Aller au contenu principal
Dernière mise à jour le

Pipelines de mémoire des agents

info

Bêta

Cette fonctionnalité est en bêta.

Un pipeline de mémoire crée une mémoire à long terme à partir des conversations passées de votre agent. Il lit l’historique des conversations depuis un magasin de sessions et en extrait des souvenirs à long terme, tels que des faits, des préférences et des procédures, dans un magasin de mémoire. Votre agent se remémore ensuite ces souvenirs lors de conversations ultérieures, de la même manière qu’il se remémore ceux qu’il a enregistrés lui-même.

Un agent qui enregistre des souvenirs au cours d’une conversation les écrit une conversation à la fois, en utilisant uniquement le contexte de cette conversation. Au fil des conversations, sa mémoire accumule des entrées qui se chevauchent et se contredisent, et les faits que l’agent n’a pas pensé à enregistrer ne sont pas conservés dans sa mémoire. Un pipeline de mémoire fonctionne a posteriori, avec toutes les conversations d’un acteur et la mémoire existante sous les yeux, ce qui lui permet de capturer ce que l’agent a manqué et de maintenir la mémoire consolidée.

Utilisez un pipeline de mémoire lorsque vous souhaitez :

  • Créez une mémoire à long terme à partir des conversations sans ajouter d’outils d’écriture de mémoire à votre agent.
  • Reconstituer la mémoire à partir de l’historique de conversation déjà conservé par un magasin de sessions.
  • Gardez la mémoire organisée au fil du temps en fusionnant les entrées qui se chevauchent et en divisant celles qui sont trop volumineuses.

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

remarque

Les exécutions du pipeline de mémoire utilisent les tarifs du compute général Serverless pour le Job et les tarifs de Model Serving pour les modèles de fondation pour les appels de modèles.

Exigences​

  • Un magasin de sessions qui conserve les conversations de votre agent, et un magasin de mémoire où écrire des souvenirs.
  • Accès aux deux magasins pour l’identité qui crée le pipeline, y compris l’autorisation de créer des tables dans la base de données du magasin mémoire. Les exécutions du pipeline utilisent cette identité.
  • Autorisation de query le modèle que le pipeline utilise pour la distillation.
  • Pour utiliser la CLI, installez databricks-agentbricks 0.5.0 ou une version ultérieure. Vous pouvez également appeler directement l’ API REST depuis n’importe quel langage.

Comment fonctionnent les pipelines de mémoire​

Un pipeline de mémoire est une ressource de mémoire d’agent qui relie un magasin de sessions à un magasin de mémoire. Cela n’a pas de rapport avec les pipelines LakeFlow Pipelines. Un magasin de sessions peut alimenter plusieurs magasins de mémoire, mais chaque paire de magasins de sessions et de mémoire ne peut être associée 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 ultérieurement. Si vous n’en choisissez pas, le pipeline utilise un modèle default.
  • Exécutions manuelles ou planifiées sur un compute Serverless : vous start vous-même les exécutions, ou configurez le pipeline pour qu’il s’exécute selon une planification environ toutes les 24 heures. Dans les deux cas, chaque exécution est exécutée en tant que Job sur un compute Serverless, sous l’identité ayant créé le pipeline.

Chaque exécution du pipeline traite séparément chaque acteur du magasin de sessions :

  1. Distiller : Le pipeline lit les nouvelles conversations de l’acteur et utilise un LLM pour en extraire des faits durables.
  2. Merge : Le pipeline déduplique les nouveaux faits et les fusionne dans des entrées de mémoire organisées par sujet sous le même actor_id dans le magasin de mémoire.
  3. Maintenance : Le pipeline réorganise la mémoire de l’acteur. Il fusionne les entrées qui se chevauchent et divise celles qui deviennent trop volumineuses.

Les exécutions du pipeline de mémoire conservent un point de contrôle pour chaque ID d’acteur. Une exécution traite toutes les sessions d’un acteur depuis sa dernière exécution réussie ; la première exécution traite donc l’historique complet de l’acteur. Si une exécution échoue pour un acteur, elle se poursuit avec les autres acteurs, et l’exécution suivante relance l’acteur en échec à partir de son point de contrôle.

Le actor_id Link les deux magasins. Un pipeline traite uniquement les acteurs qui ont des sessions dans le magasin de sessions, et écrit les mémoires de chaque acteur sous le même actor_id que celui utilisé par les sessions de l’acteur. Par default, un pipeline s’exécute uniquement lorsque vous start une exécution. Vous pouvez également programmer son exécution.

remarque

La maintenance s’applique à toutes les entrées de mémoire d’un acteur, y compris celles que votre agent a enregistrées directement. Un pipeline peut réécrire, fusionner, scinder ou supprimer toute entrée dans 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 conserver :

  • Les faits que l’utilisateur énonce explicitement et les préférences qu’il exprime, sans extrapoler au-delà de ce que dit la conversation.
  • Corrections et commentaires explicites, par exemple sur la source à utiliser pour les chiffres de revenus.
  • Connaissances durables du domaine, telles que les sources faisant autorité, les définitions des 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 :

  • Valeurs issues de sources actives qui évoluent au fil du temps, telles que le nombre actuel de lignes d’une table. Il enregistre comment trouver ou compute la valeur à la place.
  • Détails que l’agent peut consulter avec ses outils, comme le schéma d’une table.
  • Secrets, tels que les mots de passe, les clés API, et les jetons.

