Aller au contenu principal
Dernière mise à jour le

Mémoire d'agent gérée

info

Bêta

Cette fonctionnalité est en version bêta.

La mémoire d’agent gérée confère à vos agents une mémoire durable à long terme qui persiste d’une conversation à l’autre. Databricks stocke la mémoire dans Lakebase et gère pour vous le stockage, l’indexation et la recherche sémantique, afin que vos agents puissent 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 l'aperçu, vous êtes facturé pour l'instance Lakebase sous-jacente qui stocke vos entrées de mémoire. Aucuns frais supplémentaires ne s'appliquent pour la mémoire d'agent gérée elle-même. Les tarifs sont susceptibles d'être modifiés au fur et à mesure que l'aperçu progresse.

Utilisez la mémoire gérée lorsque vous souhaitez que vos agents puissent :

  • 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 gérée fonctionne avec les agents construits sur n'importe quel framework. Pour l’historique des conversations à court terme au sein d’une seule interaction, utilisez les sessions d’agent gérées.

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

Hiérarchie des ressources de mémoire de l’agent managé : un magasin de mémoire contient de nombreuses entrées de mémoire, chacune identifiée par actor_id, un session_id optionnel et un chemin d’accès, et contenant du contenu ainsi qu’une description.

La mémoire gérée a 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.

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

Exigences​

  • Python 3.10 ou version ultérieure , pour utiliser Mason (le client Python et le CLI Databricks pour les APIs), employé dans les exemples ci-dessous. Vous pouvez également appeler l’ API REST directement depuis n’importe quel langage, sans nécessiter Python.

Commencer​

Ces exemples configurent une mémoire gérée pour un agent de support : ils créent un magasin de mémoire, enregistrent la préférence d’un utilisateur et la rappellent lors d’une conversation ultérieure. Choisissez le client qui convient à votre projet. Le paramètre display_name d'un magasin de mémoire doit comporter entre 3 et 56 caractères, start avec une lettre minuscule, se terminer par une lettre ou un chiffre, et ne contenir que des lettres minuscules, des chiffres et des tirets.

Mason est le client Python et la CLI de Databricks pour les API d’agents. Il s’authentifie auprès du WorkspaceClient du Databricks SDK.

  1. Installer Mason :

    Bash
    pip install databricks-mason

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

    Python
    from databricks.sdk import WorkspaceClient
    from databricks_mason import MasonClient

    mason = MasonClient(WorkspaceClient())
    memory_store = mason.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 Mason provenant de Premiers pas 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.

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 gérés ont une portée au niveau du workspace, de sorte que tout principal capable d’accéder à un magasin peut lire et écrire chaque entrée pour l’ensemble des acteurs. Le magasin, et non l’acteur, constitue la limite de sécurité. Pour assurer une isolation stricte entre les tenants ou les utilisateurs, créez un magasin de mémoire distinct par 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 de concession d'autorisation du magasin (memory_store.grant_permission(principal_id) dans Mason).

Limitations​

  • La mémoire gérée fournit uniquement une mémoire à long terme. Pour l'historique des conversations à court terme, consultez les sessions d'agent gérées.
  • 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