Guide de démarrage rapide de l'API Agent Platform Memory Bank

Agent Platform Memory Bank vous permet d'effectuer des appels d'API directement vers Sessions et Memory Bank à l'aide du SDK Agent Platform. Utilisez le SDK Agent Platform si vous ne souhaitez pas qu'un framework d'agent orchestre les appels pour vous, ou si vous souhaitez intégrer Sessions et Memory Bank à des frameworks d'agent autres qu'Agent Development Kit (ADK).

Ce document explique comment créer, importer, récupérer et supprimer des souvenirs à l'aide d'appels d'API.

Pour le guide de démarrage rapide avec ADK, consultez Guide de démarrage rapide de Memory Bank avec ADK.

Avant de commencer

Pour suivre les étapes décrites dans ce tutoriel, vous devez d'abord suivre les étapes de la section Configurer Memory Bank.

Générer des souvenirs avec Agent Platform Sessions

Après avoir configuré Agent Platform Sessions et Memory Bank, vous pouvez créer des sessions et y ajouter des événements. Les souvenirs sont générés sous forme de faits à partir de la conversation de l'utilisateur avec l'agent, de sorte qu'ils soient disponibles pour les futures interactions de l'utilisateur. Pour en savoir plus, consultez Générer des souvenirs et Récupérer des souvenirs.

  1. Créez une session avec un ID utilisateur opaque. Tous les souvenirs générés à partir de cette session sont automatiquement associés à la clé du champ d'application {"user_id": "USER_ID"}, sauf si vous fournissez explicitement un champ d'application lors de la génération des souvenirs.

    import vertexai

client = vertexai.Client(
project="PROJECT_ID",
location="LOCATION"
)

# This assumes that you already have an Agent Platform instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
# The name can be fetched using `agent_engine.api_resource.name`.
name="AGENT_ENGINE_NAME",
user_id="USER_ID"
)

    Remplacez les éléments suivants :

    • PROJECT_ID : ID de votre projet

    • LOCATION : votre région Consultez les régions où Memory Bank est disponible .

    • AGENT_ENGINE_NAME : nom de l' instance Agent Platform que vous avez créée ou d'une instance Agent Platform existante. Le nom doit être au format suivant : projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

    • USER_ID : identifiant de votre utilisateur. Tous les souvenirs générés à partir de cette session sont automatiquement associés à la clé du champ d'application {"user_id": "USER_ID"}, sauf si vous fournissez explicitement un champ d'application lors de la génération des souvenirs.

  2. Importez des événements de manière itérative dans votre session. Les événements peuvent inclure toutes les interactions entre votre utilisateur, votre agent et vos outils. La liste ordonnée des événements représente l'historique des conversations de votre session. Cet historique des conversations est utilisé comme source pour générer des souvenirs pour cet utilisateur spécifique.

    import datetime

client.agent_engines.sessions.events.append(
name=session.response.name,
author="user",  # Required by Sessions.
invocation_id="1",  # Required by Sessions.
timestamp=datetime.datetime.now(tz=datetime.timezone.utc),  # Required by Sessions.
config={
  "content": {
    "role": "user",
    "parts": [{"text": "hello"}]
  }
}
)

  3. Pour générer des souvenirs à partir de votre historique des conversations, déclenchez une demande de génération de souvenirs pour la session :

    client.agent_engines.memories.generate(
name=agent_engine.api_resource.name,
vertex_session_source={
  # `session` should have the format "projects/.../locations/.../reasoningEngines/.../sessions/...".
"session": session.response.name
},
# Optional when using Sessions. Defaults to {"user_id": session.user_id}.
scope=SCOPE
)

Remplacez les éléments suivants :

  • (Facultatif) SCOPE : dictionnaire représentant le champ d'application des souvenirs générés, avec un maximum de cinq paires clé/valeur et aucun * caractère. Par exemple, {"session_id": "MY_SESSION"}. Seuls les souvenirs ayant le même champ d'application sont pris en compte pour la consolidation. Si aucune valeur n'est fournie, {"user_id": session.user_id} est utilisé.

Importer des souvenirs

Au lieu de générer des souvenirs à l'aide d'un dialogue brut, vous pouvez importer des souvenirs ou demander à vos agents de les ajouter directement à l'aide de GenerateMemories avec des faits pré-extraits. Au lieu que Memory Bank extraie des informations de votre contenu, vous fournissez directement les faits à stocker concernant votre utilisateur.

Pour garantir la cohérence avec les souvenirs générés, essayez d' écrire des faits pré-extraits dans la même perspective que celle que vous avez configurée pour le champ d'application donné. Par défaut, les souvenirs sont générés à la première personne (par exemple, I am a software engineer).

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Remplacez les éléments suivants :

  • FACT : fait pré-extrait qui doit être consolidé avec les souvenirs existants. Vous pouvez fournir jusqu'à cinq faits pré-extraits dans une liste comme celle-ci :

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE : dictionnaire représentant le champ d'application des souvenirs générés. Par exemple, {"session_id": "MY_SESSION"}. Seuls les souvenirs ayant le même champ d'application sont pris en compte pour la consolidation.

Vous pouvez également utiliser CreateMemory pour importer des souvenirs sans utiliser Memory Bank pour l'extraction ou la consolidation des souvenirs.

