Aller au contenu principal
Dernière mise à jour le

Mémoire des agents

info

Bêta

Cette fonctionnalité est en version bêta.

La mémoire des agents dote vos agents d’une mémoire à long terme qui persiste tout au long des conversations. Databricks stocke la mémoire dans Lakebase et gère le stockage, l'indexation et la recherche pour vous. Vos agents peuvent donc mémoriser les préférences des utilisateurs, les décisions passées et le contexte accumulé sans que vous ayez à exploiter une base de données.

remarque

Pendant la période d’aperçu, vous êtes facturé pour l’instance Lakebase sous-jacente qui stocke vos entrées de mémoire. Aucun frais supplémentaire ne s’applique à la mémoire de l’agent elle-même. Les tarifs sont susceptibles d’être modifiés au cours de l’aperçu.

Utilisez la mémoire des agents lorsque vous souhaitez que vos agents :

  • Mémorisez les préférences, les faits et les décisions des utilisateurs au fil de conversations distinctes.
  • Personnaliser les réponses en fonction de ce qu'un agent a appris lors des sessions précédentes.
  • Partagez les connaissances accumulées entre les agents et les projets.
  • Gagnez en précision et en efficacité au fil du temps.

La mémoire des agents fonctionne avec des agents construits sur n'importe quel framework. Pour l'historique des conversations à court terme lors d'une même interaction, utilisez des sessions d'agent.

Exigences​

  • Installez Python 3.10 ou version supérieure pour utiliser le SDK AgentKit. Le SDK AgentKit est le client Python Databricks pour les APIs d'agents que les exemples ci-dessous utilisent. Vous pouvez également appeler l'API REST directement depuis n'importe quel langage, sans nécessiter Python.
  • Pour utiliser memory_store.put() ou memory_store.list(path=...), installez databricks-agentbricks 0.6.0 ou une version supérieure.

Comment fonctionne la mémoire des agents​

Hiérarchie des ressources de mémoire de l’agent : un magasin de mémoire contient de nombreuses entrées de mémoire, chacune identifiée par actor_id, session_id facultatif et path, et contenant du contenu et une description.

La mémoire des agents comporte deux niveaux :

  • Un magasin de mémoire est le conteneur délimité par le workspace pour les mémoires d'un agent. La création d’un magasin provisionne automatiquement le stockage Lakebase sous-jacent. Vous adressez un magasin par son ID de magasin, que vous choisissez lors de la création du magasin.
  • Une entrée de mémoire est un élément de contenu individuel dans un magasin. Chaque entrée possède un texte content libre, un description court utilisé pour la récupération, ainsi qu’un ensemble de champs qui l’organisent et la partitionnent :
    • actor_id (obligatoire) : à qui appartient la mémoire, par exemple un utilisateur final ou un autre agent.
    • session_id (facultatif) : la session à laquelle appartient la mémoire. Laisser non défini pour la mémoire qui s'applique à toutes les sessions de l'acteur.
    • path (requis) : chemin d'accès de type système de fichiers qui organise les entrées au sein d'un acteur, tel que /preferences/response-style.md.

Une entrée est identifiée de manière unique par la combinaison de actor_id, session_id et path. Le même chemin sous deux sessions différentes, ou sous une session et sans session, contient deux entrées distinctes.

Les entrées sont ajoutées à un magasin de deux façons : votre agent ou votre application les écrit directement, ou un pipeline de mémoire en tire une synthèse à partir des conversations stockées dans un magasin de sessions.

Récupération​

Récupérez la mémoire de deux manières :

  • Liste des entrées pour un acteur, éventuellement filtrées par session_id, un préfixe path ou un path exact. Utilisez cela pour parcourir ou afficher un index de ce qu'un agent sait.
  • Rechercher des entrées pour un acteur avec une query en langage naturel. La recherche renvoie les entrées les plus pertinentes classées par score de pertinence.

Un filtre session_id sur l’une ou l’autre opération ne renvoie que les entrées enregistrées avec cette session. Il ne renvoie pas les entrées enregistrées sans session.

Commencer​

