Datenbank, Retrieval oder Sessions: Speicher für Agenten im Vergleich

Unsere Plattform nutzt eine Datenbank für strukturierte Datensätze, Retrieval für die semantische Suche in unstrukturierten Inhalten und Sessions für den Verlauf mehrteiliger Unterhaltungen. Jeder Modus ist auf ein Environment begrenzt.

In den Session-Details können Verantwortliche die gespeicherten Ereignisse prüfen und die zugehörigen Runs öffnen. Interne Metadaten und eingebettete Dateiinhalte werden dabei ausgeblendet. Dieser Leitfaden erklärt, wofür sich welcher Speichermodus eignet, wie sich die Zuordnung zu einer Session und deren TTL konfigurieren und gespeicherte Unterhaltungen debuggen lassen.

Früher Knowledge Base

Drei Optionen für Persistenz

Alle drei sind pro Environment getrennt. Jedes Environment im Projekt erhält isolierten Storage, mit getrennten Datenbeständen je Environment.

Eine einfache Faustregel: Daten für eine Tabelle gehören in die Database. Informationen, die sonst über eine Suche gefunden würden, gehören in Retrieval. Für einen Gesprächsverlauf über mehrere Anfragen hinweg eignen sich Sessions.

Datenbank: strukturierte Daten und CRUD

Jedes Environment enthält eine verwaltete Datenbank ohne festes Schema. Daten werden in Collections organisiert; jedes Dokument ist ein frei strukturiertes JSON-Objekt. Ein festes Schema, Migrationen und externes Hosting sind nicht nötig. Das System ergänzt automatisch eine UUID sowie die Zeitstempel _created_at und _updated_at.

So funktioniert es

• Collections werden automatisch erstellt, wenn ein Agent sein erstes Dokument einfügt, oder manuell im Dashboard. Namen müssen kleingeschrieben sein, mit einem Buchstaben beginnen und dürfen nur Buchstaben, Ziffern und Unterstriche enthalten.
• Dokumente sind frei strukturiert. Die Anwendung legt die Felder fest. Das System ergänzt automatisch _id, _created_at und _updated_at. Die Felder der Anwendung werden zusammen mit diesen Systemfeldern gespeichert.
• Queries unterstützen flexible JSON-Filter. Sie gleichen exakte Werte ab, setzen Vergleichsoperatoren wie $gt, $lt und $in ein, kombinieren Bedingungen mit $and und $or und fragen verschachtelte Felder per Punktnotation ab. Queries sind für schnelle Lookups in großen Collections indexiert und optimiert.

Vordefinierte Tools

Die Database enthält sechs vordefinierte Tools für eigene Tool-Wrapper:

Beispiel: Agent für die Bestellverarbeitung

Empfohlen wird, Datenbankfunktionen in domänenspezifische Funktionen zu kapseln. Der Agent ruft dann save_order oder get_customer_orders auf, statt Filter selbst zusammenzustellen. Namen von Collections und Feldzuordnungen werden einmal im Wrapper codiert und nicht im System-Prompt wiederholt.

from connic.tools import db_find, db_insert, db_update

async def save_order(customer_id: str, items: list[dict], total: float) -> dict:
    """Store a new order in the database.

    Args:
        customer_id: The customer identifier.
        items: List of order items with sku, qty, and price.
        total: Order total amount.
    """
    return await db_insert("orders", {
        "customer_id": customer_id,
        "items": items,
        "total": total,
        "status": "pending"
    })

async def get_customer_orders(customer_id: str) -> list[dict]:
    """Get all orders for a specific customer, newest first.

    Args:
        customer_id: The customer identifier.
    """
    result = await db_find(
        "orders",
        filter={"customer_id": customer_id},
        sort={"_created_at": -1}
    )
    return result.get("documents", [])

async def update_order_status(order_id: str, status: str) -> dict:
    """Update the status of an order.

    Args:
        order_id: The _id of the order to update.
        status: New status (e.g. "shipped", "delivered", "cancelled").
    """
    result = await db_update(
        "orders",
        filter={"_id": order_id},
        update={"status": status}
    )
    return result

Anschließend werden die eigenen Tools im Agenten-YAML referenziert:

version: "1.0"

name: order-processor
type: llm
model: connic/gpt-5.6-luna

system_prompt: |
  You process e-commerce orders. When you receive an order:
  1. Validate the required fields (customer, items, total)
  2. Store it using save_order
  3. When asked about an order, look it up with get_customer_orders

  Always confirm what you stored, including the _id.

tools:
  - order_tools.save_order
  - order_tools.get_customer_orders
  - order_tools.update_order_status

Die Tool-Namen beschreiben die fachlichen Aufgaben des Agenten. Er ruft save_order auf, statt die richtige Collection und Dokumentstruktur selbst zu ermitteln. Beim ersten Insert wird die Collection automatisch erstellt.

