Pipelines de mémoire d’agent

Important

Cette fonctionnalité est en version bêta.

Un pipeline de mémoire construit une mémoire à long terme à partir des conversations passées de votre agent. Il lit l’historique des conversations depuis un stockage de session et distille les souvenirs à long terme, tels que des faits, des préférences et des procédures, dans un stockage de mémoire. Votre agent se souvient alors de ces souvenirs dans des conversations ultérieures, de la même manière qu’il se rappelle les souvenirs qu’il a sauvegardés lui-même.

Un agent qui sauvegarde des souvenirs pendant une conversation les écrit une conversation à la fois, avec seulement le contexte de cette conversation. Au fil de nombreuses conversations, sa mémoire collecte des entrées qui se chevauchent et se contreposent, et des faits que l’agent n’avait pas pensé à sauvegarder n’atteignent pas la mémoire. Un pipeline de mémoire fonctionne après coup, avec toutes les conversations et la mémoire existante d’un acteur en vue, afin de capturer ce que l’agent a manqué et de maintenir la mémoire consolidée.

Utilisez un pipeline mémoire lorsque vous souhaitez :

Construisez une mémoire à long terme à partir des conversations sans ajouter d’outils d’écriture mémoire à votre agent.
Remplissez la mémoire à partir de l’historique des conversations qu’un stockage de session contient déjà.
Gardez la mémoire organisée au fil du temps en fusionnant des entrées qui se chevauchent et en divisant celles surdimensionnées.

Vous pouvez utiliser un pipeline mémoire seul ou avec des outils de mémoire que votre agent appelle pendant une conversation.

Note

Les exécutions de pipeline mémoire utilisent la tarification générale de calcul sans serveur pour le job et Foundation Model Serving pricing pour les appels de modèle.

Requirements

Un stockage de sessions qui contient les conversations de votre agent, et un stockage de mémoires pour écrire des mémoires.
Accès aux deux stockages pour l’identité qui crée le pipeline, y compris la permission de créer des tables dans la base de données du stockage en mémoire. Les exécutions de pipeline utilisent cette identité.
Permission d’interroger le modèle utilisé par le pipeline pour la distillation.
Pour utiliser la ligne de commande, installez databricks-agentbricks la version 0.5.0 ou supérieure. Vous pouvez également appeler l’API REST directement depuis n’importe quel langage.

Fonctionnement des pipelines mémoire

Un pipeline mémoire est une ressource de mémoire d’agent qui relie un stockage de session à un seul stockage mémoire. Ce n’est pas lié aux pipelines Lakeflow. Un stockage de session peut alimenter plus d’un stockage mémoire, mais chaque paire de stockage de session et de stockage mémoire ne peut avoir qu’un seul pipeline.

Appels de modèle via Unity Gateway : Le pipeline appelle son modèle de distillation via Unity Gateway.
Votre choix de modèle : Vous choisissez le modèle lorsque vous créez un pipeline et pouvez le modifier plus tard. Si vous n’en choisissez pas, le pipeline utilise un modèle par défaut.
Exécutions manuelles ou planifiées sur le calcul serverless : Vous lancez vous-même les exécutions, ou configurez le pipeline pour qu’il fonctionne selon un planning environ toutes les 24 heures. Dans tous les cas, chaque exécution s’exécute comme un job sur le calcul sans serveur, en utilisant l’identité qui a créé le pipeline.

Chaque exécution du pipeline traite chaque acteur dans le stockage de session séparément :

Distiller : Le pipeline lit les nouvelles conversations de l’acteur et utilise un LLM pour en extraire des faits durables.
Fusion : Le pipeline déduplique les nouveaux faits et les fusionne dans des entrées de mémoire thématiques sous le même actor_id dans le stockage mémoire.
Conserver : Le pipeline réorganise la mémoire de l’acteur. Elle fusionne les entrées qui se chevauchent et divise les entrées qui deviennent trop grandes.

Les exécutions du pipeline mémoire maintiennent un point de contrôle pour chaque identifiant d’acteur. Une exécution traite toutes les sessions d’un acteur depuis la dernière exécution réussie de cet acteur, donc la première exécution traite l’historique complet de l’acteur. Si une tentative échoue pour un acteur, l’exécution se poursuit avec les autres acteurs, et la prochaine tentative refait l’acteur échoué depuis son point de contrôle.

Le actor_id relie les deux magasins. Un pipeline ne traite que les acteurs ayant des sessions dans le magasin de sessions, et il écrit les mémoires de chaque acteur sous le même actor_id que les sessions de l’acteur. Par défaut, un pipeline ne s’exécute que lorsque vous lancez une exécution. Vous pouvez aussi l’exécuter selon une planification.

Note

La maintenance s’applique à toutes les entrées mémoire d’un acteur, y compris les entrées que votre agent a sauvegardées directement. Un pipeline peut réécrire, fusionner, diviser ou supprimer toute entrée sous un actor_id qu’il traite.

