Mémoire de l’agent managé

La mémoire gérée des agents offre à vos agents une mémoire à long terme d’une conversation à l’autre. Azure Databricks gère l'infrastructure et isole les mémoires de chaque portée, de sorte que vous n'avez pas à gérer vous-même le stockage ou le partitionnement.

Avec la mémoire managée, vos agents peuvent :

• N’oubliez pas les préférences des utilisateurs, les décisions passées et le contexte cumulé entre les conversations.
• Sécurisez ces connaissances avec la gouvernance d’Unity Catalog.
• Partagez de la mémoire entre les agents et les projets.
• Améliorez leur précision et leur efficacité au fil du temps.

Requirements

• Un espace de travail Databricks avec Unity Catalog activé.
• Privilège CREATE MEMORY STORE sur le schéma parent pour créer des magasins de mémoire.

Fonctionnement de la mémoire managée

La mémoire managée a deux niveaux :

• Un magasin de mémoire est un catalogue Unity sécurisable qui agit comme un conteneur pour les entrées de mémoire. Un stockage mémoire hérite de la même gouvernance, des mêmes contrôles d’accès et de la même traçabilité que n’importe quelle autre ressource d’Unity Catalog.
• Une entrée de mémoire est un élément de contenu individuel stocké dans un magasin de mémoire. Chaque entrée est identifiée par une portée et un chemin d’accès. La portée détermine à quelles mémoires une entrée appartient, et le chemin organise les entrées au sein d’une portée, à la manière d’un chemin de fichier (par exemple, /memories/preferences.md).

Scope

La portée est la façon dont vous rendez une mémoire privée pour un utilisateur ou partagée entre un groupe. Votre application définit un périmètre à chaque lecture et écriture, et une recherche ne retourne que des entrées avec une portée correspondante. Choisissez la stratégie qui correspond à ce que votre agent doit retenir :

• Mémoire privée pour chaque utilisateur : Définissez la portée sur l’identité vérifiée de l’utilisateur final. Chaque utilisateur dispose de sa propre partition et ne voit que ses propres entrées. Cette valeur user_client récupère pour vous l’identifiant de l’utilisateur final.
  • Exemple : Un agent support se souvient des préférences de communication d’un utilisateur et des tickets passés.
• Mémoire partagée pour un groupe : Définissez le scope à une clé fixe que vous choisissez, comme un identifiant d’organisation, d’équipe ou de projet. Chaque utilisateur lit et écrit les mêmes souvenirs.
  • Exemple : Un agent d’équipe se souvient d’un glossaire partagé des termes de l’entreprise et des politiques internes.
• Mémoire partitionnée selon un autre critère : Créez le périmètre à partir de vos propres valeurs, comme un ID de locataire ou une valeur composite user_id:project.
  • Exemple : Une application multi-locataires maintient la mémoire de chaque client séparée, ou la mémoire d’un seul utilisateur est isolée par projet.

Un seul agent peut combiner des stratégies en une seule conversation. Par exemple, il peut lire la mémoire privée d’un utilisateur et la mémoire d’équipe partagée dans la même requête.

Définissez la portée dans le code de votre application, à partir d’un contexte d’appelant approuvé que la requête ne peut pas altérer : l’identité vérifiée de l’utilisateur final provenant du jeton OBO pour la mémoire par utilisateur, ou une clé de locataire, d’équipe ou de projet approuvée pour la mémoire partagée. Ne laissez jamais le modèle le choisir. Si votre stratégie de périmètre dépend d’une identité d’utilisateur final, rejetez les requêtes qui en sont dépourvues plutôt que de vous replier sur un périmètre partagé. Cette managed-memory compétence vous guide dans cette configuration.

La portée sépare les mémoires, mais n’accorde pas l’accès au magasin. Un appelant doit toujours disposer du privilège READ MEMORY STORE ou WRITE MEMORY STORE pour l’ouvrir. Voir Contrôle d’accès mémoire.

Ce que l’agent sauvegarde et rappelle

La mémoire gérée fournit le stockage mémoire et les API pour lire et écrire les entrées. Votre application contrôle ce que l’agent enregistre, quand il récupère la mémoire et comment il utilise les résultats.

