Connic Run Context: Agenten mit den richtigen Daten ausführen

Connic Run Context ist ein gemeinsamer Speicher für eine Agentenausführung. Darin lassen sich selbst definierte Werte hinterlegen, die Middleware, Tools und Hooks im gesamten Ablauf nutzen können, ohne dass die KI sie kennen oder als Argumente übergeben muss. Die Anwendung legt fest, welche Daten der Kontext enthält und welche davon in den Prompt einfließen.

Eigene Daten im gesamten Ablauf nutzen

Der Run Context ist ein Python-Dictionary mit frei wählbaren Anwendungsfeldern. Darin können einzelne Texte und Zahlen ebenso stehen wie Listen oder verschachtelte Objekte.

Zu Beginn eines Runs stehen die eingehenden Daten unter context["payload"] bereit. Eine Middleware, also Python-Code vor oder nach der Verarbeitung durch den Agenten, kann Werte daraus übernehmen und weitere Daten aus der Anwendung ergänzen. Die Tools greifen während des Runs auf denselben Kontext zu. So kann ein Wert einmal bereitgestellt und in mehreren Arbeitsschritten verwendet werden.

Aktivierte Input-Guardrails verarbeiten die eingehenden Daten vor der Middleware. Dazu können auch Schwärzungen gehören, die anschließend in context["payload"] berücksichtigt sind.

Auch Zwischenergebnisse finden dort Platz. Ein Tool kann etwa festhalten, welchen Datensatz es bearbeitet hat. Ein späteres Tool oder die Middleware nach der Verarbeitung kann diesen Wert aufgreifen. Dasselbe gilt für Tool-Hooks, die eigenen Code vor oder nach einem Tool-Aufruf ausführen.

Anwendungsdaten für einen Abrechnungsassistenten bereitstellen

Ein Abrechnungsassistent verwendet in diesem Beispiel drei selbst definierte Felder: customer_id, locale und subscription_tier. Das Backend der Anwendung sendet sie zusammen mit einer Frage an einen Connic-Webhook, der mit dem LLM-Agenten billing-assistant verbunden ist. Die Kunden-ID und der Tarif stammen aus dem Kundenkonto der Beispielanwendung.

{
  "customer_id": "cus_demo_42",
  "locale": "en-GB",
  "subscription_tier": "business",
  "question": "Has invoice INV-1042 been paid?"
}

In der Datenbank-Collection invoices liegt dazu eine Beispielrechnung mit invoice_id: "INV-1042", customer_id: "cus_demo_42" und status: "paid". Das Tool kann damit später den Zahlungsstatus zur Frage nachschlagen.

Die Middleware bereitet den Kontext und die Nachricht vor

Die Datei middleware/billing-assistant.py gehört zum Agenten billing-assistant. Connic ordnet Middleware über diesen Dateinamen zu und ruft before() vor der Verarbeitung durch den Agenten auf. Die Funktion übernimmt die drei Werte aus context["payload"] in eigene Kontextfelder und gibt nur die Frage als Nutzernachricht weiter.

from typing import Any
from connic import StopProcessing


async def before(
    content: dict[str, Any], context: dict[str, Any]
) -> dict[str, Any]:
    payload = context["payload"]
    required = ("customer_id", "locale", "subscription_tier", "question")
    if not isinstance(payload, dict) or any(
        not isinstance(payload.get(key), str) or not payload[key].strip()
        for key in required
    ):
        raise StopProcessing("Missing or invalid support request")

    facts: dict[str, str] = {
        "customer_id": payload["customer_id"],
        "locale": payload["locale"],
        "subscription_tier": payload["subscription_tier"],
    }
    context.update(facts)
    return {"role": "user", "parts": [{"text": payload["question"]}]}


async def after(response: str, context: dict[str, Any]) -> str:
    context["invoice_lookup_attempted"] = "last_invoice_id" in context
    return response