start​

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

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

  1. Installez la CLI Agent Bricks ou mettez-la à niveau vers la version 0.5.0 ou ultérieure :

    Bash
    pip install --upgrade databricks-agentbricks

  2. 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 default :

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

    La commande renvoie le nom de ressource du pipeline, sous la forme memory-pipelines/<pipeline-id>.

  3. Start une exécution du pipeline :

    Bash
    agentbricks memory pipeline run <pipeline-id>

    La commande renvoie le nom de la ressource de l’exécution, au format memory-pipelines/<pipeline-id>/runs/<run-id>, et son état RUNNING.

  4. La CLI ne signale pas le résultat d’une exécution. Pour le vérifier, définissez DATABRICKS_HOST sur le Hostname de votre Workspace, générez un jeton OAuth et appelez l’API REST :

    Bash
    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}"

Une fois l'exécution réussie, votre agent peut rappeler les nouveaux souvenirs avec les opérations de liste et de recherche de la mémoire de stockage. Voir Mémoire des agents.

Surveiller les exécutions du pipeline​

Le state d’une exécution est l’une des valeurs suivantes :

État

Signification

RUNNING

L’exécution est en attente ou en cours.

SUCCEEDED

L’exécution a traité chaque acteur avec succès.

FAILED

L’exécution s’est terminée avec une erreur pour un ou plusieurs acteurs. Le champ error décrit l’échec.

CANCELLED

L’exécution a été annulée avant d’être terminée.

État

Signification

RUNNING

L’exécution est en attente ou en cours.

SUCCEEDED

L’exécution a traité chaque acteur avec succès.

FAILED

L’exécution s’est terminée avec une erreur pour un ou plusieurs acteurs. Le champ error décrit l’échec.

CANCELLED

L’exécution a été annulée avant d’être terminée.

Guidez la distillation à l’aide d’instructions​

Les instructions indiquent au pipeline ce qu’il doit conserver et comment l’organiser. Le pipeline les applique à chaque étape. Utilisez-les pour obtenir des indications de haut niveau, par exemple :

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

Sans instructions de layout, le pipeline suit le layout des entrées existantes du magasin ou déduit un layout basé sur les thèmes lorsque le magasin est vide. Il ne renomme pas les entrées existantes pour les faire correspondre à un nouveau layout. Pour modifier une entrée spécifique, modifiez-la à l’aide de l’opération de mise à jour du magasin de mémoire plutôt qu’avec des instructions.

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

Pour définir des instructions lors de la création d’un pipeline, transmettez --instructions:

Bash
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, transmettez plutôt --instructions @<path-to-file>.

Pour modifier les instructions d’un pipeline existant, exécutez ce qui suit :

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

Exécuter un pipeline selon un calendrier​

Un pipeline planifié s’exécute automatiquement environ toutes les 24 heures. Vous pouvez définir le trigger lors de la création d’un pipeline, ou le modifier ultérieurement. Le planificateur choisit quand start la première exécution programmée. Pour distiller immédiatement les conversations existantes, effectuez un start manuellement.

Pour créer un pipeline planifié, transmettez --trigger scheduled. La default est --trigger manual:

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

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

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

Vous pouvez également start manuellement une exécution d’un pipeline planifié, à condition qu’aucune autre exécution ne soit en cours.

Gérer les pipelines​

Les commandes suivantes permettent de répertorier, d’inspecter, de mettre à jour et de supprimer des pipelines. Chaque commande CLI accepte soit l’ID du pipeline, soit le nom complet de la ressource memory-pipelines/<pipeline-id>.

Tâche

Agent Bricks CLI

API REST

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>

Tâche

Agent Bricks CLI

API REST

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 reçoit un basé sur les noms de son magasin de sessions et de son magasin de mémoire. Pour rétablir le modèle default d’un pipeline, définissez son modèle sur une valeur vide, telle que --model "". Les modifications apportées au modèle et aux instructions s’appliquent à la prochaine exécution.

La suppression d’un pipeline supprime le Job associé et arrête les exécutions futures. Une exécution déjà en cours se poursuit jusqu’à son terme. Les entrées de mémoire déjà écrites par le pipeline restent dans le magasin de mémoire.

Limitations​

  • Le magasin de sessions et le magasin de mémoire sont définis lors de la création d’un pipeline. Pour modifier l’un ou l’autre, supprimez le pipeline et créez-en un nouveau.
  • Si un pipeline connecte déjà le même magasin de sessions et le même magasin de mémoire, la création d’un autre échoue avec ALREADY_EXISTS.
  • Un pipeline ne peut avoir qu’une seule exécution en cours à la fois. Le démarrage d’une exécution alors qu’une autre est en cours échoue avec une erreur ABORTED.
  • Les pipelines planifiés s’exécutent environ toutes les 24 heures. Vous ne pouvez pas définir un intervalle différent ni un calendrier cron.
  • Un pipeline traite uniquement les acteurs qui ont des sessions dans le magasin de sessions. Les entrées de mémoire des acteurs sans session restent inchangées.
  • Si le magasin de sessions contient environ 1200 acteurs ou plus avec des ID d’acteur UUID, l’exécution échoue. La limite est de 48 Kio d’ID d’acteur sérialisés, donc des ID plus courts permettent d’inclure davantage d’acteurs.

Ressources supplémentaires​

Sur cette page