memory = client.agent_engines.memories.create(
    name=agent_engine.api_resource.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns an AgentEngineMemoryOperation containing the created Memory like:

AgentEngineMemoryOperation(
  done=True,
  metadata={
    "@type': 'type.googleapis.com/google.cloud.aiplatform.v1beta1.CreateMemoryOperationMetadata",
    "genericMetadata": {
      "createTime": '2025-06-26T01:15:29.027360Z',
      "updateTime": '2025-06-26T01:15:29.027360Z'
    }
  },
  name="projects/.../locations/us-central1/reasoningEngines/.../memories/.../operations/...",
  response=Memory(
    create_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC)),
    fact="This is a fact.",
    name="projects/.../locations/us-central1/reasoningEngines/.../memories/...",
    scope={
      "user_id": "123"
    },
    update_time=datetime.datetime(2025, 6, 26, 1, 15, 29, 27360, tzinfo=TzInfo(UTC))
  )
)
"""

Récupérer et utiliser des souvenirs

Vous pouvez récupérer des souvenirs pour votre utilisateur et les inclure dans les instructions de votre système afin de donner au LLM accès à votre contexte personnalisé.

Pour en savoir plus sur la récupération de souvenirs à l'aide d'une méthode basée sur le champ d'application, consultez Récupérer des souvenirs.

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

Vous pouvez utiliser jinja pour convertir vos souvenirs structurés en invite :


from jinja2 import Template

template = Template("""
<MEMORIES>
Here is some information about the user:
{% for retrieved_memory in data %}* {{ retrieved_memory.memory.fact }}
{% endfor %}</MEMORIES>
""")

prompt = template.render(data=retrieved_memories)

"""
Output:

<MEMORIES>
Here is some information about the user:
* This is a fact
</MEMORIES>
"""

Supprimer des souvenirs

Vous pouvez supprimer des souvenirs de votre instance Memory Bank de plusieurs manières, selon la façon dont vous souhaitez sélectionner les souvenirs à supprimer.

Supprimer par nom de ressource

Si vous savez exactement quelle ressource de souvenir vous souhaitez supprimer, vous pouvez supprimer un souvenir spécifique à l'aide de son nom de ressource :

client.agent_engines.memories.delete(
    name=MEMORY_NAME,
    config={
        # Set to false (default) if you want to delete the memory asynchronously.
        "wait_for_completion": True
    }
)

Remplacez les éléments suivants :

  • MEMORY_NAME : nom du souvenir à supprimer. Le nom doit être au format suivant : projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Vous pouvez trouver le nom du souvenir en récupérant des souvenirs.

Supprimer par critères

Vous pouvez utiliser la suppression basée sur des critères pour supprimer un ou plusieurs souvenirs. Seuls les souvenirs correspondant aux filtres fournis seront supprimés. Vous devez spécifier au moins l'un des éléments suivants : filter (appliqué aux champs système) ou filter_groups (appliqué aux champs de métadonnées).

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    # Specify at least one of `filter` or `filter_groups`.
    filter="FILTER_STRING",
    filter_groups=FILTER_GROUPS,
    # Set to false (default) if you want to stage but not execute the purge operation.
    force=True,
    config={
        # Set to false (default) if you want to purge memories asynchronously.
        "wait_for_completion": True
    }
)

Remplacez les éléments suivants :

L'opération renvoie le nombre de souvenirs qui ont été supprimés (si force=True) ou qui seraient supprimés si l'opération était exécutée (si force=False).

print(operation.response.purge_count)

Par exemple, vous pouvez supprimer tous les souvenirs appartenant à un champ d'application pour user_id "123" :

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    filter="scope.user_id=\"123\""
    force=True
)

Supprimer par signification sémantique

Lors de la génération de souvenirs, Memory Bank décide s'il doit créer, mettre à jour ou supprimer des souvenirs en fonction du contenu des nouvelles informations extraites et des souvenirs existants. Un souvenir peut être supprimé si les nouvelles informations le contredisent ou si le contenu extrait demande à Memory Bank d'oublier un sujet (dans le cas du EXPLICIT_INSTRUCTIONS sujet de mémoire).

Par exemple, la requête suivante supprime les souvenirs existants contenant des informations sur les préférences alimentaires, s'ils existent pour le scope donné :

from google import genai

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_contents_source={
      "events": [{
        "content": genai.types.Content(
          role="user",
          parts=[
            genai.types.Part.from_text(text="Forget my dietary preferences.")
          ]
        )
      }]
    },
    scope={...}
)

Libérer de l'espace

Pour nettoyer toutes les ressources utilisées dans ce projet, vous pouvez supprimer le Google Cloud projet que vous avez utilisé pour ce guide de démarrage rapide.

Vous pouvez également supprimer les ressources individuelles que vous avez créées, comme suit :

  1. Utilisez l'exemple de code suivant pour supprimer l'instance Agent Platform, ce qui supprime également toutes les sessions ou tous les souvenirs associés à l'instance Agent Platform.

    agent_engine.delete(force=True)

  2. Supprimez tous les fichiers créés localement.

Étape suivante

Guide de démarrage rapide

Premiers pas avec Agent Development Kit (ADK).