Relace agenta

Important

Tato funkce je v beta verzi.

Agentní relace poskytují vašim agentům trvalé, frameworkově nezávislé úložiště pro stav relace: stav, který agent nebo framework uchovává pro jednu interakci. Nejčastěji se jedná o historii konverzace, uspořádaný přepis zpráv, volání nástrojů a výsledky, které agent čte na začátku tahu a přidává k nim během běhu. Může to být také jakýkoli jiný stav, ve kterém rámec pro interakci přetrvává, například LangGraph graf. Azure Databricks ji ukládá v Lakebase a spravuje úložiště za vás, takže databázi nesestavujete ani neprovozujete.

Note

Během preview vám je účtována podkladová instance Lakebase, která ukládá vaše relace. Za samotné sezení agentů se neúčtují žádné další poplatky. Ceny se mohou v průběhu ukázky měnit.

Používejte relace agenta, když chcete:

  • Udržujte historii konverzací agenta, aby přežila restarty a mohla být později obnovena.
  • Zrekonstruujte celý kontext (včetně volání nástrojů a odůvodnění) v navazující zprávě.
  • Vyjmenuj, shrni a rozvětvuj konverzace ze svého vlastního UI.

Relace agenta uchovávají stav jedné interakce (krátkodobý stav v rámci relace). Pro dlouhodobou paměť, která přetrvává napříč konverzacemi, použijte paměť agenta.

Požadavky

  • Nainstalujte Python 3.10 nebo novější, abyste mohli používat AgentKit SDK. AgentKit SDK je Databricks Python klient pro agentní API, který používají níže uvedené příklady. REST API můžete také volat přímo z jakéhokoliv jazyka, bez nutnosti Python.

Jak fungují relace agenta

Hierarchie zdrojů relací agentů: úložiště relací obsahuje mnoho relací a každá relace obsahuje mnoho uspořádaných položek relace.

Relace agenta mají tři úrovně:

  • Úložiště relací je kontejner vymezený pro daný pracovní prostor pro relace agenta. Vytvoření obchodu automaticky zajišťuje zálohující úložiště Lakebase. Vyberete si unikátní session_store_namepracovní prostředí.
  • Relace je jedna trvalá interakce (obvykle konverzační vlákno) v obchodě. Zasedání je identifikováno pro:
    • actor_id (povinné): komu relace patří, například koncovému uživateli nebo jinému agentovi. Seskupuje všechny sezení jednoho předmětu, takže je můžete seřadit a filtrovat dohromady. Když vytváříte aplikaci pro jednotlivé uživatele, nastavte actor_id na ID uživatele (například ověřenou identitu koncového uživatele z ověřování ve vaší aplikaci), aby relace jednotlivých uživatelů zůstaly seskupené. Nastavte ho z důvěryhodného kontextu aplikace, nikdy z hodnoty dodané modelem nebo uživatelem.
    • session_id (volitelné): ID volajícího pro interakci. Služba vygeneruje jeden, když ho vynecháte.
    • parent_session_id (volitelné): Spojuje relaci s tou, ze které byla odvetvena, aby reprezentovala větvené konverzace.
  • Položka relace je jedna položka v seřazené historii relace. Každý prvek obsahuje neprůhlednou, JSON-kompatibilní data hodnotu, například zprávu, volání nástroje, výsledek nástroje nebo blok uvažování. Azure Databricks přiřazuje každé položce item_id a create_time a nekontroluje ani neověřuje její obsah. Předměty jsou po připojení neměnné.

Služba udržuje deterministické pořadí pro položky relace a autorizuje každou operaci vůči úložišti relace.

Začínáme

Tyto příklady nastavují relace agenta pro agenta podpory: vytvoří úložiště relací, spustí relaci pro jednu konverzaci, přidá repliky konverzace a při pozdějším požadavku přečte historii. Vyberte si klienta, který odpovídá vašemu projektu.

AgentKit SDK

AgentKit SDK je Python klient Databricks pro agentní API, distribuovaný v balíčkudatabricks-agentbricks. Autentizuje se pomocí Databricks SDK WorkspaceClient.

  1. Nainstalujte AgentKit SDK:

    pip install databricks-agentbricks

  2. Vytvořte úložiště relací a poté spusťte relaci pro jednu konverzaci. actor_id je komu konverzace patří; volitelná session_id varianta jednoznačně identifikuje tuto konverzaci:

    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. Přidej různé obraty rozhovoru, zatímco agent utíká. Každý prvek je libovolná hodnota kompatibilní s JSON:

    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. Při následném požadavku načtěte relaci a přečtěte si její celou historii, abyste znovu vytvořili kontext:

    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

Klienti volají REST API pod adresou /api/2.0/agents/session-stores. Volejte ji přímo v jiných jazycích než v Pythonu.

  1. Vygenerujte OAuth token pomocí Databricks CLI:

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

  2. Vytvořte pro svého agenta úložiště relací:

    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. Začněte sezení pro jeden rozhovor. actor_id označuje, komu patří; session_id jednoznačně identifikuje tuto konverzaci:

    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. Přidejte konverzační tah, zatímco agent běží:

    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. Přečtěte si historii zpět chronologicky, abyste znovu vytvořili kontext:

    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"

Klienti také podporují odstranění nejnovější položky, vyčištění položek v relaci a rozdělení konverzace do samostatné kopie (volitelně až do konkrétní položky). Odstranění relace, která má podřízené relace, vyžaduje použití volby force, aby se odstranění kaskádovitě vztáhlo i na ně (například session.delete(force=True)).

Podpořte relaci agentního frameworku pomocí agentních relací

Agentní frameworky jako OpenAI Agents SDK a Claude Agent SDK čtou historii konverzace na začátku běhu a na konci přidávají nové položky. Úložiště relací přímo odpovídá tomuto vzoru:

Fungování frameworku Volání úložiště relace
Přečtěte si historii list_items v chronologickém pořadí (order_by="create_time asc")
Přidat položky pro otočení append Nové položky
Zrušit poslední položku pop Nejnovější položka
Vyčistěte vlákno clear Položky zasedání

Rozsah a přístup

Relace agenta ukládají položky relace jako neprůhledné hodnoty kompatibilní s JSON: služba uchovává a vrací cokoli, co váš agent nebo framework přidá, aniž by to interpretovala. Nepřidává zdroje řízení vykonávání jako běhy, kontrolní body nebo schvalování jako prvotřídní koncepty, i když framework, který takový stav serializuje, je může uchovávat jako položky.

Úložiště relací jsou omezena na pracovní prostor a přístup je autorizován na úrovni úložiště. Pole actor_id a metadata podporují pouze seskupování a filtrování; neudělují ani neomezují přístup. Nastavte actor_id ze spolehlivého kontextu aplikace, nikoli pomocí hodnoty poskytnuté modelem nebo uživatelem.

Aby jiný principál, například zástupce vašeho agenta, mohl použít úložiště, udělte mu přístup pomocí operacesession_store.grant_permission(principal_id) grant-permission (v AgentKit SDK).

Relace agenta a paměť agenta jsou nezávislé. Odstranění relace nebo úložiště relací neodstraní data uložená v úložišti paměti. Pro budování dlouhodobé paměti z relací v úložišti vytvořte memory pipeline.

Další kroky

  • Poslední aktualizace v