Mémoire de l’agent managé

La mémoire des agents gérés offre à vos agents IA une mémoire à long terme d’une conversation à l’autre. Azure Databricks gère l’infrastructure et isole la mémoire de chaque portée, de sorte que vous n’avez pas à gérer vous-même le stockage ni 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-le entre les agents et les projets.
• Améliorez la précision et l’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 correspond à la manière dont la mémoire gérée maintient séparés les souvenirs d’un agent pour différents utilisateurs ou groupes. Chaque entrée de mémoire appartient exactement à une étendue et une recherche retourne uniquement les entrées dans l’étendue que vous interrogez.

• Mémoire personnelle : Utilisez un ID d’utilisateur final comme étendue afin que chaque utilisateur obtienne sa propre mémoire privée, comme ses préférences et ses décisions passées. Les utilisateurs voient uniquement leurs propres entrées.
• Connaissances organisationnelles : Utilisez une clé partagée, telle qu’une organisation ou un ID d’équipe, pour stocker les connaissances sur laquelle tout utilisateur de l’agent peut tirer parti, comme les faits d’entreprise, les glossaires et les meilleures pratiques.

Un seul agent peut utiliser les deux simultanément : lire dans le périmètre personnel d’un utilisateur et dans un périmètre organisationnel partagé au cours de la même conversation. La scope valeur est requise pour chaque demande d’entrée de mémoire.

Prise en main de la mémoire managée

Le moyen le plus simple d’ajouter de la mémoire managée à un agent est la managed-memory compétence Claude Code. Il gère l’ensemble de l’installation pour vous. La compétence fonctionne avec OpenAI Agents SDK et 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 app-templatesmodèles d’agent, 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

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 serving de modèle Azure Databricks, connectez un stockage 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 stockage 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 stockage 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 stockage 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 à la 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 uniquement de la mémoire à long terme. Pour donner à votre agent une mémoire à court terme dans une session, utilisez l’une des options suivantes :

• Conserver l’état de session côté serveur avec une conversation.
• 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 de l’agent auto-managé.

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