Ces exemples configurant la mémoire de l'agent pour un agent de support : ils créent un magasin de mémoire, enregistrent la préférence d'un utilisateur et la rappellent dans une conversation ultérieure. Choisissez le client qui correspond à votre projet. Un ID de magasin de mémoire doit comporter de 3 à 56 caractères, start par une lettre minuscule, se terminer par une lettre ou un chiffre, et ne contenir que des lettres minuscules, des chiffres et des tirets.

Le SDK AgentKit est le client Python Databricks pour les APIs d'agents, distribué dans le package databricks-agentbricks. Il s'authentifie auprès de WorkspaceClient du SDK Databricks.

  1. Installez le SDK AgentKit :

    Bash
    pip install databricks-agentbricks

  2. Create a memory store for your agent. AgentKitClient s’authentifie avec vos identifiants WorkspaceClient :

    Python
    from databricks.sdk import WorkspaceClient
    from databricks_agentkit import AgentKitClient

    client = AgentKitClient(WorkspaceClient())
    memory_store = client.memory_stores.create("support-agent-memory")

  3. Enregistrez une mémoire après que l'agent a appris quelque chose de durable sur un utilisateur. actor_id indique à qui appartient cette mémoire, path l'organise au sein de cet acteur, et description améliore la recherche :

    Python
    memory_store.add(
        actor_id="user-123",
        path="/preferences/communication.md",
        content="Prefers email over phone. Timezone: PST. Enterprise subscription.",
        description="User 123 communication preferences",
    )

    add() échoue avec ALREADY_EXISTS si une entrée existe déjà à ce chemin. Pour créer l'entrée ou mettre à jour l'entrée existante, appelez memory_store.put() avec les mêmes arguments.

  4. Rappelez les mémoires de l’utilisateur lors d’une conversation ultérieure à l’aide d’une recherche en langage naturel :

    Python
    results = memory_store.search(actor_id="user-123", query="communication preferences", limit=10)

Donnez à votre agent des outils de mémoire​

Afin de permettre à un agent de décider du moment où il convient d'enregistrer et de rappeler des informations en mémoire, enveloppez les opérations client sous forme d'outils et indiquez à l'agent quand les utiliser dans son invite système. Définissez le paramètre actor_id dans le code d'application de confiance à partir de l'identité vérifiée de l'utilisateur final. Ne laissez jamais le modèle choisir la mémoire de quel utilisateur il doit lire ou écrire.

L'exemple suivant encapsule le memory_store du SDK AgentKit provenant de Prise en main en tant qu'outils pour le SDK OpenAI Agents.

Python
from agents import Agent, function_tool

def make_memory_tools(memory_store, actor_id: str):
    @function_tool
    def search_memory(query: str) -> str:
        """Search long-term memory for relevant facts about the user."""
        results = memory_store.search(actor_id=actor_id, query=query, limit=10)
        return "\n\n".join(f"{r.memory.path}: {r.memory.content}" for r in results) or "No memory found."

    @function_tool
    def save_memory(path: str, content: str, description: str = "") -> str:
        """Save a durable, long-term memory about the user, replacing any memory at the same path."""
        memory_store.put(actor_id=actor_id, path=path, content=content, description=description or None)
        return f"Saved memory at {path}"

    @function_tool
    def list_memories() -> str:
        """List the paths and descriptions of the user's long-term memories."""
        memories = memory_store.list(actor_id=actor_id)
        return "\n".join(f"{m.path}: {m.description}" if m.description else m.path for m in memories) or "No memory found."

    @function_tool
    def forget_memory(path: str) -> str:
        """Delete the long-term memory at a path, such as when the user asks you to forget it."""
        memories = list(memory_store.list(actor_id=actor_id, path=path))
        for memory in memories:
            memory.delete()
        return f"Forgot memory at {path}" if memories else f"No memory at {path}"

    return [search_memory, save_memory, list_memories, forget_memory]

agent = Agent(
    name="Support agent",
    instructions="Save durable user preferences, recall them when relevant, and forget them when the user asks.",
    tools=make_memory_tools(memory_store, actor_id="user-123"),
)

