Pipeline di memoria per gli agenti

Una pipeline di memoria costruisce la memoria a lungo termine dalle conversazioni passate del tuo agente. Legge la cronologia delle conversazioni da un archivio di sessione e distilla memorie a lungo termine, come fatti, preferenze e procedure, in un archivio di memorie. Il tuo agente poi ricorda quei ricordi nelle conversazioni successive allo stesso modo in cui ricorda i ricordi che ha salvato da solo.

Un agente che salva i ricordi durante una conversazione li scrive una conversazione alla volta, con solo il contesto di quella conversazione. Nel corso di molte conversazioni, la sua memoria raccoglie voci sovrapposte e contrastanti, e fatti che l'agente non ha pensato di salvare non arrivano alla memoria. Una pipeline di memoria funziona a posteriori, con tutte le conversazioni e la memoria esistente di un attore in vista, così da poter catturare ciò che l'agente ha trascurato e mantenere la memoria consolidata.

Usa una pipeline di memoria quando vuoi:

• Costruisci memoria a lungo termine dalle conversazioni senza aggiungere strumenti di scrittura della memoria al tuo agente.
• Popola la memoria dalla cronologia delle conversazioni che un archivio di sessione già conserva.
• Mantieni la memoria organizzata nel tempo unendo voci sovrapposte e dividendo quelle sovradimensionate.

Puoi usare una pipeline di memoria da sola o insieme a strumenti di memoria che il tuo agente chiama durante una conversazione.

Requirements

• Uno store di sessioni che contiene le conversazioni del tuo agente e uno store di memoria in cui scrivere i ricordi.
• Accesso a entrambi i store per l'identità che crea la pipeline, incluso il permesso di creare tabelle nel database del memory store. Le esecuzioni di pipeline usano quell'identità.
• Permesso di interrogare il modello utilizzato dalla pipeline per la distillazione. Senza di essa, le esecuzioni della pipeline falliscono.
• Per usare la CLI, installa databricks-agentbricks la versione 0.6.0 e superiore. Puoi anche chiamare l'API REST direttamente da qualsiasi linguaggio.

Come funzionano le pipeline di memoria

Una pipeline di memoria è una risorsa di memoria agente che collega uno store di sessione a uno store di memoria. Non è collegato alle pipeline di Lakeflow. Un archivio di sessione può fornire più di un archivio di memoria, ma ogni coppia costituita da un archivio di sessione e un archivio di memoria può avere una sola pipeline.

• Chiamate al modello tramite Unity Gateway: La pipeline chiama il suo modello di distillazione tramite Unity Gateway.
• La tua scelta di modello: Scegli il modello quando crei una pipeline e puoi cambiarlo in seguito. Se non ne scegli uno, la pipeline usa un modello predefinito.
• Esecuzioni manuali o pianificate su calcolo serverless: Avvii tu stesso le esecuzioni, oppure configuri la pipeline per farla eseguire secondo una pianificazione di circa ogni 24 ore. In ogni caso, ogni esecuzione viene eseguita come un processo su calcolo serverless, usando l'identità che ha creato la pipeline.

Ogni esecuzione della pipeline elabora ogni attore nella memoria sessione separatamente:

1. Distilla: La pipeline legge le nuove conversazioni dell'attore e utilizza un LLM per estrarre fatti duraturi da esse.
2. Merge: La pipeline deduplica i nuovi fatti e li unisce in voci di memoria basate su argomenti sotto lo stesso actor_id nell'archivio di memoria.
3. Mantieni: La pipeline riorganizza la memoria dell'actor. Unisce le voci che si sovrappongono e divide le voci che diventano troppo grandi.

Le esecuzioni della pipeline di memoria mantengono un checkpoint per ogni ID attore. Un'esecuzione elabora tutte le sessioni di un attore dalla sua ultima esecuzione completata con successo, quindi la prima esecuzione elabora l'intera cronologia dell'attore. Se una run fallisce per un attore, continua con gli altri attori, e la run successiva ritenta l'attore fallito dal suo checkpoint.

Il actor_id collega i due negozi. Una pipeline elabora solo gli attori che hanno sessioni nello store delle sessioni e scrive le memorie di ogni attore sotto lo stesso actor_id che usano le sessioni dell'attore. Per impostazione predefinita, una pipeline viene eseguita solo quando avvii un'esecuzione. Puoi anche eseguirlo secondo una pianificazione.

Che cosa mantiene una pipeline

Un pipeline estrae fatti individuali e duraturi dalle conversazioni. È progettato per mantenere:

