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 avec 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 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 celles de la section Configurer Memory Bank.
Générer des souvenirs avec les sessions Agent Platform
Après avoir configuré les sessions Agent Platform 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. Ils sont ainsi disponibles pour les futures interactions de l'utilisateur. Pour en savoir plus, consultez Générer des souvenirs et Récupérer des souvenirs.
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 portée
{"user_id": "USER_ID"}, sauf si vous fournissez explicitement une portée 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 compatibles pour Memory Bank.
AGENT_ENGINE_NAME : nom de l'instance Agent Platform que vous avez créée ou d'une instance Agent Platform existante. Le nom doit respecter le 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 portée
{"user_id": "USER_ID"}, sauf si vous fournissez explicitement une portée lors de la génération des souvenirs.
Importez des événements de manière itérative dans votre session. Les événements peuvent inclure toutes les interactions entre votre utilisateur, l'agent et les outils. La liste ordonnée des événements représente l'historique des conversations de votre session. Cet historique des conversations sert de 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"}] } } )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 la même portée 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 à partir de dialogues bruts, vous pouvez les importer ou demander à vos agents de les ajouter directement à l'aide de GenerateMemories avec des faits pré-extraits.
Au lieu d'extraire des informations de votre contenu, la Banque de mémoire vous permet de fournir directement les faits à stocker sur votre utilisateur.
Pour assurer la cohérence avec les souvenirs générés, essayez d'écrire les faits pré-extraits dans la même perspective que celle que vous avez configurée pour la portée donnée. 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 à consolider 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. Exemple :
{"session_id": "MY_SESSION"}Seuls les souvenirs ayant la même portée 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 les souvenirs de votre utilisateur et les inclure dans vos instructions système pour 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 requête :
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
Il existe plusieurs façons de supprimer des souvenirs de votre instance Memory Bank, selon la façon dont vous souhaitez sélectionner les souvenirs à supprimer.
Supprimer par nom de ressource
Si vous savez exactement quelle ressource de mémoire vous souhaitez supprimer, vous pouvez supprimer une mémoire 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 respecter le 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 les souvenirs.
Supprimer par critère
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 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 :
- FILTER_STRING : chaîne utilisant la syntaxe EBNF pour filtrer les champs système. Les champs système incluent
create_time,update_time,factettopics. Pour en savoir plus sur le filtrage par rapport aux champs système, consultez la section Filtrer par champs de métadonnées sur la page "Récupérer des souvenirs". - FILTER_GROUPS : liste de dictionnaires ou d'objets pour filtrer les métadonnées de la mémoire. Pour en savoir plus sur le filtrage par rapport aux champs de métadonnées, consultez la section Filtrer par champs système de la page "Récupérer des souvenirs".
L'opération renvoie le nombre de souvenirs 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 toutes les mémoires 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, la banque de souvenirs décide de créer, de modifier ou de 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 de supprimer un sujet (dans le cas du thème de mémoire EXPLICIT_INSTRUCTIONS).
Par exemple, la requête suivante supprimerait 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={...}
)
Effectuer un nettoyage
Pour nettoyer toutes les ressources utilisées dans ce projet, vous pouvez supprimer le projet Google Cloud 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 :
Utilisez l'exemple de code suivant pour supprimer l'instance Agent Platform, ce qui supprime également toutes les sessions ou mémoires associées à l'instance Agent Platform.
agent_engine.delete(force=True)Supprimez tous les fichiers créés localement.
Étapes suivantes
Démarrage rapide avec Agent Development Kit
Faites vos premiers pas avec Agent Development Kit (ADK).