Sitzungen verwalteter Agenten

Important

Dieses Feature befindet sich in der Betaversion.

Managed-Agent-Sitzungen geben Ihren Agenten einen dauerhaften, framework-unabhängigen Speicher für den Sitzungszustand: den Zustand, den ein Agent oder Framework für eine Interaktion beibehält. Am häufigsten handelt es sich dabei um den Gesprächsverlauf, das geordnete Transkript von Nachrichten, Tool-Anrufen und Ergebnissen, das ein Agent zu Beginn einer Runde liest und während der Runde anhängt. Es kann sich auch um einen anderen Zustand handeln, den ein Framework für die Interaktion speichert, zum Beispiel einen LangGraph-Graphen. Azure Databricks speichert es in Lakebase und verwaltet den Speicher für Sie, sodass Sie die Datenbank nicht bauen oder betreiben.

Note

Während der Vorschauphase werden dir die Kosten für die zugrunde liegende Lakebase-Instanz in Rechnung gestellt, die deine Sitzungen speichert. Für die Managed-Agent-Sitzungen selbst fallen keine zusätzlichen Gebühren an. Die Preise können sich im Verlauf der Vorschau ändern.

Nutze verwaltete Sitzungen, wenn du möchtest:

  • Behalten Sie den Gesprächsverlauf eines Agenten bei, damit dieser Neustarts übersteht und später fortgesetzt werden kann.
  • Rekonstruiere den vollständigen Kontext (einschließlich Werkzeugaufrufe und Argumentation) zu einer Folgenachricht.
  • Frühere Gespräche in deiner eigenen Benutzeroberfläche auflisten, fortsetzen und davon abzweigen.

Verwaltete Sitzungen speichern den Zustand einer einzelnen Interaktion (kurzfristiger sitzungsinterner Zustand). Für ein dauerhaftes, langfristiges Gedächtnis, das über Gespräche hinweg erhalten bleibt, verwenden Sie Managed Agent Memory.

Anforderungen

  • Installiere Python 3.10 oder höher, um das AgentKit SDK zu verwenden. Das AgentKit SDK ist der Databricks-Python-Client für Agenten-APIs, den die untenstehenden Beispiele verwenden. Du kannst die REST-API auch direkt aus jeder Sprache aufrufen, ohne dass du Python brauchst.

Wie verwaltete Sitzungen funktionieren

Resource-Hierarchie verwalteter Agent-Sitzungen: Ein Sitzungsspeicher enthält viele Sitzungen, und jede Sitzung enthält viele geordnete Sitzungselemente.

Verwaltete Sitzungen haben drei Stufen:

  • Ein Sitzungsspeicher ist der auf den Workspace beschränkte Container für die Sitzungen eines Agenten. Beim Erstellen eines Stores wird der zugrunde liegende Lakebase-Speicher automatisch bereitgestellt. Du wählst ein im Arbeitsbereich eindeutiges session_store_name.
  • Eine Sitzung ist eine dauerhafte Interaktion (typischerweise ein Gesprächsthread) innerhalb eines Geschäfts. Eine Sitzung wird definiert durch:
    • actor_id (erforderlich): Wem die Sitzung gehört, z. B. einem Endnutzer oder einem anderen Agenten. Es gruppiert alle Sitzungen eines Themas, sodass du sie zusammen listen und filtern kannst. Wenn Sie eine App pro Benutzer erstellen, stellen Sie die Benutzer-ID (zum Beispiel die verifizierte Endbenutzeridentität aus der Authentifizierung Ihrer App) ein, actor_id sodass die Sitzungen jedes Nutzers gruppiert bleiben. Lege ihn im vertrauenswürdigen Anwendungskontext fest, niemals anhand eines vom Modell oder Benutzer bereitgestellten Werts.
    • session_id (optional): eine vom Anrufer gewählte ID für die Interaktion. Der Dienst erzeugt eine, wenn du sie weglässt.
    • parent_session_id (optional): verknüpft eine Session mit der, von der sie abgezweigt wurde, um verzweigte Konversationen darzustellen.
  • Ein Session-Item ist ein Eintrag in der bestellten Historie einer Session. Jedes Element enthält einen undurchsichtigen, JSON-kompatiblen data Wert, wie zum Beispiel eine Nachricht, einen Werkzeugaufruf, ein Werkzeugergebnis oder einen Argumentationsblock. Azure Databricks weist jedem Element ein item_id und ein create_time zu und überprüft oder validiert deren Inhalt nicht. Elemente sind nach dem Hinzufügen unveränderlich.

Der Dienst pflegt eine deterministische Reihenfolge für die Elemente einer Sitzung und autorisiert jede Operation gegen den Session-Speicher.

Get started

Diese Beispiele richten verwaltete Sitzungen für einen Support-Mitarbeiter ein: Sie erstellen einen Sitzungsspeicher, starten eine Sitzung für ein Gespräch, fügen die Runden des Gesprächs hinzu und lesen die Historie bei einer späteren Anfrage zurück. Wählen Sie den Kunden, der zu Ihrem Projekt passt.

AgentKit SDK