Retrieval: semantische Suche und RAG

Retrieval speichert hochgeladene Dokumente, erstellt einen semantischen Suchindex und gibt Agenten Zugriff auf Organisationswissen. Der folgende Artikel erklärt, wie Retrieval-Augmented Generation (RAG) funktioniert. Inhalte werden automatisch in Chunks geteilt und in Vektor-Embeddings umgewandelt. So kann eine Query nach „Kündigungsregeln“ ein Dokument mit dem Titel „Rückgabe- und Erstattungsrichtlinie“ finden.

So funktioniert es

• Entries sind logische Dokumente, die durch eine entry_id identifiziert werden. Lange Inhalte werden automatisch in durchsuchbare Chunks geteilt.
• Namespaces kategorisieren Einträge und funktionieren wie Ordner: policies, products, faq. Eintrags-IDs sind innerhalb eines Namespaces eindeutig.
• Semantische Suche findet die inhaltlich relevantesten Chunks. Ein Schwellenwert für min_score von standardmäßig 0,3 filtert Ergebnisse mit geringer Ähnlichkeit aus. Ergebnisse werden nach Relevanz sortiert.
• Mehrere Content-Typen werden unterstützt: Plain Text, PDF-Dateien, deren Seiten extrahiert, in Chunks geteilt und eingebettet werden, sowie Bilder, die Vision KI-Modelle analysieren und deren extrahierte Inhalte eingebettet werden.

Vordefinierte Tools

Beispiel: Support-Agent mit Retrieval

Wie bei der Datenbank empfiehlt es sich, Retrieval Tools in domänenspezifische Funktionen zu kapseln. Der Agent ruft dann search_solutions auf, statt direkt mit Namespaces und Eintrags-IDs zu arbeiten. Die Routing-Logik wird einmal im Wrapper codiert, damit sich der Agent auf seine Aufgabe konzentriert.

from connic.tools import retrieval_query, retrieval_store

async def search_solutions(query: str) -> list[dict]:
    """Search the support retrieval for solutions.

    Args:
        query: Describe the customer's issue.
    """
    result = await retrieval_query(query, namespace="solutions", max_results=3)
    return result.get("results", [])

async def save_solution(content: str, entry_id: str | None = None) -> dict:
    """Store a reusable solution for future tickets.

    Args:
        content: The solution text including the problem description.
        entry_id: Optional stable ID for future updates (e.g. "password-reset-steps").
    """
    return await retrieval_store(
        content, namespace="solutions", entry_id=entry_id
    )

async def search_policies(query: str) -> list[dict]:
    """Look up company policies relevant to a support question.

    Args:
        query: Describe what policy information you need.
    """
    result = await retrieval_query(query, namespace="policies", max_results=3)
    return result.get("results", [])

version: "1.0"

name: support-agent
type: llm
model: connic/gpt-5.6-terra

system_prompt: |
  You are a customer support agent. For every question:
  1. Search for existing solutions using search_solutions
  2. If needed, check company policies with search_policies
  3. If you solve a new problem, store the solution with save_solution
     so future tickets benefit from it

tools:
  - support_tools.search_solutions
  - support_tools.save_solution
  - support_tools.search_policies

Der Agent muss Namespaces und Eintrags-IDs nicht mehr kennen. Er ruft search_solutions("password reset not working") auf und erhält relevante Ergebnisse. Die semantische Suche verarbeitet Synonyme und Paraphrasen automatisch.

Sessions: persistenter Gesprächsverlauf

Sessions lösen ein anderes Problem als Datenbank oder Retrieval. Sie geben einem Agenten über mehrere Requests hinweg einen gespeicherten Verlauf der laufenden Unterhaltung. Ohne Sessions ist jede Nachricht unabhängig: Der Agent beginnt jedes Mal neu und weiß nicht, was zuvor gesagt wurde.

Mit aktivierten Sessions verwaltet der Agent den Gesprächsverlauf automatisch. Nachrichten, Antworten und Tool-Aktivitäten werden erfasst und beim nächsten Request mit derselben Session-Identität verwendet. Dieses Verhalten wird in YAML konfiguriert, statt Speicher-Tools aufzurufen.

Konfiguration

Das Agent-YAML erhält einen session-Block mit zwei Feldern:

• key: ein Ausdruck, der festlegt, welcher Wert eine Unterhaltung identifiziert. Mit context.<field> lässt sich aus dem Middleware-Kontext lesen, mit input.<field> aus den Nutzdaten der Anfrage. Für jede Anfrage derselben Unterhaltung muss dieser Ausdruck denselben Wert liefern.
• ttl: optionale Gültigkeitsdauer in Sekunden. Sie funktioniert als Inaktivitäts-Timeout: Jede Aktualisierung setzt den Ablaufzeitpunkt neu. Das Minimum beträgt 60 Sekunden. Ohne Angabe laufen Sessions nie ab.

