Mémoire d'agent gérée

info

Bêta

Cette fonctionnalité est en Bêta. Les administrateurs du Workspace peuvent contrôler l'accès à cette fonctionnalité à partir de la page Previews . Consultez Gérer les aperçus Databricks.

La mémoire gérée des agents confère à vos agents IA une mémoire à long terme à travers les conversations. Databricks gère l'infrastructure et isole les mémoires de chaque étendue, vous n'avez donc pas à gérer le stockage ou le partitionnement vous-même.

Avec la mémoire gérée, vos agents peuvent :

Mémorisez les préférences utilisateur, les décisions passées et le contexte accumulé entre les conversations.
Sécurisez ces connaissances grâce à la gouvernance Unity Catalog.
Partager la mémoire entre les agents et les projets.
Améliorez leur précision et leur efficacité au fil du temps.

Exigences

Un workspace Databricks avec Unity Catalog activé.
Le privilège CREATE MEMORY STORE sur le schéma parent pour créer des magasins de mémoire.

Fonctionnement de la mémoire gérée

La mémoire gérée a deux niveaux :

Un magasin de mémoire est un élément sécurisable de Unity Catalog qui agit comme un conteneur pour les entrées de mémoire. Un magasin de mémoire hérite de la même gouvernance, du même contrôle d'accès et de la même traçabilité que tout autre asset de 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. Le périmètre détermine à quelles mémoires une entrée appartient, et le chemin organise les entrées au sein d'un périmètre, à l'instar d'un chemin de fichier (par exemple, /memories/preferences.md).

Portée

La portée correspond à la façon dont la mémoire gérée maintient les mémoires d'un agent séparées pour différents utilisateurs ou groupes. Chaque entrée de mémoire appartient à un seul scope, et une recherche ne renvoie que les entrées du scope que vous query.

Mémoire personnelle : utilisez un ID d'utilisateur final comme portée afin que chaque utilisateur dispose de sa propre mémoire privée, telle que ses préférences et ses décisions passées. Les utilisateurs ne voient que leurs propres entrées. La valeur de la portée user_client récupère automatiquement l'ID de l'utilisateur final.
Connaissances organisationnelles : Utilisez une clé partagée, telle qu'un ID d'organisation ou d'équipe, pour stocker des connaissances que tout utilisateur de l'agent peut exploiter, tels que des faits sur l'entreprise, des glossaires et des bonnes pratiques.

Un seul agent peut utiliser les deux à la fois : lire à partir du périmètre personnel d'un utilisateur et d'un périmètre organisationnel partagé dans la même conversation. Le scope est requis sur chaque demande d'entrée de mémoire.

attention

La portée est la limite d'isolement entre les utilisateurs. Configurez le périmètre dans un code fiable et ne laissez jamais le modèle le définir. Le Service Principal de l'application Databricks peut lire chaque périmètre.

Premiers pas avec les compétences en matière de mémoire gérée

Le moyen le plus simple d'ajouter de la mémoire gérée à un agent est la compétence Claude Code managed-memory. La compétence gère toute la configuration pour vous et fonctionne avec le SDK OpenAI Agents et LangGraph.

Intégrez la compétence dans votre projet de deux façons :

Start from a template
Add the skill to an existing project

La compétence est intégrée aux templates d'application Databricks. Créez un nouvel agent à partir de l'un des Template d'agent, retrouvez la compétence sous .claude/skills/managed-memory/.

Clonez le Template repository :

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

Parcourez le app-templates, sélectionnez un Template d'agent pour start. Par exemple, pour utiliser le Template SDK OpenAI Agents :
Bash
```
cd app-templates/agent-openai-agents-sdk
```

remarque

Pour les « advanced » app Template, après le déploiement, vous devez accorder des privilèges au Service Principal d’application Lakebase Postgres, sinon la configuration de la session renverra une erreur 502.

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

prompt

Add Databricks managed long-term memory to my agent.

Si vous avez déjà un projet d'agent, ajoutez-lui la compétence.

Créez le répertoire des compétences s’il n’existe pas :
Bash
```
mkdir -p .claude/skills/managed-memory
```
Download le fichier SKILL.md à partir du répertoire de compétencesmanaged-memory et enregistrez-le dans .claude/skills/managed-memory/.
Une fois la compétence dans votre projet, décrivez ce que vous voulez et votre assistant de codage s'occupe du reste :

prompt

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 compétence Claude Code managed-memory.

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

Générer un jeton OAuth à l’aide de l’interface de ligne de commande Databricks pour appeler les APIs :
Bash
```
databricks auth login --host ${DATABRICKS_HOST}
databricks auth token
```

Créez un magasin de mémoire pour conserver la mémoire de votre agent :

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

Écrivez une entrée de mémoire après que l'agent a appris quelque chose sur un utilisateur. Le scope partitionne l'entrée pour un seul utilisateur. Utilisez le champ contents pour le texte complet de la mémoire et le description comme un court résumé qui améliore la récupération :

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

Recherchez les entrées de mémoire pour cet utilisateur dans une conversation ultérieure afin de récupérer ce que l'agent a appris :

Bash
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 l’API REST complète, y compris les Endpoint, les champs de requête et les champs de réponse, consultez la référence de l’API API.

