Vous pouvez utiliser le SDK Agent Platform pour effectuer des appels d'API directement vers Memory Bank. 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 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 infos mémorisées à l'aide d'appels d'API.
Pour le guide de démarrage rapide avec ADK, consultez Guide de démarrage rapide 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. Avant de commencer ce guide de démarrage rapide, assurez-vous d'avoir créé une instance Memory Bank et une instance Sessions, comme illustré dans l'exemple suivant :
import vertexai
client = vertexai.Client(
project="PROJECT_ID",
location="LOCATION"
)
memory_bank = client.agent_engines.create()
sessions = client.agent_engines.create()
Générer des infos mémorisées avec Agent Platform Sessions
Après avoir configuré Agent Platform Sessions, vous pouvez créer des sessions et y ajouter des événements. Vous pouvez ensuite utiliser Memory Bank pour générer des infos mémorisées à partir de la conversation de l'utilisateur avec l'agent afin qu'elles soient disponibles pour les futures interactions de l'utilisateur. Pour en savoir plus, consultez Générer des infos mémorisées et Récupérer des infos mémorisées.
Créez une session avec un ID utilisateur opaque. Toutes les infos mémorisées générées à partir de cette session sont automatiquement associées à 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 infos mémorisées.import vertexai client = vertexai.Client( project="PROJECT_ID", location="LOCATION" ) session = client.agent_engines.sessions.create( # The name can be fetched using `sessions.api_resource.name`. name="SESSIONS_NAME", user_id="USER_ID" )Remplacez les éléments suivants :
PROJECT_ID : ID de votre projet
LOCATION : votre région Consultez les régions disponibles pour Memory Bank.
SESSIONS_NAME : nom de l' instance Sessions que vous avez créée ou d'une instance Sessions existante. Le nom doit être au format suivant :
projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.USER_ID : identifiant de votre utilisateur. Toutes les infos mémorisées générées à partir de cette session sont automatiquement associées à 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 infos mémorisées.
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 infos mémorisées 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 infos mémorisées à partir de votre historique des conversations, déclenchez une demande de génération d'infos mémorisées pour la session :
client.agent_engines.memories.generate( name=memory_bank.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
infos mémorisées générées, avec un maximum de cinq paires clé/valeur et aucun
*caractère. Par exemple,{"session_id": "MY_SESSION"}. Seules les infos mémorisées ayant le même champ d'application sont prises en compte pour la consolidation. Si aucune valeur n'est fournie,{"user_id": session.user_id}est utilisé.
Importer des infos mémorisées
Au lieu de générer des infos mémorisées à l'aide d'un dialogue brut, vous pouvez importer des infos mémorisées 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 infos mémorisées générées, 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 infos mémorisées sont générées à la première personne (par exemple, I
am a software engineer).
client.agent_engines.memories.generate(
name=memory_bank.api_resource.name,
direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
scope=SCOPE
)
Remplacez les éléments suivants :
FACT : fait pré-extrait à consolider avec les infos mémorisées existantes. 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 infos mémorisées générées. Par exemple,
{"session_id": "MY_SESSION"}. Seules les infos mémorisées ayant le même champ d'application sont prises en compte pour la consolidation.
Vous pouvez également utiliser CreateMemory pour importer des infos mémorisées sans utiliser Memory Bank pour l'extraction ou la consolidation des infos mémorisées.
memory = client.agent_engines.memories.create(
name=memory_bank.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 infos mémorisées
Vous pouvez récupérer des infos mémorisées 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 d'infos mémorisées à l'aide d'une méthode basée sur le champ d'application, consultez Récupérer des infos mémorisées.
# Retrieve all memories for User ID 123.
retrieved_memories = list(
client.agent_engines.memories.retrieve(
name=memory_bank.api_resource.name,
scope={"user_id": "123"}
)
)
Vous pouvez utiliser jinja pour convertir vos infos mémorisées structurées en prompt :
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 infos mémorisées
Vous pouvez supprimer des infos mémorisées de votre instance Memory Bank de plusieurs manières, selon la façon dont vous souhaitez sélectionner les infos mémorisées à supprimer.
Supprimer par nom de ressource
Si vous savez exactement quelle ressource d'info mémorisée vous souhaitez supprimer, vous pouvez supprimer une info mémorisée 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 de l'info mémorisée à 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 de l'info mémorisée en récupérant des infos mémorisées.
Supprimer par critères
Vous pouvez utiliser la suppression basée sur des critères pour supprimer une ou plusieurs infos mémorisées. Seules les infos mémorisées correspondant aux filtres fournis seront supprimées. 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=memory_bank.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,fact, ettopics. Pour en savoir plus sur le filtrage des champs système, consultez la section Filtrer par champs de métadonnées de la page Récupérer des infos mémorisées. - FILTER_GROUPS : liste de dictionnaires ou d'objets pour filtrer les métadonnées des infos mémorisées. Pour en savoir plus sur le filtrage des champs de métadonnées, consultez la section Filtrer par champs système de la page Récupérer des infos mémorisées.
L'opération renvoie le nombre d'infos mémorisées qui ont été supprimées (si force=True) ou qui seraient supprimées si l'opération était exécutée (si force=False).
print(operation.response.purge_count)
Par exemple, vous pouvez supprimer toutes les infos mémorisées appartenant à un champ d'application pour user_id "123" :
operation = client.agent_engines.memories.purge(
name=memory_bank.api_resource.name,
filter="scope.user_id=\"123\""
force=True
)
Supprimer par signification sémantique
Lors de la génération d'infos mémorisées,
Memory Bank décide s'il doit créer, mettre à jour ou supprimer des
infos mémorisées en fonction du contenu des informations nouvellement extraites et des
infos mémorisées existantes. Une info mémorisée peut être supprimée si les nouvelles informations la contredisent
ou si le contenu extrait demande à Memory Bank d'oublier un
sujet (dans le cas du EXPLICIT_INSTRUCTIONS sujet d'info mémorisée
topic).
Par exemple, la requête suivante supprime les infos mémorisées existantes contenant des informations sur les préférences alimentaires, si elles existent pour le scope donné :
from google import genai
client.agent_engines.memories.generate(
name=memory_bank.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 Google Cloud projet que vous avez utilisé pour ce tutoriel.
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 infos mémorisées associées à l'instance Agent Platform.
agent_engine.delete(force=True)Supprimez tous les fichiers créés localement.
Étape suivante
Guide de démarrage rapide avec Agent Development Kit
Premiers pas avec Agent Development Kit (ADK).