Connic bildet die gespeicherte Session-ID aus Agentenname und aufgelöstem Key. Storage identifiziert den Datensatz anhand dieser ID, der Agentenanwendung und der Runtime-Nutzeridentität. Jede Unterhaltung benötigt einen eindeutigen Schlüssel. Das Dashboard verwendet alle drei gespeicherten Felder, wenn es die Session und zugehörige Runs lädt.

Beispiel: Telegram-Chatbot

Ein Telegram-Bot kann die Chat-ID aus dem Payload seiner Verbindung verwenden, um pro Chat eine eigene Unterhaltung zu verwalten:

version: "1.0"

name: telegram-bot
type: llm
model: connic/gpt-5.6-terra

system_prompt: |
  You are a helpful personal assistant on Telegram.
  You can reference earlier messages in the conversation.

session:
  key: input.chat_id
  ttl: 86400    # 24 hours

Jede eindeutige chat_id erhält eine eigene Session. Sendet derselbe Chat eine weitere Nachricht, bekommt der Agent den gespeicherten Session-Kontext. Nach 24 Stunden Inaktivität läuft die Session ab und die nächste Nachricht beginnt eine neue Unterhaltung.

Persistente Sessions prüfen und debuggen

Ein Datensatz unter Storage > Sessions zeigt die genaue Session-ID, den Agenten, die angezeigte Nachrichtenanzahl, Erstellungszeit, letzte Aktualisierung und Ablaufzeitpunkt. Die Gesprächsansicht zeigt die gespeicherten Inhalte von Nutzer-, Assistenten-, System- und Tool-Nachrichten, soweit sie angezeigt werden können.

• Aufgezeichneter Text und JSON erscheinen direkt in der Unterhaltung. Attachments zeigen Dateiname, MIME-Typ und Größe, ohne Inline-Dateidaten offenzulegen.
• Tool-Namen und Argumente stehen neben aufgezeichneten Ergebnissen oder Fehlern. Reasoning erscheint nur, wenn es unmaskiert gespeichert wurde; andernfalls markiert der Drawer es als redacted.
• Die Tabelle der zugehörigen Runs berücksichtigt gemeinsam die Session-ID, die Agentenanwendung und die Nutzeridentität. Über einen Eintrag lässt sich der entsprechende Run öffnen.

Wann welcher Storage passt

Entscheidend sind die Art der Daten und die gewünschte Zugriffsweise.

Zugriffskontrolle im Agent-YAML

Datenbank und Retrieval unterstützen direkt im Agent-YAML granulare Zugriffskontrollen. Die Konfiguration kann die Collections oder Namespaces einschränken, auf die ein Agent zugreifen darf, sowie Schreib- und Löschoperationen verhindern. Zugriffskontrolle gilt unabhängig davon, ob der Agent vordefinierte Tools direkt oder über eigene Wrapper verwendet.

Datenbank-Zugriffskontrolle

tools:
  - order_tools.save_order
  - order_tools.get_customer_orders

# Restrict database access
database:
  collections:
    orders:
      prevent_delete: true    # can read and write, but not delete
    customers: {}             # full access, no restrictions
  prevent_delete: false       # global default
  prevent_write: false        # global default

Wenn collections gesetzt ist, kann der Agent nur auf diese Collections zugreifen. Jeder Versuch, eine nicht aufgelistete Collection abzufragen oder zu beschreiben, wird blockiert. Fehlt collections, sind alle Collections zugänglich.

Für eine einfachere Konfiguration lassen sich Collections auch als Liste übergeben:

database:
  collections: [orders, customers]
  prevent_delete: true

Retrieval Zugriffskontrolle

Retrieval Zugriffskontrolle funktioniert genauso, ist jedoch auf Namespaces statt Collections begrenzt:

tools:
  - support_tools.search_solutions
  - support_tools.save_solution
  - support_tools.search_policies

# Restrict retrieval access
retrieval:
  namespaces:
    solutions:
      prevent_delete: true    # can query and store, but not delete
    policies:
      prevent_write: true     # read-only access to policies
  prevent_delete: false
  prevent_write: false

Das ist besonders für Multi-Agent-Setups nützlich. Ein Support-Agent kann Read-only-Zugriff auf den Namespace policies und vollständigen Zugriff auf solutions erhalten, während ein Admin-Agent beide verwaltet.

Storage im Dashboard verwalten

Alle drei Storage-Systeme haben im Connic-Dashboard eigene Seiten im Menü Storage. Dort lassen sich die Daten ohne Code prüfen, verwalten und debuggen.