Définissez ce comportement dans le prompt système de l’agent : indiquez-lui quelles informations conserver de manière persistante et quand les récupérer. La compétence managed-memory et les modèles conservent cette invite système dans une constante nommée MEMORY_INSTRUCTIONS. Scope est configuré séparément dans un code applicatif fiable et n’est jamais choisi par le modèle.

Adaptez la formulation à votre stratégie de portée. Voici un exemple de stratégie par utilisateur :

You have durable, cross-session memory about whoever (or whatever) this conversation is scoped to. Use it deliberately, not by reflex.

Recall whenever the answer is about the user or calls for personalized information — anything that might draw on preferences, decisions, or workflows they've shared before — and you don't already have it from this conversation; also list once before saving, to find the right existing topic. Don't tell the user you don't know their preferences without checking — list_memories first. Skip memory only when the answer truly doesn't depend on who's asking (general knowledge, math, coding) or you already have what you need. A `[has_contents]` entry has a body to get_memory; one without is fully captured by its description. Open a memory with get_memory before you state its specifics, and never assert a fact that isn't stored — if nothing relevant is stored, just answer without it. Don't re-list what you've already seen this turn.

Save only what will still matter in a future, unrelated conversation — a stable preference, fact, decision, or ongoing project the user actually stated or decided. Don't save your own suggestions or guesses, passing chatter, secrets, or anything scoped to this chat ("for now", a one-off label).
- Write each memory so it stands on its own out of context, under one broad, stable /memories/... topic per subject with the specifics inside it.
- Check the list first and update_memory an existing topic instead of minting a near-duplicate.
- For a very broad question that touches many memories, summarize from the list's descriptions; reserve get_memory for the specific entry you actually need.
- If the user's info changes or contradicts what's stored, update or replace it rather than keeping both — but don't rewrite a memory that already says the same thing.
- delete_memory what's stale.
- Briefly tell the user whenever you save, update, or delete.

Commencez par la gestion de la mémoire

Le moyen le plus simple d’ajouter de la mémoire managée à un agent est la managed-memory compétence Claude Code. La fonctionnalité prend en charge toute la configuration pour vous et fonctionne avec le SDK OpenAI Agents ainsi qu’avec LangGraph.

Ajoutez le skill à votre projet de deux façons :

Démarrer à partir d’un modèle

La compétence est fournie dans les modèles d’application Databricks. Créez un nouvel agent à partir de l’un des modèles d’agent, puis trouvez la compétence dans .claude/skills/managed-memory/.

1. Clonez le référentiel de modèles :

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

2. Parcourez les modèles d’agent app-templates, sélectionnez un modèle d’agent pour commencer. Par exemple, pour utiliser le modèle du SDK OpenAI Agents :

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

   Note

   Pour les modèles d’application « avancés », après le déploiement, vous devez accorder au principal de service de l’application les privilèges Lakebase Postgres ; sinon, l’initialisation de la session renverra une erreur 502.

3. Une fois que la compétence se trouve dans votre projet, décrivez ce que vous voulez et votre assistant de codage s’occupe du reste :

   Tip

   Add Databricks managed long-term memory to my agent.
   

Ajouter la compétence à un projet existant

Si vous disposez déjà d’un projet d’agent, ajoutez-y la compétence.

1. Créez le répertoire des compétences s’il n’existe pas :

   mkdir -p .claude/skills/managed-memory
   

2. Téléchargez le SKILL.md fichier à partir du managed-memory répertoire des compétences et enregistrez-le dans .claude/skills/managed-memory/.

3. Une fois que la compétence se trouve dans votre projet, décrivez ce que vous voulez et votre assistant de codage s’occupe du reste :

   Tip

   Add Databricks managed long-term memory to my agent.
   

Créer et utiliser un magasin de mémoire manuellement

Cette section montre comment créer et utiliser un magasin de mémoire sans la managed-memory compétence Claude Code.

L’exemple suivant configure la mémoire managée pour un agent de support client qui stocke les préférences d’un utilisateur et les récupère dans une conversation ultérieure.

1. Générez un jeton OAuth à l’aide de l’interface CLI Databricks pour appeler les API :

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

