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 à votre place, 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 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. 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 agentplatform
client = agentplatform.Client(
project="PROJECT_ID",
location="LOCATION"
)
memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()
Générer des souvenirs avec les sessions Agent Platform
Après avoir configuré les sessions Agent Platform, vous pouvez créer des sessions et y ajouter des événements. Vous pouvez ensuite utiliser Memory Bank pour générer des informations 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 souvenirs et Récupérer des souvenirs.
Créez une session avec un ID utilisateur opaque. Toutes les informations mémorisées générées à partir de cette session sont automatiquement associées au champ d'application
{"user_id": "USER_ID"}, sauf si vous fournissez explicitement un champ d'application lors de la génération des informations mémorisées.import agentplatform client = agentplatform.Client( project="PROJECT_ID", location="LOCATION" ) session = client.sessions.create( # The name can be fetched using `sessions.name`. name="SESSIONS_NAME", user_id="USER_ID" )Remplacez les éléments suivants :
PROJECT_ID : ID du 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 mémoires générées à partir de cette session sont automatiquement associées au champ d'application
{"user_id": "USER_ID"}, sauf si vous fournissez explicitement un champ d'application lors de la génération des mémoires.
Importez des événements de manière itérative dans votre session. Les événements peuvent inclure toutes les interactions entre l'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 est utilisé comme source pour générer des souvenirs pour cet utilisateur spécifique.
import datetime client.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 informations mémorisées à partir de l'historique de vos conversations, déclenchez une requête de génération d'informations mémorisées pour la session :
client.memory_banks.memories.generate( name=memory_bank.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"}. Seules les informations mémorisées ayant le même champ d'application sont prises en compte pour la consolidation. Si cette valeur n'est pas spécifiée,{"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.
Plutôt que de laisser Memory Bank extraire des informations de votre contenu, vous fournissez 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 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.memory_banks.memories.generate(
name=memory_bank.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. Exemple :
{"session_id": "MY_SESSION"}Seules les informations 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 souvenirs sans utiliser Memory Bank pour l'extraction ou la consolidation des souvenirs.
memory = client.memory_banks.memories.create(
name=memory_bank.name,
fact="This is a fact.",
scope={"user_id": "123"}
)
"""
Returns a MemoryOperation containing the created Memory like:
MemoryOperation(
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 l'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 memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
name=memory_bank.name,
scope={"user_id": "123"}
).page
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 les informations mémorisées
Il existe plusieurs façons de supprimer des souvenirs de votre instance Memory Bank, selon la manière 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.memory_banks.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 la mémoire à 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 la mémoire en récupérant les mémoires.
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.memory_banks.memories.purge(
name=memory_bank.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 champs système, consultez la section Filtrer par champs de métadonnées de la page "Récupérer des souvenirs". - FILTER_GROUPS : liste de dictionnaires ou d'objets permettant de filtrer les métadonnées de mémoire. 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 souvenirs".
L'opération renvoie le nombre de souvenirs qui ont été purgés (si force=True) ou qui seraient purgé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 l'ID de conversation user_id "123" :
operation = client.memory_banks.memories.purge(
name=memory_bank.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 de créer, de mettre à jour ou de supprimer des souvenirs en fonction du contenu des informations nouvellement extraites et des souvenirs existants. Une information mémorisée peut être supprimée si les nouvelles informations la contredisent ou si le contenu extrait indique à la banque de mémoire d'oublier un sujet (dans le cas du sujet 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.memory_banks.memories.generate(
name=memory_bank.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 tutoriel.
Vous pouvez également supprimer les ressources individuelles que vous avez créées, comme suit :
Utilisez l'exemple de code suivant pour supprimer les instances Agent Platform Memory Bank et Agent Runtime sur Gemini Enterprise Agent Platform :
client.memory_banks.delete(name=memory_bank.name, force=True) client.runtimes.delete(name=sessions.name, force=True)Supprimez tous les fichiers créés localement.
Étapes suivantes
Guide de démarrage rapide d'Agent Development Kit
Créer un agent ADK qui mémorise les préférences de l'utilisateur