Das AgentKit SDK ist der Databricks-Python-Client für Agenten-APIs, der im Paket databricks-agentbricks verteilt wird. Die Authentifizierung erfolgt über das WorkspaceClient des Databricks SDK.

  1. Installieren Sie das AgentKit SDK:

    pip install databricks-agentbricks

  2. Erstelle einen Session-Store und starte dann eine Sitzung für ein Gespräch. actor_id gibt an, wem die Unterhaltung gehört; das optionale session_id identifiziert diese Unterhaltung eindeutig:

    from databricks.sdk import WorkspaceClient
from databricks_agentkit import AgentKitClient

client = AgentKitClient(WorkspaceClient())
session_store = client.session_stores.create("support-agent-sessions")
session = session_store.add(actor_id="customer-123", session_id="case-456")

  3. Fügen Sie die Wendungen des Gesprächs hinzu, während der Agent davonläuft. Jedes Element ist ein beliebiger JSON-kompatibler Wert:

    session.append_items(
    [
        {"type": "message", "role": "user", "content": "I need help with my cluster."},
        {"type": "message", "role": "assistant", "content": "Let's take a look."},
    ]
)

  4. Bei einer Folgeanfrage laden Sie die Sitzung neu und lesen Sie die vollständige Historie, um den Kontext wiederherzustellen:

    session = session_store.get("case-456")
# Request chronological order; list_items defaults to newest-first and auto-pages.
history = [item.data for item in session.list_items(order_by="create_time asc")]

REST API

Die Clients rufen die REST-API unter /api/2.0/agents/session-stores. Rufen Sie sie direkt in anderen Sprachen als Python auf.

  1. Generiere ein OAuth-Token mit der Databricks-CLI:

    databricks auth login --host ${DATABRICKS_HOST}
export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)

  2. Erstellen Sie einen Session-Store für Ihren Agenten:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores?session_store_name=support-agent-sessions" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"description": "Support agent conversation history"}'

  3. Eine Sitzung für eine Unterhaltung starten. actor_id ist, wem es gehört; session_id identifiziert dieses Gespräch eindeutig:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions?session_id=case-456" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"actor_id": "customer-123"}'

  4. Fügen Sie eine Gesprächsrunde hinzu, während der Agent ausläuft:

    curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items:append" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"items": [{"data": {"type": "message", "role": "user", "content": "I need help with my cluster."}}]}'

  5. Lesen Sie die Geschichte chronologisch zurück, um den Kontext wiederherzustellen:

    curl -G "https://${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions/sessions/case-456/items" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" --data-urlencode "order_by=create_time asc"

Die Clients unterstützen außerdem das Entfernen des letzten Elements, das Löschen der Items einer Sitzung und das Forken einer Konversation in eine unabhängige Kopie (optional bis zu einem bestimmten Item). Das Löschen einer Sitzung mit untergeordneten Sitzungen erfordert eine Force-Option, um die Löschung kaskadierend auch auf diese anzuwenden (zum Beispiel session.delete(force=True)).

Unterstützen Sie die Sitzungen eines Frameworks für Agenten mit verwalteten Sitzungen

Agent-Frameworks wie das OpenAI Agents SDK und das Claude Agent SDK lesen den Gesprächsverlauf zu Beginn eines Durchlaufs und fügen am Ende neue Elemente hinzu. Der Sitzungsspeicher entspricht direkt diesem Muster:

Rahmenbetrieb Sitzungsspeicheraufruf
Geschichte lesen list_items in chronologischer Reihenfolge (order_by="create_time asc")
Hinzufügen von Durchlaufelementen append Die neuen Gegenstände
Letzten Punkt rückgängig machen pop das neueste Element
Lösch den Thread clear Die Punkte der Sitzung

Umfang und Zugang

Managed Sessions speichern die Elemente einer Sitzung als undurchsichtige, JSON-kompatible Werte: Der Service bleibt bestehen und gibt alles zurück, was dein Agent oder Framework anhängt, ohne es zu interpretieren. Es fügt keine Ausführungskontrollressourcen wie Durchläufe, Checkpoints oder Genehmigungen als erstklassige Konzepte hinzu, obwohl ein Framework, das einen solchen Zustand serialisiert, sie als Elemente speichern kann.

Session-Speicher sind auf den Arbeitsbereich beschränkt, und der Zugriff wird auf der Ebene des jeweiligen Speichers autorisiert. Die Felder actor_id und metadata unterstützen nur die Gruppierung und Filterung; sie gewähren keinen Zugriff und schränken ihn nicht ein. Legen Sie den actor_id aus einem vertrauenswürdigen Anwendungskontext fest, statt einen vom Modell oder Benutzer bereitgestellten Wert zu verwenden.

Um einem anderen Prinzipal, etwa dem Serviceprinzipal Ihres Agenten, die Nutzung eines Stores zu ermöglichen, gewähren Sie ihm mit dem Vorgang „grant-permission“ des Stores (session_store.grant_permission(principal_id) im AgentKit SDK) Zugriff.

Verwaltete Sitzungen und verwalteter Speicher sind unabhängig voneinander. Das Löschen einer Sitzung oder eines Sitzungsspeichers löscht keinen Speicher, der in einem Speicher gespeichert ist.

Nächste Schritte

  • Zuletzt aktualisiert um