• Fatti che l'utente dichiara esplicitamente e preferenze che esprime, senza dedurre oltre ciò che dice la conversazione.
• Correzioni e feedback espliciti, come quale fonte utilizzare per i ricavi.
• Conoscenza duratura del settore, come fonti autorevole, definizioni di metriche, terminologia e convenzioni di team, oltre a flussi di lavoro e progetti in corso.

È progettato per saltare:

• Valori provenienti da fonti live che cambiano nel tempo, come il conteggio attuale delle righe di una tabella. Registra invece come trovare o calcolare il valore.
• Dettagli che l'agente può consultare con i suoi strumenti, come lo schema di una tabella.
• Segreti, come password, chiavi API e token.

Get started

Questi esempi creano una pipeline di memoria per la sessione e gli archivi di memoria di un agente di supporto, avviano una run e ne verificano il risultato. Identifica ogni store tramite il suo ID, l'identificatore scelto quando hai creato lo store, o tramite il nome della risorsa, come memory-stores/support-agent-memory. Scegli il cliente che si adatta al tuo progetto.

Mattoni agente

L'Agent Bricks CLI utilizza il profilo CLI Databricks salvato per autenticarsi.

1. Installa la CLI di Agent Bricks, oppure aggiornala alla versione 0.6.0 e superiore:

   pip install --upgrade databricks-agentbricks
   

2. Crea una pipeline che distilli il support-agent-sessions session store nel support-agent-memory memory store. --model è facoltativo. Se lo ometti, la pipeline utilizza un modello predefinito:

   agentbricks memory pipeline create \
     --session-store support-agent-sessions \
     --memory-store support-agent-memory \
     --model system.ai.claude-sonnet-5
   

   Il comando restituisce il nome della risorsa della pipeline, nella forma memory-pipelines/<pipeline-id>.

3. Avvia un'esecuzione della pipeline:

   agentbricks memory pipeline run <pipeline-id>
   

   Il comando restituisce il nome della risorsa della run, nella forma memory-pipelines/<pipeline-id>/runs/<run-id>, e il suo RUNNING stato.

4. La CLI non riporta il risultato di un'esecuzione. Per verificarlo, imposta DATABRICKS_HOST sul nome host del tuo workspace, genera un token OAuth e chiama l'API REST:

   export DATABRICKS_TOKEN=$(databricks auth token --profile <profile> | jq -r .access_token)
   curl "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/runs/<run-id>" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}"
   

REST API

La CLI chiama l'API REST tramite /api/2.0/agents/memory-pipelines. Richiamalo direttamente da qualsiasi linguaggio.

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 una pipeline che distilli i ricordi da support-agent-sessions e li salvi su support-agent-memory. dreamer_policy.model è facoltativo. Se lo ometti, la pipeline utilizza un modello predefinito:

   curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"model": "system.ai.claude-sonnet-5"}}'
   

   Il campo della name risposta contiene il nome della risorsa della pipeline, nella forma memory-pipelines/<pipeline-id>.

3. Avvia un'esecuzione della pipeline:

   curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/run" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
     -d '{}'
   

   Il campo name della risposta contiene il nome della risorsa della run, nella forma memory-pipelines/<pipeline-id>/runs/<run-id>.

4. Controlla il risultato dell'esecuzione:

   curl "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>/runs/<run-id>" \
     -H "Authorization: Bearer ${DATABRICKS_TOKEN}"
   

Dopo che una run riesce, il tuo agente può richiamare i nuovi ricordi con la lista e le operazioni di ricerca dello store di memoria. Vedi la memoria dell'agente.

Monitorare le esecuzioni delle pipeline

La state di una corsa è una delle seguenti:

Guidare la distillazione con istruzioni

Le istruzioni dicono alla pipeline cosa mantenere e come organizzarla. Il processo li applica in ogni fase. Utilizzali per indicazioni di alto livello, come:

• Gli argomenti su cui concentrarsi, come le preferenze dei clienti e i dettagli dell'account.
• Il contenuto da saltare, come i passaggi di troubleshooting una tantum.
• I percorsi in cui organizzare le voci.

Senza istruzioni di layout, la pipeline segue la disposizione delle voci esistenti del store, oppure deriva una disposizione basata su argomenti quando il store è vuoto. Non rinomina le voci esistenti per adattarle a un nuovo layout. Per modificare una voce specifica, modificala con l'operazione di aggiornamento dello store di memoria anziché tramite istruzioni.

Puoi impostare istruzioni quando crei una pipeline e modificarle in seguito. L'esecuzione successiva utilizza le nuove istruzioni.

Mattoni agente

Per impostare le istruzioni quando crei una pipeline, passa --instructions:

agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --instructions "Focus on durable customer preferences and account details. Ignore one-off troubleshooting steps. Organize entries under /preferences/ and /account/."

Per caricare istruzioni più lunghe da un file UTF-8, --instructions @<path-to-file> passa invece.