Das Dashboard zeigt auf der Seite Billing außerdem die Storage-Nutzung mit Fortschrittsbalken für jedes Limit. Sie zeigen, wie nah die aktuelle Nutzung an der Kapazität des Tarifs liegt.

Retrieval befüllen

Inhalte gelangen auf zwei Wegen in Retrieval:

• 1.Upload im Dashboard: Auf der Seite Retrieval lassen sich Dateien wie PDF, TXT, MD, PNG, JPG, GIF und WEBP hochladen oder Texte direkt einfügen. Dateien werden asynchron verarbeitet. Der Fortschritt steht in der Liste der Upload-Jobs.
• 2.Tool-Aufrufe von Agenten: Agenten mit Zugriff auf retrieval_store können während einer Ausführung direkt oder über einen Wrapper in Retrieval schreiben. So lernen Agenten aus Interaktionen: Sie entdecken eine Lösung und speichern sie für das nächste Mal.

Bewährte Vorgehensweisen

Tariflimits

Für Datenbank und Retrieval gelten je nach Tarif Limits für Collections, Dokumente und Einträge. Sie werden automatisch durchgesetzt und vor jeder Schreiboperation geprüft. Ist ein Limit erreicht, erhält der Agent eine eindeutige Fehlermeldung.

Aktuelle Tariflimits stehen auf der Preisseite und auf der Seite Billing in den Projekteinstellungen. Dort wird die aktuelle Nutzung mit Fortschrittsbalken für jedes Limit angezeigt.

Vollständiges Beispiel: Support-Agent mit allen drei Optionen

Dieser vollständige Agent nutzt alle drei Optionen. Sessions speichern den Gesprächsverlauf, die Datenbank verwaltet Support-Tickets und Retrieval sucht nach Lösungen.

version: "1.0"

name: support-agent
type: llm
model: connic/gpt-5.6-terra

system_prompt: |
  You are a customer support agent. For every incoming ticket:

  1. Search for existing solutions using search_solutions
  2. Check company policies if relevant with search_policies
  3. Create a ticket record with save_ticket
  4. If you discover a new solution, save it with save_solution

temperature: 0.5
max_iterations: 15

# Persistent conversation history per customer
session:
  key: context.customer_id
  ttl: 86400

tools:
  - support_tools.search_solutions
  - support_tools.save_solution
  - support_tools.search_policies
  - ticket_tools.save_ticket
  - ticket_tools.get_ticket
  - ticket_tools.update_ticket

# Only allow access to what this agent needs
database:
  collections:
    tickets: {}
  prevent_delete: true

retrieval:
  namespaces:
    solutions: {}
    policies:
      prevent_write: true
      prevent_delete: true

Dieser Agent erinnert sich an die Unterhaltung über Sessions, kann Tickets in der Datenbank erstellen und aktualisieren, Dokumentation per Retrieval durchsuchen und dort neue Lösungen speichern. Er kann keine Tickets löschen, nicht in den Namespace policies schreiben und nicht auf andere als die aufgelisteten Collections oder Namespaces zugreifen.

Erste Schritte

• 1.Den passenden Speicher für die Daten auswählen. Strukturierte Datensätze gehören in die Datenbank, unstrukturierte Texte für die Suche nach Bedeutung in Retrieval und Gesprächsverlauf in Sessions.
• 2.Eigene Tool-Wrapper schreiben. Vordefinierte Tools aus connic.tools lassen sich in domänenspezifische Funktionen kapseln. Das gibt dem Agenten eine übersichtlichere Schnittstelle und bildet die Geschäftslogik einmalig ab.
• 3.Retrieval vorab befüllen. Dokumentation, FAQs und Richtlinien vor dem Deployment über das Dashboard hochladen. Agenten funktionieren besser, wenn Retrieval bereits Inhalte enthält.
• 4.Zugriffskontrollen festlegen. Collections und Namespaces pro Agent begrenzen. Das Prinzip der geringsten Rechte lässt sich über die Optionen prevent_delete und prevent_write durchsetzen.
• 5.Bereitstellen und prüfen. Im Dashboard kontrollieren, ob der Agent die richtigen Daten liest und schreibt. Dazu gehören Collection-Inhalte auf der Datenbankseite, semantische Abfragen auf der Retrieval-Seite und eine persistente Session samt Unterhaltung und zugehöriger Ausführungsdetails.

Die vollständige API-Referenz und Syntax für Abfragefilter steht in der Dokumentation der Datenbank Tools, in der Dokumentation der Retrieval Tools sowie in der Anleitung zum Konfigurieren persistenter Sessions. Für den Einstieg in Connic eignet sich der Quickstart-Leitfaden, mit dem sich ein erster Agent bereitstellen lässt.