Ce qu’un pipeline conserve

Un pipeline extrait des faits individuels et durables des conversations. Il est conçu pour préserver :

Des faits que l’utilisateur énonce explicitement et des préférences qu’il exprime, sans déduire au-delà de ce que dit la conversation.
Corrections et retours explicites, comme quelle source utiliser pour les chiffres de revenus.
Une connaissance durable du domaine, telle que des sources faisant autorité, des définitions métriques, la terminologie et les conventions d’équipe, ainsi que les flux de travail et les projets en cours.

Il est conçu pour ignorer :

Des valeurs provenant de sources en direct qui évoluent au fil du temps, comme le nombre de lignes actuelles d’une table. Il enregistre comment trouver ou calculer la valeur à la place.
Des détails que l’agent peut consulter avec ses outils, comme le schéma d’une table.
Des secrets, tels que les mots de passe, les clés API et les jetons.

Get started

Ces exemples créent un pipeline mémoire pour la session et les magasins de mémoire d’un agent de support, lancent une exécution et vérifient son résultat. Identifiez chaque magasin par son ID, l’identifiant choisi lors de la création du magasin, ou par son nom de ressource, tel que memory-stores/support-agent-memory. Choisissez le client qui correspond à votre projet.

Briques de l’agent

L’Agent Bricks CLI utilise votre profil Databricks CLI enregistré pour s’authentifier.

Installez la CLI Agent Bricks, ou faites-la passer à la version 0.5.0 et supérieure :
```
pip install --upgrade databricks-agentbricks
```
Créez un pipeline qui distille le magasin de sessions support-agent-sessions dans le magasin de mémoire support-agent-memory. --model est facultatif. Si vous l’omettez, le pipeline utilise un modèle par défaut :
```
agentbricks memory pipeline create \
  --session-store support-agent-sessions \
  --memory-store support-agent-memory \
  --model system.ai.claude-sonnet-5
```
La commande retourne le nom de la ressource du pipeline, sous la forme memory-pipelines/<pipeline-id>.
Démarrez une exécution du pipeline :
```
agentbricks memory pipeline run <pipeline-id>
```
La commande renvoie le nom de ressource de l’exécution, sous la forme memory-pipelines/<pipeline-id>/runs/<run-id>, et son état RUNNING.

Le CLI ne rapporte pas le résultat d’une exécution. Pour vérifier, définissez DATABRICKS_HOST sur votre nom d’hôte d’espace de travail, générez un jeton OAuth, et appelez 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 appelle l’API REST via /api/2.0/agents/memory-pipelines. Appelez-le directement à partir de n’importe quel langage.

Générez un jeton OAuth avec l’interface de ligne de commande Databricks :

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

Créez un pipeline qui distille les souvenirs de support-agent-sessions et les sauvegarde dans support-agent-memory. model est facultatif. Si vous l’omettez, le pipeline utilise un modèle par défaut :
```
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", "model": "system.ai.claude-sonnet-5"}'
```
Le champ de name la réponse contient le nom de la ressource du pipeline, sous la forme memory-pipelines/<pipeline-id>.

Démarrez une exécution du 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 '{}'

Le champ de la name réponse contient le nom de la ressource de l’exécution, sous la forme memory-pipelines/<pipeline-id>/runs/<run-id>.

Vérifiez le résultat de l’exécution :

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

Après le succès d’une exécution, votre agent peut rappeler les nouvelles mémoires grâce à la liste et aux opérations de recherche du stockage de mémoire. Voir la mémoire de l’agent.

Surveiller les exécutions de pipeline

Le state d’une exécution est l’un des suivants :

State	Meaning
`RUNNING`	L’exécution est en attente ou en cours.
`SUCCEEDED`	L’exécution a traité chaque actor avec succès.
`FAILED`	L’exécution s’est terminée avec une erreur pour un ou plusieurs acteurs. Le `error` champ décrit la défaillance.
`CANCELLED`	La course a été annulée avant qu’elle ne se termine.

Orienter la distillation avec instructions

Les instructions indiquent au pipeline quoi garder et comment les organiser. Le pipeline les applique à chaque étape. Utilisez-les pour des conseils de haut niveau, tels que :

Les sujets sur lesquels se concentrer, comme les préférences des clients et les détails du compte.
Le contenu à sauter, comme des étapes ponctuelles de dépannage.
Les chemins sous lesquels organiser les entrées.

Sans instructions de mise en page, le pipeline suit la disposition des entrées existantes du store, ou dérive une mise en page thématique lorsque le store est vide. Il ne renomme pas les entrées existantes pour correspondre à une nouvelle disposition. Pour modifier une entrée spécifique, il faut la modifier avec l’opération de mise à jour du magasin de mémoire au lieu d’utiliser des instructions.

Vous pouvez définir des instructions lors de la création d’un pipeline et les modifier plus tard. La prochaine exécution utilise les nouvelles instructions.