Ajouter de la mémoire à un agent avec des conversations

Le workflow REST ci-dessus appelle directement le magasin de mémoire et les APIs d'entrée. Lorsque vous créez un agent sur un Endpoint de service de modèle Databricks, connectez plutôt un magasin de mémoire à une conversation avec le client compatible OpenAI dans le SDK databricks-openai.

Une conversation est un état de conversation compatible avec OpenAI — l'historique des exécutions des messages et des appels d'outils — sauvegardé par un magasin de mémoire et épinglé à une portée unique. Réutilisez la même conversation à travers les requêtes pour donner à l'agent une mémoire des tours précédents.

Liez un magasin de mémoire existant et un scope à une nouvelle conversation. memory_store.name est le nom à trois niveaux du stockage, et scope partitionne l'état de la conversation, généralement par utilisateur final :

Python
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={
     &quot;memory_store&quot;: {&quot;name&quot;: &quot;main.default.support_agent_memory&quot;},
     &quot;scope&quot;: {&quot;kind&quot;: &quot;user&quot;, &quot;value&quot;: user_id},
 },
)

Transmettez l'ID de conversation à responses.create. L'agent lit et écrit l'état de la conversation dans le magasin de mémoire lié sous cette portée :

Python
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)

Réutilisez le même ID de conversation lors des requêtes ultérieures afin que l'agent se souvienne des tours précédents. Ne créez pas une nouvelle conversation par tour :

Python
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 les Endpoint de conversation et les champs de requête, consultez les APIs de conversation.

Contrôle d’accès à la mémoire

Les magasins de mémoire sont des éléments sécurisables d'Unity Catalog. Les privilèges suivants contrôlent l'accès :

Privilège	S'applique à	Description
`CREATE MEMORY STORE`	Schéma parent	Créez de nouveaux magasins de mémoire sous un schéma.
`READ MEMORY STORE`	Stockage en mémoire	Lire les métadonnées et les entrées d'un magasin de mémoire.
`WRITE MEMORY STORE`	Stockage en mémoire	Créer, mettre à jour et supprimer des entrées de mémoire dans un magasin.
`MANAGE`	Stockage en mémoire	Mettre à jour ou supprimer le magasin de mémoire lui-même. Accorder des autorisations à d'autres utilisateurs.
`USE SCHEMA`	Schéma parent	Répertorier les magasins de mémoire dans un schéma.

Privilège	S'applique à	Description
`CREATE MEMORY STORE`	Schéma parent	Créez de nouveaux magasins de mémoire sous un schéma.
`READ MEMORY STORE`	Stockage en mémoire	Lire les métadonnées et les entrées d'un magasin de mémoire.
`WRITE MEMORY STORE`	Stockage en mémoire	Créer, mettre à jour et supprimer des entrées de mémoire dans un magasin.
`MANAGE`	Stockage en mémoire	Mettre à jour ou supprimer le magasin de mémoire lui-même. Accorder des autorisations à d'autres utilisateurs.
`USE SCHEMA`	Schéma parent	Répertorier les magasins de mémoire dans un schéma.

Implémenter la mémoire à court terme

Les APIs d'entrée de mémoire fournissent une mémoire à long terme que votre agent peut utiliser comme outils. Pour donner à votre agent une mémoire à court terme gérée dans une session, Databricks vous recommande de lier votre magasin de mémoire à une conversation. Vous pouvez également :

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

Recommandations de sécurité

Databricks fournit le stockage gouverné, le chiffrement, les primitives d'isolation et la piste d'audit. En tant que développeur d'applications, Databricks recommande ce qui suit :

Utilisez la valeur default de l'étendue par utilisateur (user_client), sauf si vous avez une raison délibérée de partitionner différemment (par exemple, la mémoire par projet ou par compte).
Accorder le moindre privilège : seul le Service Principal Databricks de votre agent nécessite WRITE MEMORY STORE. Accordez READ MEMORY STORE de manière restreinte, et évitez les attributions larges aux utilisateurs humains ou aux grands groupes.
Protégez l'identifiant du service principal Databricks de l'application : c'est la clé du plan de données du magasin. Traitez-le comme n'importe quel identifiant de service de grande valeur — utilisez des jetons de courte durée, évitez de le consigner et ajoutez des défenses SSRF à votre application.

Limitations

Les entrées de mémoire fournissent uniquement une mémoire à long terme. Pour la différence entre la mémoire à court et à long terme, consultez Mémoire à court et à long terme.
Les magasins de mémoire et les entrées sont créés et gérés uniquement via l'API REST Unity Catalog ; il n'existe pas de SDK Python pour ces APIs. Pour utiliser un magasin de mémoire d'un agent, connectez-le à une conversation avec le client compatible OpenAI. Consultez Ajouter de la mémoire à un agent avec des conversations.

Étapes suivantes

Référence de l'API de la mémoire

Exigences​

Fonctionnement de la mémoire gérée​

Portée​

Premiers pas avec les compétences en matière de mémoire gérée​

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

Ajouter de la mémoire à un agent avec des conversations​

Contrôle d’accès à la mémoire​

Implémenter la mémoire à court terme​

Recommandations de sécurité​

Limitations​

Étapes suivantes​