Aller au contenu principal
Dernière mise à jour le

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 de l'agent confère à vos agents une mémoire à long terme à travers les conversations. Databricks exécute 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​

Le périmètre (scope) est la manière dont vous rendez une mémoire privée pour un utilisateur ou partagée au sein d’un groupe. Votre application définit un périmètre pour chaque lecture et écriture, et une recherche ne renvoie que les entrées dont le périmètre correspond. Choisissez la stratégie qui correspond aux éléments dont votre agent doit se souvenir :

  • Mémoire privée pour chaque utilisateur : définissez le périmètre sur l’identité vérifiée de l’utilisateur final. Chaque utilisateur obtient sa propre partition et ne voit que ses propres entrées. La valeur user_client résout l’ID de l’utilisateur final pour vous.

    • Exemple : un agent d’assistance se souvient des préférences de communication et des tickets passés d’un utilisateur.

  • Mémoire partagée pour un groupe : définissez le périmètre sur une clé fixe de votre choix, telle qu’un identifiant d’organisation, d’équipe ou de projet. Chaque utilisateur lit et écrit dans les mêmes mémoires.

    • Exemple : un agent d'équipe mémorise un glossaire partagé de termes d'entreprise et de politiques internes.

  • Mémoire divisée par autre chose : construisez la portée à partir de vos propres valeurs, telles qu’un ID de tenant ou un composite user_id:project.

    • Exemple : une application multi-tenant maintient la mémoire de chaque client séparée, ou la mémoire d'un utilisateur unique est isolée par projet.

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

Définissez le périmètre 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 issue du jeton OBO pour la mémoire par utilisateur, ou une clé de tenant, 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 de l’identité d’un utilisateur final, rejetez les requêtes qui n’en possèdent pas plutôt que de revenir à un périmètre partagé. La compétencemanaged-memory vous guide tout au long de cette configuration.

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

attention

Le périmètre (scope) constitue la limite d’isolation entre les utilisateurs, mais il ne s’agit pas d’un contrôle d’accès. Le Service Principal Databricks de l’application peut lire tous les périmètres ; protégez donc ses informations d’identification en conséquence.

Ce que l’agent enregistre et mémorise​

La mémoire gérée fournit le magasin de mémoire et les APIs pour la lecture et l'écriture d'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 l'invite système de l'agent : demandez à l'agent quelles informations durables enregistrer et quand les récupérer. La compétence managed-memory et le Template conservent cette invite système dans une constante nommée MEMORY_INSTRUCTIONS. Le périmètre est configuré séparément dans le code de l'application approuvée et n'est jamais choisi par le modèle.

Adaptez la formulation à votre stratégie de périmètre. Voici un exemple pour la 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.

start avec les compétences 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 :

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/.

  1. Clonez le Template repository :

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

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

  1. 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.

  1. 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

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

  3. É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"
      }'

  4. 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.

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

  2. 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)

  3. 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 de l'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​

Sur cette page