Agentsessies

Agentsessies geven je agenten een duurzame, framework-agnostische opslag voor sessietoestand: de toestand die een agent of framework voor één interactie behoudt. Meestal is dit de gespreksgeschiedenis, de geordende transcriptie van berichten, tool-calls en resultaten die een agent aan het begin van een beurt leest en eraan toevoegt terwijl deze loopt. Het kan ook elke andere toestand zijn die een framework voor de interactie bewaart, zoals een LangGraph-graaf. Azure Databricks slaat het op in Lakebase en beheert de opslag voor je, dus je bouwt of bedient de database niet.

Gebruik agentsessies wanneer je wilt:

• Houd de gespreksgeschiedenis van een agent in stand zodat deze herstarts overleeft en later kan worden hervat.
• Reconstrueer de volledige context (inclusief toolcalls en redenering) bij een vervolgbericht.
• Bekijk, hervat en splits eerdere gesprekken af in je eigen gebruikersinterface.

Agentsessies houden de toestand van één interactie vast (kortdurend, in-sessie toestand). Voor een langetermijngeheugen dat over gesprekken heen blijft bestaan, gebruik agent memory.

Requirements

• Installeer Python 3.10 of hoger, om de AgentKit SDK te gebruiken. AgentKit SDK is de Databricks Python-client voor agent-API's die in de onderstaande voorbeelden worden gebruikt. Je kunt de REST API ook direct aanroepen vanuit elke taal, zonder Python-vereiste.

Hoe agentensessies werken

Agentsessies bestaan uit drie niveaus:

• Een sessieopslag is de container binnen de werkruimtescope waarin de sessies van een agent worden opgeslagen. Door een store te maken, wordt de onderliggende Lakebase-opslag automatisch ingericht. Je kiest een unieke winkel-ID binnen de werkruimte.
• Een sessie is één duurzame interactie (meestal een gespreksdraad) binnen een winkel. Een sessie wordt geïdentificeerd door:
  • actor_id (vereist): van wie de sessie is, zoals een eindgebruiker of een andere agent. Het groepeert alle sessies van één onderwerp zodat je ze samen kunt vermelden en filteren. Wanneer je een per-gebruiker app bouwt, stel actor_id dan in op de gebruikers-ID (bijvoorbeeld de geverifieerde eindgebruikersidentiteit van je app-authenticatie) zodat de sessies van elke gebruiker gegroepeerd blijven. Stel het in vanuit de context van de vertrouwde applicatie, nooit op een door het model of de gebruiker aangegeven waarde.
  • session_id (optioneel): een door de beller gekozen ID voor de interactie. De dienst genereert er een als je hem weglaat.
  • parent_session_id (optioneel): maakt de sessie een kind van een andere sessie in de opslag, zoals het gesprek van een subagent. Stel het in wanneer je de sessie aanmaakt.
• Een sessie-item is één vermelding in de geordende geschiedenis van een sessie. Elk item bevat een ondoorzichtige, JSON-compatibele data waarde, zoals een bericht, toolcall, toolresultaat of redeneerblok. Azure Databricks wijst elk item een item_id en een create_time toe en inspecteert of valideert de inhoud niet. Items zijn onveranderlijk nadat ze zijn toegevoegd.

De service onderhoudt een deterministische volgorde voor de items van een sessie en autoriseert elke bewerking tegen de sessieopslag.

Get started

Deze voorbeelden zetten agentsessies op voor een supportagent: ze maken een sessieopslag aan, starten een sessie voor één gesprek, voegen de gesprekswendingen van het gesprek toe en halen later de geschiedenis weer op bij een volgend verzoek. Kies de klant die bij jouw project past.

AgentKit SDK

De AgentKit SDK is de Databricks Python-client voor agent-API's, verspreid in het databricks-agentbricks pakket. Het authenticeert met de SDK van Databricks WorkspaceClient.

1. Installeer de AgentKit SDK:

   pip install databricks-agentbricks
   

2. Maak een sessieopslag aan en begin dan een sessie voor één gesprek. actor_id is van wie het gesprek is; de optionele session_id identificeert dit gesprek op unieke wijze:

   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. Voeg de wendingen van het gesprek toe terwijl de agent rent. Elk item is een willekeurige JSON-compatibele waarde:

   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. Op een vervolgverzoek laad je de sessie opnieuw en lees je de volledige geschiedenis om de context opnieuw op te bouwen:

   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

De clients roepen de REST API aan onder /api/2.0/agents/session-stores. Roep het rechtstreeks aan in andere talen dan Python.

1. Genereer een OAuth-token met de Databricks CLI:

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

2. Maak een sessiewinkel voor je agent:

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

3. Begin een sessie voor één gesprek. actor_id is aan wie het toebehoort; session_id identificeert dit gesprek op unieke wijze:

   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. Voeg een gespreksbeurt toe terwijl de agent luidt:

   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. Lees de geschiedenis terug in chronologische volgorde om de context opnieuw op te bouwen:

   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"
   

De clients ondersteunen ook het verwijderen van het meest recente item, het wissen van de items van een sessie en het afsplitsen van een gesprek tot een zelfstandige kopie (eventueel tot en met een specifiek item). Een fork heeft geen oudersessie, en het verwijderen van de bronsessie verwijdert deze niet. Het verwijderen van een sessie verwijdert altijd de kindsessies en hun items.

Laat de sessie van een agentenraamwerk ondersteunen door agentsessies

Agent-frameworks zoals de OpenAI Agents SDK en de Claude Agent SDK lezen de gespreksgeschiedenis aan het begin van een run en voegen nieuwe items toe aan het einde. De sessieopslag sluit direct aan op dat patroon:

Reikwijdte en toegang

Agentsessies slaan de items van een sessie op als ondoorzichtige, JSON-compatibele waarden: de service slaat op en geeft terug wat je agent of framework toevoegt, zonder het te interpreteren. Het voegt geen uitvoeringscontrolemiddelen toe zoals runs, checkpoints of goedkeuringen als eersteklas concepten, hoewel een framework dat zo'n toestand serialiseert deze als items kan behouden.

Sessieopslagruimten zijn gebonden aan de werkruimte en toegang wordt geautoriseerd op het niveau van de opslagruimte. Toegangsbeheer voor winkels omvat de sessies van een winkel. Elke werkruimtegebruiker kan sessiestores vermelden en opvragen, inclusief hun ID's en beschrijvingen. De actor_id en-velden metadata ondersteunen alleen groeperen en filteren; ze verlenen of beperken geen toegang. Stel de actor_id in vanuit een vertrouwde toepassingscontext in plaats van een door het model of de gebruiker opgegeven waarde.

Om een andere principal, zoals de serviceprincipal van uw agent, een store te laten gebruiken, verleen deze toegang via de grant-permission-operatie van de store (session_store.grant_permission(principal_id) in de AgentKit SDK). Alleen de maker van de winkel of een workspace-beheerder kan toegang verlenen.

Agentsessies en agentgeheugen zijn onafhankelijk. Het verwijderen van een sessie of sessieopslag verwijdert geen geheugen dat in een geheugenopslag is behouden. Om langetermijngeheugen op te bouwen uit de sessies in een store, maak je een memory pipeline.

Volgende stappen 

• Agentgeheugen
• Pijplijnen voor agentgeheugen
• Agent API-referentie