Memoria gestita dell'agente

La memoria dell'agente gestito offre agli agenti di intelligenza artificiale la memoria a lungo termine tra le conversazioni. Azure Databricks gestisce l'infrastruttura e isola le memorie di ogni ambito, quindi non è necessario gestire direttamente l'archiviazione o il partizionamento.

Con la memoria gestita, gli agenti possono:

• Ricordare le preferenze utente, le decisioni passate e il contesto accumulato tra le conversazioni.
• Proteggi queste conoscenze con le funzionalità di governance di Unity Catalog.
• Condividere la memoria tra agenti e progetti.
• Migliorano la loro precisione ed efficienza nel tempo.

Requisiti

• Un'area di lavoro di Databricks con Il catalogo Unity abilitato.
• Il privilegio CREATE MEMORY STORE sullo schema padre per creare archivi in memoria.

Funzionamento della memoria gestita

La memoria gestita ha due livelli:

• Un archivio di memorie è un oggetto proteggibile di Unity Catalog che funge da contenitore per gli elementi di memoria. Un archivio di memoria eredita la stessa governance, il controllo di accesso e la derivazione di qualsiasi altro asset del catalogo Unity.
• Un elemento di memoria è un singolo contenuto archiviato all'interno di un archivio di memoria. Ogni voce è identificata da un ambito e da un percorso. L'ambito determina a chi appartengono i ricordi associati a una voce e il percorso organizza le voci all'interno di un ambito, in modo simile al percorso di un file (ad esempio, /memories/preferences.md).

Scope

L'ambito di applicazione indica come la memoria gestita mantenga separate le memorie di un agente tra utenti o gruppi diversi. Ogni elemento di memoria appartiene esattamente a un solo ambito e una ricerca restituisce solo gli elementi presenti nell'ambito interrogato.

• Memoria personale: Usare un ID utente finale come ambito in modo che ogni utente ottenga la propria memoria privata, ad esempio le preferenze e le decisioni passate. Gli utenti vedono solo i propri elementi. Il valore di ambito user_client recupera automaticamente l'ID dell'utente finale.
• Conoscenza organizzativa: Usare una chiave condivisa, ad esempio un'organizzazione o un ID team, per archiviare le informazioni su cui qualsiasi utente dell'agente può trarre informazioni, ad esempio fatti aziendali, glossari e procedure consigliate.

Un singolo agente può usare entrambi contemporaneamente: leggere dall'ambito personale di un utente e un ambito aziendale condiviso nella stessa conversazione. È scope obbligatorio per ogni richiesta di immissione di memoria.

Introduzione alle competenze di memoria gestita

Il modo più semplice per aggiungere memoria gestita a un agente è l'abilità managed-memory Claude Code. La skill gestisce tutta la configurazione necessaria per te e funziona sia con l’SDK OpenAI Agents che con LangGraph.

Aggiungi la skill al tuo progetto in uno di questi due modi:

Inizia da un modello

La funzionalità è inclusa nei modelli di app Databricks. Crea un nuovo agente da uno dei modelli per agenti e trova l'abilità in .claude/skills/managed-memory/.

1. Clonare il repository dei modelli:

   git clone https://github.com/databricks/app-templates.git
   

2. Sfogliare app-templates, selezionare un modello di agente da cui iniziare. Ad esempio, per usare il modello OpenAI Agents SDK:

   cd app-templates/agent-openai-agents-sdk
   

   Note

   Per i modelli di app "avanzati", dopo la distribuzione, è necessario concedere all'entità servizio app i privilegi di Lakebase Postgres; in caso contrario, la configurazione della sessione restituirà un 502 errore.

3. Una volta che la competenza è presente nel progetto, descrivere ciò che si vuole e l'assistente alla scrittura del codice si occupa del resto:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Aggiungere la competenza a un progetto esistente

Se si dispone già di un progetto di agente, aggiungere la competenza.

1. Crea la directory delle competenze se non esiste:

   mkdir -p .claude/skills/managed-memory
   

2. Scarica il file SKILL.md dalla managed-memory directory della skill e salvalo in .claude/skills/managed-memory/.

3. Una volta che la competenza è presente nel progetto, descrivere ciò che si vuole e l'assistente alla scrittura del codice si occupa del resto:

   Tip

   Add Databricks managed long-term memory to my agent.
   

Creare e usare manualmente un archivio memoria

Questa sezione illustra come creare e usare un archivio memoria senza la managed-memory competenza Claude Code.

Nell'esempio seguente viene impostata la memoria gestita per un agente del supporto clienti che archivia le preferenze di un utente e le recupera in una conversazione successiva.

1. Generare un token OAuth usando l'interfaccia della riga di comando di Databricks per chiamare le API:

   databricks auth login --host ${DATABRICKS_HOST}
   databricks auth token
   

2. Creare un archivio memoria per memorizzare i ricordi dell'agente:

   curl -X POST "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "support_agent_memory",
       "catalog_name": "main",
       "schema_name": "default",
       "description": "Long-term memory for the customer support agent"
     }'
   

