Sessioni con agenti gestiti

Le sessioni gestite dell'agente offrono ai tuoi agenti un archivio durevole, indipendente dal framework, per lo stato della sessione: lo stato che un agente o un framework mantiene per una singola interazione. Più comunemente si tratta della cronologia delle conversazioni, la trascrizione ordinata di messaggi, chiamate agli strumenti e risultati che un agente legge all'inizio di un turno e aggiunge man mano che viene eseguita. Può anche essere qualsiasi altro stato in cui persiste un framework per l'interazione, come un grafo LangGraph. Azure Databricks lo memorizza in Lakebase e gestisce lo storage per te, quindi non costruisci né gestisci il database.

Usa le sessioni gestite quando vuoi:

• Rendi persistente la cronologia della conversazione di un agente, in modo che venga mantenuta anche dopo i riavvii e possa essere ripresa in seguito.
• Ricostruisci il contesto completo (incluse le chiamate agli strumenti e il ragionamento) in un messaggio successivo.
• Elenca, riprendi e crea diramazioni da conversazioni precedenti dalla tua interfaccia utente.

Le sessioni gestite mantengono lo stato di un'unica interazione (a breve termine, stato durante la sessione). Per una memoria duratura e a lungo termine che persiste tra le conversazioni, usa la memoria gestita degli agenti.

Requisiti

• Installa Python 3.10 o superiore, per usare l'SDK AgentKit. AgentKit SDK è il client Python di Databricks per le API degli agenti che utilizzano gli esempi sottostanti. Puoi anche chiamare l'API REST direttamente da qualsiasi linguaggio, senza bisogno di Python.

Come funzionano le sessioni gestite

Le sessioni gestite hanno tre livelli:

• Un archivio delle sessioni è il contenitore relativo all'area di lavoro per le sessioni di un agente. Creare uno store fornisce automaticamente lo storage di supporto a Lakebase. Scegli uno spazio di lavoro unico session_store_name.
• Una sessione è un'interazione duratura (tipicamente un thread di conversazione) all'interno di un negozio. Una sessione è identificata da:
  • actor_id (richiesto): a chi appartiene la sessione, come un utente finale o un altro agente. Raggruppa tutte le sessioni di un solo argomento così puoi elencarle e filtrarle insieme. Quando costruisci un'app per utente, imposta actor_id l'ID dell'utente (ad esempio, l'identità utente finale verificata dall'autenticazione della tua app) in modo che le sessioni di ogni utente rimangano raggruppate. Impostalo nel contesto di un'applicazione attendibile, mai su un valore fornito dal modello o dall'utente.
  • session_id (opzionale): un ID scelto dal chiamante per l'interazione. Il servizio ne genera uno quando lo ometti.
  • parent_session_id (opzionale): collega una sessione a quella da cui è stata forforcata, per rappresentare conversazioni ramificate.
• Un elemento di sessione è una voce nella cronologia ordinata di una sessione. Ogni elemento contiene un valore opaco e compatibile data con JSON, come un messaggio, una chiamata a uno strumento, un risultato dello strumento o un blocco di ragionamento. Azure Databricks assegna a ogni elemento un item_id e un create_time e non ne ispeziona né ne convalida il contenuto. Gli elementi sono immutabili dopo essere stati aggiunti.

Il servizio mantiene un ordine deterministico per gli elementi di una sessione e autorizza ogni operazione rispetto all'archivio della sessione.

Get started

Questi esempi configurano sessioni gestite per un agente di supporto: creano uno store sessioni, avviano una sessione per una conversazione, aggiungono i turni della conversazione e rileggono la cronologia su una richiesta successiva. Scegli il cliente che si adatta al tuo progetto.

AgentKit SDK

L'SDK AgentKit è il client Python di Databricks per le API degli agenti, distribuito nel databricks-agentbricks pacchetto. Si autentica con l'SDK di Databricks WorkspaceClient.

1. Installa l'SDK AgentKit:

   pip install databricks-agentbricks
   

2. Crea un archivio sessioni, quindi avvia una sessione per una singola conversazione. actor_id è a chi appartiene la conversazione; l'opzionale session_id identifica unicamente questa conversazione:

   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. Aggiungi i turni della conversazione mentre l'agente corre. Ogni elemento è un valore compatibile con 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. Su richiesta successiva, ricarica la sessione e leggi la sua storia completa per ricostruire il contesto:

   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

I client chiamano l'API REST sotto /api/2.0/agents/session-stores. Chiamalo direttamente per i linguaggi diversi da Python.

1. Genera un token OAuth con la CLI Databricks:

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

2. Crea un archivio di sessione per il tuo agente:

   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. Inizia una sessione per una conversazione. actor_id è a chi appartiene; session_id identifica in modo unico questa conversazione:

   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. Aggiungi un turno di conversazione mentre l'agente corre:

   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. Leggi la storia in ordine cronologico per ricostruire il contesto:

   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"
   

I client consentono anche di rimuovere l'elemento più recente, cancellare gli elementi di una sessione e duplicare una conversazione in una copia indipendente (facoltativamente fino a un elemento specifico). Per eliminare una sessione con sessioni figlie è necessaria l'opzione force per eseguirne l'eliminazione a cascata (ad esempio, session.delete(force=True)).

Supporta la sessione di un framework di agenti tramite sessioni gestite

Framework di agenti come OpenAI Agents SDK e Claude Agent SDK leggono la cronologia delle conversazioni all'inizio di una run e aggiungono nuovi elementi alla fine. L’archivio di sessione corrisponde direttamente a quello schema:

Ambito e accesso

Le sessioni gestite memorizzano gli elementi di una sessione come valori opachi e compatibili con JSON: il servizio persiste e restituisce ciò che il tuo agente o framework aggiunge, senza interpretarlo. Non aggiunge risorse di controllo dell'esecuzione come esecuzioni, checkpoint o approvazioni quali concetti fondamentali, anche se un framework che serializza tale stato può persisterlo sotto forma di elementi.

Gli archivi di sessione sono limitati all’area di lavoro e l’accesso è autorizzato a livello di archivio. I actor_id campi e metadata supportano solo il raggruppamento e il filtraggio; non concedono né limitano l'accesso. Imposta il actor_id dal contesto dell'applicazione attendibile anziché da un valore fornito dal modello o dall'utente.

Per consentire a un altro principal, ad esempio il service principal del tuo agente, di usare uno store, concedigli l’accesso tramite l’operazione grant-permission dello store (session_store.grant_permission(principal_id) nell’SDK AgentKit).

Le sessioni gestite e la memoria gestita sono indipendenti. L'eliminazione di una sessione o di un archivio delle sessioni non elimina la memoria archiviata in un archivio di memoria.

Passaggi successivi

• Memoria gestita degli agenti
• Riferimento API dell'agente