Die Prüfung am Anfang erwartet für die vier Felder jeweils einen nicht leeren Text. Fehlt eine Angabe, beendet StopProcessing den Run vor dem Modellaufruf. Nach erfolgreicher Prüfung ergänzt context.update(facts) die Werte im gemeinsamen Dictionary. Die zurückgegebene Nachricht enthält die Frage, mit der die KI arbeiten soll; Kunden-ID, Sprache und Tarif bleiben über den Kontext für den weiteren Ablauf verfügbar.

Dieses Beispiel verarbeitet eine Textfrage. Bei Nachrichten mit Anhängen kann die Middleware neben dem Text auch die zugehörigen Dateiteile weitergeben. Die Nachrichtenformate der Middleware beschreiben, wie sich solche Inhalte zusammenstellen lassen.

Nach der Antwort ruft Connic after() mit demselben Kontext auf. Die Funktion prüft, ob das Tool last_invoice_id gesetzt hat, und hält unter invoice_lookup_attempted fest, ob eine Rechnungsabfrage versucht wurde. Die Antwort selbst gibt sie unverändert zurück.

Ein Tool nutzt Daten, die die KI nicht mitliefern muss

Für die Rechnungsabfrage erhält get_invoice_status die Rechnungsnummer von der KI und liest die Kunden-ID aus dem Kontext. Die Funktion verwendet dafür den Parameter context: dict[str, Any]:

from typing import Any
from connic.tools import db_find


async def get_invoice_status(
    invoice_id: str, context: dict[str, Any]
) -> dict[str, Any]:
    """Look up payment status for an invoice in the current account.

    Args:
        invoice_id: Invoice reference from the billing question.
    """
    context["last_invoice_id"] = invoice_id
    result = await db_find(
        "invoices",
        filter={
            "invoice_id": invoice_id,
            "customer_id": context["customer_id"],
        },
        fields=["invoice_id", "status"],
        limit=1,
    )
    if "error" in result:
        return {"error": "Invoice lookup unavailable"}
    if not result["documents"]:
        return {"error": "Invoice not found"}
    invoice = result["documents"][0]
    return {"invoice_id": invoice["invoice_id"], "status": invoice["status"]}

Beim Tool-Aufruf übergibt Connic den Parameter context automatisch. Er gehört nicht zu den Argumenten, die das Modell ausfüllt. Die KI liefert nur invoice_id; der Tool-Code ergänzt den Kundenfilter aus context["customer_id"].

Das Tool liest mit db_find aus der Collection invoices und gleicht dabei Rechnungsnummer und Kunden-ID ab. Bei einem Treffer gibt es Rechnungsnummer und Zahlungsstatus zurück. Eine fehlgeschlagene Datenbankabfrage liefert Invoice lookup unavailable; eine Suche ohne Treffer liefert Invoice not found. Gleichzeitig hält das Tool die abgefragte Rechnungsnummer unter last_invoice_id im Kontext fest. Dieser Wert steht anschließend auch anderen Tools und der Middleware zur Verfügung.

Ausgewählte Werte für die Antwort verwenden

Manche Kontextwerte sollen auch die Antwort beeinflussen. Im Abrechnungsbeispiel legt die Anwendung über den Prompt fest, welche Sprache und welchen Tarif das Modell berücksichtigen soll. Dafür stehen die Feldnamen als Platzhalter im System-Prompt. Der folgende Auszug aus agents/billing-assistant.yaml verbindet den Prompt mit dem Tool und dem Zugriff auf die Rechnungs-Collection. Name, Version, Agententyp und Modell stehen in der übrigen Agentenkonfiguration.

system_prompt: |
  Answer billing questions in locale {locale}.
  The customer's subscription tier is {subscription_tier}.
  Use get_invoice_status to check invoice payment status.
  Report lookup errors without guessing a payment status.

tools:
  - billing.get_invoice_status

database:
  collections:
    invoices:
      prevent_write: true
      prevent_delete: true

Connic setzt vor dem Modellaufruf en-GB für {locale} und business für {subscription_tier} ein. Die Kunden-ID liest das Tool für den Kundenfilter aus dem Kontext. Die Anwendung entscheidet, welche Kontextwerte sie zusätzlich in den Prompt aufnimmt.

