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 donne à vos agents une mémoire à long terme qui persiste à travers les conversations. Databricks stocke la mémoire dans Lakebase et gère le stockage, l’indexation et la recherche sémantique pour vous, afin que vos agents puissent se souvenir des préférences des utilisateurs, des décisions passées et du 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.

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 entraîne le provisionnement automatique du stockage Lakebase sous-jacent. Vous désignez un magasin par son display_name.
  • 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 (optionnel) : enregistre la session à partir de laquelle la mémoire a été capturée, à des fins de traçage et de provenance. Laissez ce champ non défini pour la mémoire qui n'est pas liée à une session spécifique.
    • 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.

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 :

  • Lister les entrées pour un acteur, éventuellement filtrées par session_id ou par un préfixe path. Utilisez cette option pour parcourir ou restituer un index de ce qu'un agent sait.
  • Recherchez 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 en texte intégral (BM25).

Commencer​

Ces exemples configurent la mémoire d’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 adapté à votre projet. Le display_name d’un magasin de mémoire doit comporter entre 3 et 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",
    )

  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."""
        memory_store.add(actor_id=actor_id, path=path, content=content, description=description)
        return f"Saved memory at {path}"

    return [search_memory, save_memory]

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

Le même modèle fonctionne avec le SDK Claude Agent et d'autres frameworks : encapsulez les opérations de recherche et d'ajout 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 à l’aide de l’opération d’attribution d’autorisations du magasin (memory_store.grant_permission(principal_id) dans le SDK AgentKit).

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 est une opération en texte intégral (BM25) classée par pertinence qui renvoie un ensemble de résultats top-N pouvant aller jusqu'à 100 entrées. Elle ne prend pas en charge la pagination ou la recherche de similarité vectorielle.
  • 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 magasin display_name est immuable après sa création. Seul description peut être mis à jour.

Étapes suivantes​

Sur cette page