Per modificare le istruzioni di una pipeline esistente, esegui quanto segue:

agentbricks memory pipeline update <pipeline-id> \
  --instructions "Keep only durable customer preferences."

REST API

Nell'API REST, l'oggetto dreamer_policy di una pipeline contiene le sue impostazioni di distillazione: instructions, trigger e model. Per impostare istruzioni quando crei una pipeline, includile in dreamer_policy.instructions:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"instructions": "Focus on durable customer preferences and account details. Ignore one-off troubleshooting steps. Organize entries under /preferences/ and /account/."}}'

Per modificare le istruzioni di una pipeline esistente, aggiornare dreamer_policy.instructions:

curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>?update_mask=dreamer_policy.instructions" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"dreamer_policy": {"instructions": "Keep only durable customer preferences."}}'

Esegui una pipeline in base a una pianificazione

Una pipeline programmata si attiva automaticamente circa ogni 24 ore. Puoi impostare il trigger quando crei una pipeline, oppure cambiarlo in seguito. L’utilità di pianificazione sceglie quando inizia la prima esecuzione pianificata. Per condensare subito le conversazioni esistenti, avvia manualmente un'esecuzione.

Mattoni agente

Per creare una pipeline programmata, passare --trigger scheduled. Il valore predefinito è --trigger manual:

agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --trigger scheduled

Per modificare il trigger di una pipeline esistente, esegui quanto segue:

agentbricks memory pipeline update <pipeline-id> --trigger scheduled

Se hai una pipeline programmata, puoi metterla in pausa:

agentbricks memory pipeline pause <pipeline-id>

Per riavviare le corse programmate, riprendile:

agentbricks memory pipeline resume <pipeline-id>

REST API

Per creare una pipeline programmata, imposta dreamer_policy.trigger su SCHEDULED:

curl -X POST "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"session_store": "support-agent-sessions", "memory_store": "support-agent-memory", "dreamer_policy": {"trigger": "SCHEDULED"}}'

Per modificare il trigger di una pipeline esistente, aggiorna dreamer_policy.trigger a SCHEDULED op MANUAL_ONLY:

curl -X PATCH "https://${DATABRICKS_HOST}/api/2.0/agents/memory-pipelines/<pipeline-id>?update_mask=dreamer_policy.trigger" \
  -H "Authorization: Bearer ${DATABRICKS_TOKEN}" -H "Content-Type: application/json" \
  -d '{"dreamer_policy": {"trigger": "SCHEDULED"}}'

Puoi anche avviare manualmente una run di una pipeline programmata, purché non ci sia un'altra run in corso.

Gestione delle pipeline

I seguenti comandi elencano, ispezionano, aggiornano ed eliminano le pipeline. Ogni comando CLI accetta o l'ID della pipeline o il nome completo della relativa risorsa memory-pipelines/<pipeline-id>.

Se non imposti un nome di visualizzazione, la pipeline ne ottiene uno in base ai nomi dello store di sessione e dello store di memoria. Per riportare una pipeline al modello predefinito, aggiorna il modello a un valore vuoto, come --model "". I cambiamenti di modello e istruzioni si applicano alla prossima esecuzione.

Eliminare una pipeline elimina il job sottostante e blocca le esecuzioni future. Un'esecuzione già in corso continua fino al completamento. Le voci di memoria già scritte dalla pipeline rimangono nello store di memoria.

Limitations

• L'archivio di sessione e l'archivio di memoria sono fissi quando crei una pipeline. Per cambiare uno dei due, elimina la pipeline e creane una nuova. Una nuova pipeline non riutilizza i checkpoint della vecchia pipeline, quindi la sua prima esecuzione processa la storia completa di ogni attore, anche per la stessa coppia di store.
• Se una pipeline collega già lo stesso archivio delle sessioni e archivio di memoria, crearne un'altra fallisce con ALREADY_EXISTS.
• Una pipeline può avere una sola esecuzione in corso alla volta. Avviare un'esecuzione mentre un'altra è in corso fallisce con un errore ABORTED.
• Le pipeline pianificate vengono eseguite circa ogni 24 ore. Non puoi impostare un intervallo diverso o una pianificazione cron.
• Una pipeline elabora solo gli attori che hanno sessioni nello store sessioni. Le voci di memoria per gli attori senza sessioni rimangono invariate.
• Se l'archivio di sessione ha più di circa 1.200 attori con ID attore UUID, il run non riesce. Il limite è di 48 KiB di ID attori serializzati, quindi ID più brevi permettono più attori.

Risorse aggiuntive

• Memoria agente
• Sessioni agente
• Memoria e sessioni degli agenti
• Riferimento API dell'agente