put() crée l’entrée ou remplace le contenu de l’entrée déjà présente sur ce chemin d’accès. Pour ajouter le contenu en tant que nouvelles lignes, transmettez append=True. put() n'est pas atomique, donc les écritures simultanées sur le même chemin d'accès peuvent se remplacer mutuellement. list(path=...) renvoie les entrées situées exactement sur ce chemin d’accès dans chaque session, de sorte que forget_memory supprime également toute entrée enregistrée sur ce chemin d’accès dans le cadre d’une session.

Le même modèle fonctionne avec le SDK Claude Agent et d'autres frameworks : encapsulez les opérations de recherche, de mise, de liste et de suppression du magasin en tant que type d'outil du framework.

Si vous exécutez également un pipeline de mémoire sur le même magasin de mémoire, le pipeline peut réécrire, fusionner, diviser ou supprimer les entrées que votre agent enregistre pour tout acteur qu’il traite.

Partitionner et sécuriser la mémoire​

Au sein d'un magasin, actor_id est la méthode utilisée pour séparer les mémoires de chacun. Chaque liste et chaque recherche sont limitées à un seul actor_id. Choisissez donc la stratégie qui correspond à ce que votre agent doit mémoriser :

  • Mémoire privée pour chaque utilisateur : définissez actor_id sur l'identité vérifiée de l'utilisateur final. Chaque utilisateur obtient sa propre partition, et l'agent ne rappelle que les entrées de cet utilisateur.

    • 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 actor_id sur une clé fixe de votre choix, telle qu'un identifiant d'équipe, de projet ou d'organisation. Tout le monde lit et écrit les mêmes mémoires.

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

  • Division de la mémoire par un autre élément : construisez actor_id à partir de vos propres valeurs, telles qu’un ID de tenant ou un composite user:project.

    • Exemple : Une application multi-tenant définit actor_id sur {tenant}:{user} afin que les utilisateurs de chaque client restent isolés les uns des autres.

Définissez actor_id dans le code de votre application à partir d'un contexte d'appelant de confiance : l'identité vérifiée de l'utilisateur final pour la mémoire par utilisateur, ou une clé d'équipe ou de projet de confiance pour la mémoire partagée. Ne laissez jamais le modèle le choisir. Si votre stratégie repose sur l'identité d'un utilisateur final, rejetez les requêtes qui n'en comportent pas plutôt que de recourir à un actor_id partagé.

attention

actor_id sépare les mémoires, mais ce n'est pas un contrôle d'accès. Les magasins de mémoire sont limités au workspace, de sorte que tout principal pouvant accéder à un magasin peut lire et écrire chaque entrée pour tous les acteurs. Le magasin, et non l’acteur, est la limite de sécurité. Pour une isolation stricte entre les tenants ou les utilisateurs, créez un magasin de mémoire séparé pour chaque limite.

Pour permettre à un autre principal, tel que le service principal de votre agent, d'utiliser un magasin, accordez-lui l'accès avec l'opération accord-autorisation du magasin (memory_store.grant_permission(principal_id) dans le SDK AgentKit). Seul le créateur du magasin ou un administrateur du workspace peut accorder l'accès.

Limitations​

  • La mémoire des agents ne fournit qu'une mémoire à long terme. Pour l'historique de conversation à court terme, consultez les sessions d'agent.
  • La recherche classe les entrées par pertinence, combinant la recherche en texte intégral (BM25) et la correspondance sémantique sur le contenu et la description de chaque entrée. Il renvoie jusqu'à 100 entrées et ne prend pas en charge la pagination.
  • Le contrôle d'accès est appliqué au niveau du stockage. Le contrôle d'accès par entrée et par acteur n'est pas disponible.
  • Le contrôle d'accès au magasin couvre les entrées d'un magasin. Tout utilisateur de Workspace peut répertorier et obtenir les magasins de mémoire, y compris leurs ID et leurs descriptions.
  • Vous ne pouvez pas modifier l'ID d'un magasin après l'avoir créé. Seuls description peuvent être mis à jour.

Étapes suivantes​

Sur cette page