Ce document explique comment récupérer et inspecter des souvenirs dans la console Google Cloud ou avec le SDK Agent Platform.
Si vous utilisez l'Agent Development Kit (ADK), votre agent peut orchestrer automatiquement ces appels pour vous. Consultez Guide de démarrage rapide avec ADK.
Avant de commencer
Pour effectuer les étapes décrites sur cette page, vous devez d'abord suivre les étapes de la section Configurer Memory Bank.
Opérations de récupération
Vous disposez des options suivantes pour récupérer les souvenirs générés :
Obtenir une mémoire : obtenez l'intégralité du contenu d'une seule mémoire à l'aide du SDK Agent Platform.
Récupérez des souvenirs à l'aide de la recherche par similarité ou tous les souvenirs du champ d'application.
Lister les souvenirs : listez et filtrez les souvenirs dans la consoleGoogle Cloud ou avec le SDK Agent Platform.
Obtenir la mémoire
Utilisez GetMemories pour obtenir le contenu complet d'un seul souvenir :
memory = client.memory_banks.memories.get(
name="MEMORY_NAME")
Remplacez les éléments suivants :
MEMORY_NAME: nom de mémoire complet au format "projects/.../locations/.../reasoningEngines/.../memories...".
Récupérer des souvenirs à l'aide de la récupération basée sur le champ d'application
Vous pouvez utiliser RetrieveMemories pour récupérer les souvenirs d'un champ d'application particulier. Seuls les souvenirs ayant exactement le même champ d'application (quel que soit l'ordre) que la requête de récupération sont renvoyés. Par exemple, vous pouvez récupérer toutes les informations mémorisées qui sont limitées à un utilisateur particulier à l'aide de {"user_id": "123"}. Si aucune information mémorisée n'est renvoyée, cela signifie que la banque de mémoire n'en contient aucune pour le champ d'application fourni.
Le champ d'application d'une information mémorisée est défini lors de sa génération ou de sa création, et il est immuable.
Vous pouvez utiliser RetrieveMemories pour effectuer les opérations suivantes pour un champ d'application particulier :
- Récupérer des informations mémorisées à l'aide de la recherche de similarités
- Récupérer tous les souvenirs
Récupérer des informations mémorisées à l'aide de la recherche de similarités
Si vous avez de nombreuses infos mémorisées pour un champ d'application particulier, vous pouvez utiliser la recherche de similarité pour ne récupérer que les infos mémorisées les plus similaires en fournissant des paramètres de recherche de similarité. Memory Bank ne prend en compte que les souvenirs ayant exactement le même champ d'application que la requête lors de la recherche de similarité. La recherche de similarité compare les vecteurs d'embedding entre les faits des mémoires et la requête de recherche.
Les souvenirs renvoyés sont triés du plus similaire (distance euclidienne la plus courte) au moins similaire (distance euclidienne la plus grande) :
results = client.memory_banks.memories.retrieve(
name=memory_bank.name,
scope=SCOPE,
similarity_search_params={
"search_query": "QUERY",
# Optional. Defaults to 3.
"top_k": 3
}
)
# RetrieveMemories returns a pager. You can use `page` to retrieve memories.
results.page
"""
Returns:
[
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is a fact."
},
distance=0.5
),
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is another fact."
},
distance=0.7
),
]
"""
Remplacez les éléments suivants :
QUERY: requête pour laquelle effectuer une recherche de similarité. Par exemple, vous pouvez utiliser le dernier tour de parole de l'utilisateur dans la conversation comme requête.SCOPE: dictionnaire représentant le champ d'application de la recherche de similarité. Exemple :{"user_id": "123"}. Seules les informations mémorisées ayant le même champ d'application que la requête sont prises en compte.
Récupérer tous les souvenirs
Si aucun paramètre de recherche de similarité n'est fourni, RetrieveMemories renvoie toutes les mémoires ayant le champ d'application fourni, quelle que soit leur similarité avec la conversation actuelle.
results = client.memory_banks.memories.retrieve(
name=memory_bank.name,
scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `page` to retrieve up to 100 memories per page.
results.page
"""
Returns:
[
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is a fact."
}
),
RetrieveMemoriesResponseRetrievedMemory(
memory=Memory(
name="projects/.../locations/.../reasoningEngines/.../memories/...",
...
fact="This is another fact."
}
),
]
"""
Remplacez les éléments suivants :
SCOPE: dictionnaire représentant le champ d'application de la récupération. Exemple :{"user_id": "123"}. Seules les informations mémorisées ayant le même champ d'application que la requête sont renvoyées.
Lister les informations mémorisées
Vous pouvez lister et inspecter les souvenirs dans la console Google Cloud ou avec le SDK Agent Platform.
Console
Pour afficher et filtrer les souvenirs dans la console Google Cloud (nécessite aiplatform.memories.list, inclus dans roles/aiplatform.memoryViewer et roles/aiplatform.memoryUser) :
Ouvrez votre instance dans la console Google Cloud :
Instance Memory Bank autonome : accédez à la page Memory Bank d'Agent Platform, puis cliquez sur votre instance.
Agent déployé sur Agent Runtime : accédez à la page Déploiements d'Agent Platform, puis cliquez sur votre agent.
Ouvrez l'onglet Souvenirs. Par défaut, la vue Non structuré affiche un tableau de souvenirs (Champ d'application, Nom de la ressource, Fait, Créé et Mis à jour).
Facultatif : Filtrez ou gérez les souvenirs :
- Filtrer par champ d'application : saisissez une paire
key:value(par exemple,user_id:123) dans la barre de filtre ou cliquez sur un chip de champ d'application sur n'importe quelle ligne. - Afficher les profils structurés : passez à Structuré et sélectionnez un champ d'application complet, ou appliquez un filtre de champ d'application dans Non structuré, puis cliquez sur Rechercher dans les mémoires structurées. Pour en savoir plus, consultez Profils de mémoire.
- Modifier, inspecter les révisions ou supprimer : cliquez sur le menu Autres actions () sur une ligne de mémoire, puis sélectionnez Modifier, Afficher les révisions ou Supprimer.
- Filtrer par champ d'application : saisissez une paire
SDK Agent Platform
Utilisez ListMemories pour lister les informations mémorisées de votre banque de mémoire sans filtrage basé sur le champ d'application. Pour la récupération basée sur le champ d'application, utilisez plutôt RetrieveMemories. ListMemories n'est pas recommandé pour la récupération à faible latence.
pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
print(page)
Filtrer les souvenirs
Cette section explique comment utiliser des filtres pour limiter les souvenirs récupérés. Vous pouvez appliquer les filtres suivants :
Métadonnées utilisant l'attribut
filter_groupspour la récupération basée sur le champ d'application.Champs système utilisant
filter. Les champs système incluent les champstopics,create_time,update_timeetfactdes souvenirs.
Vous pouvez utiliser à la fois le filtrage des métadonnées et celui des champs système dans la même requête.
Filtrer par métadonnées
Lorsque vous créez, mettez à jour ou générez des souvenirs, vous pouvez leur appliquer des métadonnées structurées :
import datetime
from agentplatform import types
metadata = {
"my_string_key": types.MemoryMetadataValue(string_value="my_string_value"),
"my_double_key": types.MemoryMetadataValue(double_value=123.456),
"my_boolean_key": types.MemoryMetadataValue(bool_value=True),
"my_timestamp_key": types.MemoryMetadataValue(
timestamp_value=datetime.datetime(
2027, 1, 1, 12, 30, 00, tzinfo=datetime.timezone.utc
)
),
}
client.memory_banks.memories.create(
...,
config={"metadata": metadata}
)
client.memory_banks.memories.update(
...,
config={"metadata": metadata}
)
client.memory_banks.memories.generate(
...,
config={"metadata": metadata}
)
Vous pouvez filtrer ces métadonnées lors de la récupération des souvenirs à l'aide de l'attribut filter_groups. Les filtres de métadonnées sont définis sous forme normale disjonctive (DNF), qui est une expression logique de OU de ET.
Par exemple, la requête suivante récupère les souvenirs qui incluent les métadonnées ({"my_string_key": {"string_value": "my_value"}} ET {"my_double_key": {"double": 1.23}}) OU {"my_string_key": {"string_value":
"other"}}.
Dictionnaire
results = client.memory_banks.memories.retrieve(
...,
config={
# Each element of `filter_groups` is combined using OR logic.
"filter_groups": [
{
# Each element of `filters` is combined using AND logic.
"filters": [
{
"key": "my_string_key",
"value": {"string_value": "my_value"}
},
{
"key": "my_double_key",
"value": {"double_value": 1.23}
}
]
},
{
"filters": [
{
"key": "my_string_key",
"value": {"string_value": "other"}
}
]
}
]
}
)
Basée sur les classes
from agentplatform import types
results = client.memory_banks.memories.retrieve(
...,
config=types.RetrieveMemoriesConfig(
# Each element of `filter_groups` is combined using OR logic.
filter_groups=[
types.MemoryConjunctionFilter(
# Each element of `filters` is combined using AND logic.
filters=[
types.MemoryFilter(
key="my_string_key",
value=types.MemoryMetadataValue(string_value="my_value")
),
types.MemoryFilter(
key="my_double_key",
value=types.MemoryMetadataValue(double_value=1.23)
)
]
),
types.MemoryConjunctionFilter(
filters=[
types.MemoryFilter(
key="my_string_key",
value=types.MemoryMetadataValue(string_value="other")
)
]
)
]
)
)
Filtrer par champs système
Vous pouvez filtrer les champs système à l'aide de l'attribut filter, qui attend une valeur de chaîne utilisant la syntaxe EBNF. Les champs système incluent create_time, update_time, fact et topics.
La syntaxe EBNF doit respecter les exigences suivantes lors de la construction d'une chaîne de filtre :
- Pour combiner des filtres, utilisez
ANDetOR. - La chaîne doit utiliser des guillemets doubles
". - Les champs de date et d'heure (comme
create_time) utilisent une chaîne entre guillemets doubles représentant la date et l'heure ISO 8601 ou un champ numérique représentant les microsecondes depuis l'epoch Unix.
Par exemple, le filtre suivant peut être utilisé pour récupérer les souvenirs dont le fact inclut la sous-chaîne "allergies" et dont le update_time est postérieur au 1er janvier 2026.
filter_string = 'fact=~".*allergies.*" AND update_time>="2026-01-01T00:00:00Z"'
client.memory_banks.memories.retrieve(
...,
config={"filter": filter_string}
)
client.memory_banks.memories.list(
...,
config={"filter": filter_string}
)
Filtrer par thème
Les souvenirs générés sont automatiquement étiquetés avec le thème de souvenir approprié.
Pour filtrer les thèmes gérés, utilisez topics.managed_memory_topic comme nom de champ et le ManagedTopicEnum attendu comme valeur, par exemple topics.managed_memory_topic: USER_PREFERENCES.
Pour filtrer sur des thèmes personnalisés, utilisez topics.custom_memory_topic_label comme nom de champ et le libellé du thème attendu comme valeur, par exemple topics.custom_memory_topic_label: custom-label.
filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"
client.memory_banks.memories.retrieve(
...,
config={"filter": filter_string}
)
client.memory_banks.memories.list(
...,
config={"filter": filter_string}
)