Die ersten beiden Anweisungen lauten dann „Answer billing questions in locale en-GB.“ und „The customer's subscription tier is business.“ Der Eintrag unter tools macht billing.get_invoice_status für den Agenten verfügbar. Die Datenbankkonfiguration erlaubt das Lesen aus invoices und sperrt Schreib- und Löschzugriffe auf diese Collection.

Den Kontext durch den Run verfolgen

Mit einer als bezahlt gespeicherten Beispielrechnung ergibt sich bei einem Aufruf von get_invoice_status folgender Ablauf:

Nach der Ausführung speichert Connic den abschließenden Kontext mit dem Run. Die selbst definierten Felder sehen im Beispiel so aus:

{
  "customer_id": "cus_demo_42",
  "locale": "en-GB",
  "subscription_tier": "business",
  "last_invoice_id": "INV-1042",
  "invoice_lookup_attempted": true
}

In den Run-Details zeigt der Bereich „Context“ die gespeicherten Werte. Zusammen mit den Nachrichten und Tool-Aufrufen im Trace lässt sich nachvollziehen, welche Daten die Anwendung bereitgestellt hat, was die KI erhalten hat und welche Werte im Lauf der Verarbeitung hinzugekommen sind. Die API für Run-Details stellt diese Daten im Feld run_context bereit.

Neben den eigenen Feldern enthält der Kontext die eingehenden Daten unter payload und Angaben zum Run, etwa run_id, agent_name, connector_id und timestamp. Vor dem Aufruf von after() ergänzt Connic außerdem den Tokenverbrauch unter token_usage und die bisherige Laufzeit unter duration_ms. Die Middleware kann diese Angaben gemeinsam mit den Ergebnissen der Tools auswerten.

Wie Änderungen während und nach dem Run weiterwirken

Middleware, Tools und Tool-Hooks lesen und verändern dasselbe Dictionary. Schreibt ein Tool einen Wert hinein, können nachfolgende Aufrufe ihn weiterverwenden. Tool-Hooks können außerdem Parameter vor einer Abfrage oder Ergebnisse danach bearbeiten und dabei auf die vorhandenen Kontextwerte zugreifen.

Für parallel ausgeführte Tools gibt es keine festgelegte Reihenfolge der Schreibzugriffe. Wenn ein Arbeitsschritt das Ergebnis eines anderen benötigt, müssen die Aufrufe entsprechend nacheinander erfolgen. Connic speichert den Kontext als JSON. Die Werte der eigenen Felder müssen sich dafür als JSON speichern lassen.

Für den System-Prompt verwendet Connic die Werte, die vor dem Modellaufruf bereitstehen. Soll ein späteres Tool-Ergebnis die laufende Antwort beeinflussen, gibt das Tool die betreffenden Daten an das Modell zurück. In diesem Beispiel erhält die KI deshalb den Zahlungsstatus als Tool-Ergebnis, während die Rechnungsnummer zusätzlich für die After-Middleware im Kontext bleibt.

Jeder neue Run erhält einen eigenen Kontext; der gespeicherte Kontext hält die Werte der abgeschlossenen Ausführung fest. Bei fortgesetzten Gesprächen bewahrt Connic außerdem den Gesprächsverlauf und die zuvor für Prompts übernommenen Werte auf. Die aktuellen Kontextwerte ersetzen dort gleichnamige Einträge. Einträge, die im neuen Run fehlen, können aus dem bisherigen Gespräch erhalten bleiben. Die Middleware kann die für den Prompt benötigten Werte bei jedem Run setzen und so etwa eine geänderte Spracheinstellung übernehmen.

Fehlt ein Wert auch dort, bleibt ein einfacher Platzhalter wie {locale} als Text im Prompt stehen. Bei verschachtelten Zugriffen oder Formatangaben können fehlende Werte einen Formatierungsfehler auslösen. Im Beispiel prüft die Middleware die Spracheinstellung vorher und stoppt den Run bei einer fehlenden Angabe. Für optionale Felder kann sie stattdessen einen passenden Standardwert setzen.