Briques de l’agent

Pour indiquer des instructions lors de la création d’un pipeline, passez --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/."

Pour charger des instructions plus longues à partir d’un fichier UTF-8, passez --instructions @<path-to-file> à la place.

Pour modifier les instructions d’un pipeline existant, exécutez la commande suivante :

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

REST API

Dans l’API REST, l’objet d’un dreamer_policy pipeline conserve ses paramètres de distillation : instructions et trigger. Pour définir des instructions lors de la création d’un pipeline, incluez-les dans 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/."}}'

Pour modifier les instructions d’un pipeline existant, mettez à jour 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."}}'

Exécutez un pipeline selon un planning

Un pipeline programmé s’exécute automatiquement environ toutes les 24 heures. Vous pouvez définir le déclencheur lorsque vous créez un pipeline, ou le modifier plus tard. Le planificateur choisit quand commence la première exécution planifiée. Pour condenser immédiatement les conversations existantes, lancez une exécution manuellement.

Briques de l’agent

Pour créer un pipeline planifié, passez --trigger scheduled. La valeur par défaut est --trigger manual:

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

Pour modifier le déclencheur d’un pipeline existant, exécutez ce qui suit :

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

REST API

Pour créer un pipeline planifié, définissez dreamer_policy.trigger sur 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"}}'

Pour modifier le déclencheur d’un pipeline existant, remplacez dreamer_policy.trigger par SCHEDULED ou 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"}}'

Vous pouvez aussi lancer manuellement une exécution d’un pipeline programmé, tant qu’aucune autre exécution n’est en cours.

Gérer les pipelines

Les commandes suivantes listent, inspectent, mettent à jour et suppriment les pipelines. Chaque commande CLI accepte soit l’ID du pipeline, soit son nom de ressource complet memory-pipelines/<pipeline-id>.

Tâche	CLI de l’agent Bricks	REST API
Lister les pipelines	`agentbricks memory pipeline list`	`GET /api/2.0/agents/memory-pipelines`
Obtenir un pipeline	`agentbricks memory pipeline get <pipeline-id>`	`GET /api/2.0/agents/memory-pipelines/<pipeline-id>`
Mettre à jour un pipeline	`agentbricks memory pipeline update <pipeline-id>` avec `--display-name`, `--model`, `--trigger`, ou `--instructions`	`PATCH /api/2.0/agents/memory-pipelines/<pipeline-id>` avec un `update_mask` de `display_name`, `model`, `dreamer_policy.trigger`, ou `dreamer_policy.instructions`
Supprimer un pipeline	`agentbricks memory pipeline delete <pipeline-id>`	`DELETE /api/2.0/agents/memory-pipelines/<pipeline-id>`

Si vous ne définissez pas de nom d’affichage, le pipeline en obtient un en fonction de ses noms du magasin de sessions et du magasin de mémoire. Pour revenir à un pipeline au modèle par défaut, mettez à jour son modèle à une valeur vide, telle que --model "". Les changements de modèle et d’instruction s’appliquent à la prochaine exécution.

Supprimer un pipeline supprime sa tâche associée et arrête les futures exécutions. Une partie déjà en cours se poursuit jusqu’à son terme. Les entrées mémoire déjà écrites par le pipeline restent dans la mémoire.

Limitations

Le magasin de sessions et le magasin en mémoire sont définis lorsque vous créez un pipeline. Pour changer l’un ou l’autre, supprimez le pipeline et créez-en un nouveau.
Si un pipeline connecte déjà le même stockage de session et stockage de mémoire, en créer un autre échoue avec ALREADY_EXISTS.
Un pipeline ne peut avoir qu’une seule exécution en cours à la fois. Démarrer une exécution alors qu’une autre est en cours échoue avec l’erreur ABORTED.
Les pipelines programmés s’exécutent environ toutes les 24 heures. Tu ne peux pas définir un intervalle différent ou un horaire cron.
Un pipeline ne traite que les acteurs ayant des sessions dans le magasin de sessions. Les entrées mémoire des acteurs sans sessions restent inchangées.
Si le magasin de session compte plus d’environ 1 200 acteurs avec des identifiants d’acteur UUID, l’exécution échoue. La limite est de 48 KiB d’identifiants d’acteur sérialisés, donc des identifiants plus courts permettent d’avoir plus d’acteurs.

Ressources additionnelles

Commentaires

Cette page a-t-elle été utile ?

Dernière mise à jour : 2026-10-16

Pipelines de mémoire d’agent

Requirements

Fonctionnement des pipelines mémoire

Ce qu’un pipeline conserve

Get started

Briques de l’agent

REST API

Surveiller les exécutions de pipeline

Orienter la distillation avec instructions

Briques de l’agent

REST API

Exécutez un pipeline selon un planning

Briques de l’agent

REST API

Gérer les pipelines

Limitations

Ressources additionnelles

Commentaires

Ressources supplémentaires