3. Scrivere una voce nella memoria dopo che l'agente ha appreso qualcosa riguardo a un utente. scope assegna la voce a un singolo utente. Usa il campo contents per il testo completo della memoria e il description come breve riepilogo che migliora il recupero:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries?scope=user-123" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "path": "/memories/preferences.md",
       "contents": "Prefers email communication. Timezone: PST. Has an Enterprise subscription.",
       "description": "User 123 communication preferences and account details"
     }'
   

4. Cerca gli elementi di memoria relativi a quell'utente nel corso di una conversazione successiva per recuperare ciò che l'agente ha appreso:

   curl -X POST \
     "https://${DATABRICKS_HOST}/api/2.1/unity-catalog/memory-stores/main.default.support_agent_memory/entries:search" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" \
     -H "Content-Type: application/json" \
     -d '{
       "scope": "user-123",
       "query": "communication preferences"
     }'
   

Per l'API REST completa, inclusi endpoint, campi di richiesta e campi di risposta, vedere Informazioni di riferimento sull'API di memoria.

Aggiungi memoria a un agente tramite le conversazioni

Il flusso di lavoro REST precedente chiama direttamente l'archivio di memoria e le API di immissione. Quando si crea un agente su un endpoint di serving del modello di Azure Databricks, collega invece un archivio di memoria a una conversazione con il client compatibile con OpenAI nell’SDK databricks-openai.

Una conversazione è uno stato di conversazione compatibile con OpenAI, ovvero la cronologia di esecuzione dei messaggi e delle chiamate agli strumenti, supportata da un archivio di memoria e aggiunta a un singolo ambito. Riutilizza la stessa conversazione in più richieste per dare all'agente memoria degli scambi precedenti.

1. Associare un archivio di memoria esistente e un ambito a una nuova conversazione. memory_store.name è il nome a tre livelli dell'archivio dati e scope suddivide lo stato della conversazione, in genere in base all'utente finale:

   from databricks.sdk import WorkspaceClient
   from databricks_openai import DatabricksOpenAI
   
   workspace_client = WorkspaceClient()
   user_id = str(workspace_client.current_user.me().id)
   
   client = DatabricksOpenAI(workspace_client=workspace_client, use_ai_gateway=True)
   
   conversation = client.conversations.create(
       extra_body={
           "memory_store": {"name": "main.default.support_agent_memory"},
           "scope": {"kind": "user", "value": user_id},
       },
   )
   

2. Passa l'ID della conversazione a responses.create. L'agente legge e scrive lo stato della conversazione nell'archivio di memoria associato all'interno di tale ambito:

   response = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "What is the average NYC taxi price?"}],
       stream=True,
   )
   
   for event in response:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

3. Riutilizzare lo stesso ID conversazione nelle richieste successive in modo che l'agente ricordi i turni precedenti. Non creare una nuova conversazione per turno:

   followup = client.responses.create(
       model="databricks-gpt-5-2",
       conversation=conversation.id,
       input=[{"type": "message", "role": "user", "content": "Restate the average taxi price you found, and how it was calculated."}],
       stream=True,
   )
   
   for event in followup:
       if event.type == "response.output_text.delta":
           print(event.delta, end="", flush=True)
   

Per gli endpoint di conversazione e i campi della richiesta, vedere API di conversazione.

Controllo di accesso alla memoria

Gli store di memoria sono oggetti proteggibili di Unity Catalog. I privilegi seguenti controllano l'accesso:

Implementazione della memoria a breve termine

Le API di immissione della memoria forniscono memoria a lungo termine come strumenti da usare per l'agente. Per assegnare all'agente la memoria a breve termine gestita in una sessione, Databricks consiglia di collegare l'archivio memoria a una conversazione. È anche possibile:

• Mantieni la memoria di sessione del framework dell'agente, ad esempio il parametro OpenAI session= o un checkpointer di LangGraph.
• Usa la memoria dell'agente autogestita come archivio della cronologia delle conversazioni.

Raccomandazioni sulla sicurezza

Azure Databricks fornisce l'archivio regolamentato, la crittografia, le primitive di isolamento e il audit trail. In qualità di sviluppatore di app, Databricks consiglia quanto segue:

• Usare il valore predefinito per ambito utente (user_client) a meno che non si disponga di un motivo intenzionale per partizionare in modo diverso (ad esempio, per progetto o memoria per account).
• Concedi il privilegio minimo: solo il service principal dell'agente necessita di WRITE MEMORY STORE. Concedere READ MEMORY STORE in modo ristretto ed evitare ampie concessioni a utenti umani o gruppi di grandi dimensioni.
• Proteggi la credenziale del service principal dell'app: è la chiave del data plane dell'archivio. Considerarlo come qualsiasi credenziale di servizio di alto valore: usare token di breve durata, evitare di registrarlo e aggiungere difese SSRF all'app.

Limitations

• Le voci di memoria consentono solo la memorizzazione a lungo termine. Per la differenza tra memoria a breve termine e a lungo termine, vedere Memoria a breve termine e memoria a lungo termine.
• Gli archivi di memoria e le voci vengono creati e gestiti solo tramite l'API REST del catalogo Unity; non è disponibile Python SDK per queste API. Per usare un archivio di memoria da un agente, connetterlo a una conversazione con il client compatibile con OpenAI. Vedi Aggiungere memoria a un agente con conversazioni.

Passaggi successivi

• Informazioni di riferimento sulle API di memoria