Hinweis
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, sich anzumelden oder das Verzeichnis zu wechseln.
Für den Zugriff auf diese Seite ist eine Autorisierung erforderlich. Sie können versuchen, das Verzeichnis zu wechseln.
Important
Dieses Feature befindet sich in der Betaversion. Um es zu verwenden, muss ein Workspace-Administrator Agent Memory Sessions auf der Seite Vorschau aktivieren. Siehe Manage Azure Databricks Previews.
Agent-Sitzungen geben Ihren Agenten einen dauerhaften, framework-agnostischen Speicher für den Sitzungszustand: den Zustand, den ein Agent oder Framework für eine Interaktion hä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 Agentensitzungen selbst fallen keine zusätzlichen Gebühren an. Die Preise können sich im Verlauf der Vorschau ändern.
Nutzen Sie Agentensitzungen, wenn Sie Folgendes tun möchten:
- 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.
Agent-Sitzungen speichern den Zustand einer einzelnen Interaktion (kurzfristig, während der Sitzung). Für das Langzeitgedächtnis, das über Gespräche hinweg anhält, verwenden Sie 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.
- Um die REST-API-Beispiele zu verwenden, installieren Sie die Databricks-CLI (zur Generierung eines OAuth-Tokens),
curl, undjq.
Wie Agentensitzungen funktionieren
Agentensitzungen 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 eine innerhalb des Workspace eindeutige Store-ID und nutzt sie, um in späteren Aufrufen auf den Store zu verweisen. Geben Sie die Store-ID wie folgt durch:
- Das Argument
nameim AgentKit SDK. - Der Abfrageparameter
session_store_idin der REST-API.
- Das Argument
- 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_idsodass 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): ordnet die Sitzung als untergeordnete Sitzung einer anderen Sitzung im Store zu, wie zum Beispiel der Konversation eines Unteragenten. Stelle es ein, wenn du die Sitzung erstellst.
-
- Ein Session-Item ist ein Eintrag in der bestellten Historie einer Session. Jedes Element enthält einen undurchsichtigen, JSON-kompatiblen
dataWert, wie zum Beispiel eine Nachricht, einen Werkzeugaufruf, ein Werkzeugergebnis oder einen Argumentationsblock. Azure Databricks weist jedem Element einitem_idund eincreate_timezu 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 Agentensitzungen für einen Support-Mitarbeiter ein: sie erstellen einen Session-Store, starten eine Sitzung für ein Gespräch, fügen die Runden des Gesprächs hinzu und lesen die Historie auf einer späteren Anfrage zurück. Wählen Sie den Kunden, der zu Ihrem Projekt passt.
Store-IDs sind innerhalb eines Arbeitsbereichs eindeutig. Wenn du beide Tabs ausführst oder die ID bereits belegt ist, wähle eine andere ID oder lösche zuerst den bestehenden Store. Store-Antworten enthalten außerdem eine dienstzugewiesene UUID in session_store_id. Spätere Aufrufe verwenden die von dir gewählte Store-ID.
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.
Installieren Sie das AgentKit SDK:
pip install databricks-agentbricksDas
databricks-agentbricksPaket bietet dasdatabricks_agentkitPython-Modul.Erstelle einen Session-Store und starte dann eine Sitzung für ein Gespräch.
actor_idgibt an, wem die Unterhaltung gehört; das optionalesession_ididentifiziert 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-sdk") session = session_store.add(actor_id="customer-123", session_id="case-456")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."}, ] )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.
Setzen Sie
DATABRICKS_HOSTauf die URL Ihres Arbeitsbereichs, einschließlichhttps://, und generieren Sie dann ein OAuth-Token mit der Databricks-CLI:export DATABRICKS_HOST=https://<workspace-url> databricks auth login --host ${DATABRICKS_HOST} export DATABRICKS_TOKEN=$(databricks auth token | jq -r .access_token)Erstellen Sie einen Session-Store für Ihren Agenten:
curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/session-stores?session_store_id=support-agent-sessions-rest" \ -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \ -d '{"description": "Support agent conversation history"}'Eine Sitzung für eine Unterhaltung starten.
actor_idist, wem es gehört;session_ididentifiziert dieses Gespräch eindeutig:curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions?session_id=case-456" \ -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \ -d '{"actor_id": "customer-123"}'Fügen Sie eine Gesprächsrunde hinzu, während der Agent ausläuft:
curl -X POST "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/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."}}]}'Lesen Sie die Geschichte chronologisch zurück, um den Kontext wiederherzustellen:
curl -G "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions/case-456/items" \ -H "Authorization: Bearer ${DATABRICKS_TOKEN}" --data-urlencode "order_by=create_time asc"Die Antwort gibt Elemente in
session_items, bis zupage_sizepro Anfrage zurück (standardmäßig 10, maximal 100). Wenn noch mehr Elemente übrig sind, enthält sienext_page_token. Übergebe diesen Wert alspage_tokenund wiederhole das, bis die Antwort keinenext_page_tokenhat. Dielist_items-Seiten des AgentKit-SDK für Sie.Zum Beispiel liest diese Schleife den vollständigen Verlauf jeweils 100 Elemente auf einmal aus:
PAGE_TOKEN="" while true; do RESPONSE=$(curl -s -G "${DATABRICKS_HOST}/api/2.0/agents/session-stores/support-agent-sessions-rest/sessions/case-456/items" \ -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \ --data-urlencode "order_by=create_time asc" --data-urlencode "page_size=100" \ ${PAGE_TOKEN:+--data-urlencode "page_token=${PAGE_TOKEN}"}) echo "${RESPONSE}" | jq -c '.session_items[]?.data' PAGE_TOKEN=$(echo "${RESPONSE}" | jq -r '.next_page_token // empty') [ -z "${PAGE_TOKEN}" ] && break done
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). Ein Fork hat keine übergeordnete Sitzung, und das Löschen der Quellsitzung löscht sie nicht. Das Löschen einer Sitzung löscht immer ihre Kind-Sitzungen und deren Elemente.
Eine Sitzung eines Agenten-Frameworks mit Agentensitzungen unterlegen
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 | AgentKit SDK-Call |
|---|---|
| Geschichte lesen | list_items(order_by="create_time asc") |
| Hinzufügen von Durchlaufelementen | append_items(items) |
| Letzten Punkt rückgängig machen | pop_item() |
| Lösch den Thread | clear_items() |
Umfang und Zugang
Agent-Sitzungen speichern die Elemente einer Sitzung als undurchsichtige, JSON-kompatible Werte: Der Dienst speichert 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 Store-Zugriffskontrolle gilt für die Sessions eines Stores. Jeder Workspace-Nutzer kann Session-Stores auflisten und abrufen, einschließlich ihrer IDs und Beschreibungen. 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. Nur der Ersteller des Shops oder ein Workspace-Admin kann Zugriff gewähren. Siehe Berechtigungen verwalten für Agentenspeicher und Sitzungsspeicher für Berechtigungsstufen, unterstützte Operationen und Beispiele.
Agentensitzungen und Agentenspeicher sind unabhängig voneinander. Das Löschen einer Sitzung oder eines Sitzungsspeichers löscht keinen Speicher, der in einem Speicher gespeichert ist. Um aus den Sitzungen in einem Store ein Langzeitgedächtnis aufzubauen, erstellen Sie eine Speicherpipeline.