2. Créez un magasin de mémoire pour contenir les mémoires de votre agent :

   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. Écrivez une entrée de mémoire après que l’agent a appris quelque chose sur un utilisateur. Le scope attribue l’entrée à un seul utilisateur. Utilisez le champ contents pour le texte complet de la mémoire et le champ description comme court résumé afin d'améliorer la récupération :

   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. Recherchez les entrées de mémoire de cet utilisateur dans une conversation ultérieure pour récupérer ce que l’agent a appris :

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

Pour obtenir l’API REST complète, notamment les points de terminaison, les champs de requête et les champs de réponse, consultez la référence de l’API mémoire.

Ajouter de la mémoire à un agent grâce aux conversations

Le flux de travail REST ci-dessus appelle directement les API de magasin de mémoire et d’entrée. Lorsque vous créez un agent sur un point de terminaison de mise en service de modèles Azure Databricks, connectez un magasin de mémoire à une conversation avec le client compatible OpenAI dans le SDK databricks-openai à la place.

Une conversation est un état de conversation compatible avec OpenAI — l’historique en cours des messages et des appels d’outils — pris en charge par un magasin de mémoire et associé à une seule portée. Réutilisez la même conversation entre les requêtes pour donner à l’agent la mémoire des tours précédents.

1. Associez un magasin de mémoire existant et une portée à une nouvelle conversation. memory_store.name est le nom à trois niveaux de l’espace de stockage, et scope segmente l’état de la conversation, généralement selon l’utilisateur final :

   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. Passez l’ID de conversation à responses.create. L’agent lit et écrit l’état de la conversation dans le magasin de mémoire associé dans cette portée :

   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. Réutilisez le même ID de conversation sur les demandes ultérieures afin que l’agent se souvienne des tours précédents. Ne créez pas de nouvelle conversation à chaque tour :

   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)
   

Pour connaître les points de terminaison de conversation et les champs de requête, consultez les API de conversation.

Contrôle d’accès mémoire

Les espaces de stockage mémoire sont des objets sécurisables dans Unity Catalog. Les privilèges suivants contrôlent l’accès :

Implémenter la mémoire à court terme

Les API d’entrée de mémoire fournissent une mémoire à long terme en tant qu’outils pour que votre agent utilise. Pour doter votre agent d’une mémoire à court terme gérée dans une session, Databricks recommande d’associer votre stockage de mémoire à une conversation. Vous pouvez également :

• Conservez la mémoire de session de votre infrastructure d’agent, telle que le paramètre OpenAI session= ou un point de contrôle LangGraph.
• Utilisez la mémoire autogérée de l’agent pour le stockage de l’historique des conversations.

Recommandations de sécurité

Azure Databricks fournit un espace de stockage gouverné, le chiffrement, des mécanismes d’isolation et un journal d’audit. En tant que développeur d’applications, Databricks recommande les éléments suivants :

• Utilisez la valeur par défaut de l’étendue par utilisateur (user_client) sauf si vous avez une raison délibérée de partitionner différemment (par exemple, par projet ou par compte).
• Accordez le niveau de privilège minimal : seul le principal de service de votre agent a besoin de WRITE MEMORY STORE. Accordez READ MEMORY STORE de manière étroite et évitez les subventions étendues aux utilisateurs humains ou aux grands groupes.
• Protégez les informations d’identification du principal app service : il s’agit de la clé du plan de données du magasin. Traitez-le comme les informations d’identification de service à valeur élevée : utilisez des jetons de courte durée, évitez de le journaliser et ajoutez des défenses SSRF à votre application.

Limitations

• Les entrées de mémoire fournissent uniquement de la mémoire à long terme. Pour connaître la différence entre la mémoire à court terme et à long terme, consultez la mémoire à court terme et à long terme.
• Les magasins de mémoire et les entrées sont créés et gérés via l’API REST du catalogue Unity uniquement ; il n’existe aucun Python SDK pour ces API. Pour utiliser un stockage de mémoire depuis un agent, connectez-le à une conversation à l’aide du client compatible OpenAI. Consultez Doter un agent de mémoire à l’aide de conversations.

Étapes suivantes

• Informations de référence sur l’API mémoire