Hanterade agentsessioner

Hanterade agentsessioner ger dina agenter en beständig, ramverksoberoende lagring av sessionstillstånd: det tillstånd som en agent eller ett ramverk bevarar under en interaktion. Oftast är det konversationshistoriken, den ordnade transkriptionen av meddelanden, verktygsanrop och resultat som en agent läser i början av en omgång och fyller på allteftersom den körs. Det kan också vara vilket annat tillstånd som helst där ett ramverk finns kvar för interaktionen, såsom en LangGraph-graf. Azure Databricks lagrar det i Lakebase och hanterar lagringen åt dig, så du bygger eller driver inte databasen.

Använd hanterade sessioner när du vill:

• Behåll en agents konversationshistorik så att den överlever omstarter och kan återupptas senare.
• Återskapa fullständig kontext (inklusive verktygsanrop och resonemang) i ett uppföljningsmeddelande.
• Lista, återuppta och förgrena tidigare konversationer från ditt eget användargränssnitt.

Hanterade sessioner bevarar tillståndet för en enskild interaktion (ett kortvarigt tillstånd inom sessionen). För hållbart, långtidsminne som består över samtal , använd managed agent memory.

Requirements

• Installera Python 3.10 eller högre för att använda AgentKit SDK. AgentKit SDK är Databricks Python-klient för agent-API:er som exemplen nedan använder. Du kan också anropa REST API:et direkt från vilket språk som helst, utan att behöva Python.

Hur hanterade sessioner fungerar

Managed sessions har tre nivåer:

• Ett sessionslager är den arbetsytespecifika behållaren för en agents sessioner. När du skapar ett lagringsutrymme etableras den underliggande Lakebase-lagringen automatiskt. Du väljer en session_store_name som är unik för arbetsytan.
• En session är en varaktig interaktion (vanligtvis en samtalstråd) inom en butik. En session identifieras av:
  • actor_id (Krävs): Vem sessionen tillhör, såsom en slutanvändare eller en annan agent. Den grupperar alla sessioner för ett ämne så att du kan lista och filtrera dem tillsammans. När du bygger en app per användare, ställ actor_id in till användarens ID (till exempel den verifierade slutanvändaridentiteten från appens autentisering) så att varje användares sessioner förblir grupperade. Sätt det från betrodd applikationskontext, aldrig ett modell- eller användargenererat värde.
  • session_id (valfritt): ett ID valt av uppringaren för interaktionen. Tjänsten genererar en när du utelämnar den.
  • parent_session_id (valfritt): länkar en session till den session som den förgrenades från, för att visa förgrenade konversationer.
• Ett sessionsobjekt är en post i en sessions ordnade historik. Varje objekt har ett ogenomskinligt, JSON-kompatibelt data värde, såsom ett meddelande, ett verktygsanrop, ett verktygsresultat eller ett resonemangsblock. Azure Databricks tilldelar varje objekt ett item_id och ett create_time och inspekterar eller validerar inte dess innehåll. Föremål är oföränderliga efter att de lagts till.

Tjänsten upprätthåller en deterministisk ordning för sessionens objekt och auktoriserar varje operation mot sessionslagringen.

Get started

Dessa exempel konfigurerar hanterade sessioner för en support-agent: de skapar en sessionslagring, startar en session för ett enskilt samtal, lägger till inläggen i konversationen och läser sedan tillbaka historiken vid en senare begäran. Välj den kund som passar ditt projekt.

AgentKit SDK

AgentKit SDK är Databricks Python-klient för agent-API:er, distribuerad i paketetdatabricks-agentbricks. Den autentiserar sig med Databricks SDK:s WorkspaceClient.

1. Installera AgentKit SDK:n:

   pip install databricks-agentbricks
   

2. Skapa en sessionslagring och starta sedan en session för en enda konversation. actor_id är vem samtalet tillhör; det valfria session_id identifierar unikt denna konversation:

   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. Lägg till samtalets vändningar medan agenten springer. Varje objekt är ett valfritt JSON-kompatibelt värde:

   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. Vid en uppföljningsförfrågan, ladda om sessionen och läs dess fullständiga historik för att återskapa 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

Klienterna anropar REST-API:et under /api/2.0/agents/session-stores. Anropa det direkt i språk andra än Python.

1. Generera en OAuth-token med Databricks CLI:

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

2. Skapa en sessionbutik för din agent:

   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. Starta en session för ett samtal. actor_id är vem den tillhör; session_id identifierar unikt denna konversation:

   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. Lägg till en samtalstur medan agenten säger:

   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. Läs historien i kronologisk ordning för att återskapa sammanhanget:

   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"
   

Klienterna har också stöd för att ta bort det senaste objektet, rensa objekten i en session och skapa en oberoende kopia av en konversation, valfritt fram till ett visst objekt. Att radera en session som har barnsessioner kräver ett tvångsalternativ för att kaskadera raderingen till dem (till exempel, session.delete(force=True)).

Använd hanterade sessioner för ett agentramverk

Agentramverk som OpenAI Agents SDK och Claude Agent SDK läser konversationshistorik i början av en körning och lägger till nya objekt i slutet. Sessionslagret motsvarar direkt det mönstret:

Omfattning och tillgång

Hanterade sessioner lagrar en sessions objekt som ogenomskinliga, JSON-kompatibla värden: tjänsten består och returnerar vad din agent eller ramverk lägger till, utan att tolka det. Den lägger inte till exekveringskontrollresurser som körningar, kontrollpunkter eller godkännanden som förstklassiga koncept, även om ett ramverk som serialiserar sådant tillstånd kan lagra det som objekt.

Sessionslagringar är begränsade till arbetsytan, och åtkomst beviljas på lagringsnivå. Fälten actor_id och metadata stöder endast gruppering och filtrering; de ger eller begränsar inte åtkomst. Ange actor_id från betrodd applikationskontext i stället för ett värde som tillhandahålls av modellen eller användaren.

För att låta en annan huvudperson, som din agents tjänstehuvudansvariga, använda en butik, ge den tillgång med butikens grant-permission-operation (session_store.grant_permission(principal_id) i AgentKit SDK).

Managed sessions och managed memory är oberoende av varandra. Att radera en session eller sessionslagring raderar inte minne som lagrats i ett minneslager.

Nästa steg

• Hanterat agentminne
• Agent API-referens