Récupérer des souvenirs

Ce document explique comment utiliser ces opérations de récupération à l'aide du SDK Agent Platform.

Si vous utilisez l'Agent Development Kit (ADK), votre agent peut orchestrer automatiquement ces appels pour vous. Consultez le guide de démarrage rapide avec ADK.

Avant de commencer

Pour réaliser les étapes décrites sur cette page, vous devez d'abord suivre celles 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 le contenu complet d'une mémoire à l'aide du SDK Agent Platform.

• Lister les souvenirs : listez les souvenirs à l'aide du SDK Agent Platform ou de la console Google Cloud .

• Récupérer des souvenirs : à l'aide du SDK Agent Platform, récupérez des souvenirs à l'aide de la récupération de mémoire basée sur le champ d'application. Récupérez des souvenirs à l'aide d'une recherche par similarité ou tous les souvenirs inclus dans le champ d'application.

Obtenir un souvenir

Utilisez GetMemories pour obtenir l'intégralité du contenu d'une mémoire :

memory = client.agent_engines.memories.get(
    name="MEMORY_NAME")

Remplacez les éléments suivants :

• MEMORY_NAME : nom de mémoire complet au format "projects/.../locations/.../reasoningEngines/.../memories...".

Lister les souvenirs

pager = client.agent_engines.memories.list(name=agent_engine.api_resource.name)
for page in pager:
  print(page)

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 des souvenirs pour une portée spécifique. Seules les mémoires ayant exactement la même portée (indépendamment de l'ordre) que la demande de récupération sont renvoyées. Par exemple, vous pouvez récupérer tous les souvenirs associés à un utilisateur spécifique à l'aide de {"user_id": "123"}. Si aucun souvenir n'est renvoyé, cela signifie que la banque de souvenirs n'en contient aucun pour le champ d'application fourni.

Le champ d'application d'un souvenir 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 spécifique :

• Récupérer des souvenirs à l'aide de la recherche de similarité
• Récupérer tous les souvenirs

Récupérer des souvenirs à l'aide de la recherche de similarité

Si vous avez de nombreux souvenirs pour une portée spécifique, vous pouvez utiliser la recherche par similarité pour ne récupérer que les souvenirs les plus similaires en fournissant des paramètres de recherche par similarité. Memory Bank ne prend en compte que les souvenirs dont le champ d'application est exactement le même que celui de la requête lors de la recherche par similarité. La recherche de similarités compare les vecteurs d'embedding entre les faits des souvenirs 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 longue) :

results = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope=SCOPE,
    similarity_search_params={
        "search_query": "QUERY",
        # Optional. Defaults to 3.
        "top_k": 3
    }
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all memories.
list(results)

"""
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 par similarité. Par exemple, vous pouvez utiliser le dernier tour de parole de l'utilisateur comme requête.

• SCOPE : dictionnaire représentant le champ d'application de la recherche par similarité. Exemple : {"user_id": "123"}. Seuls les souvenirs ayant la même portée que la requête sont pris en compte.

Récupérer toutes les infos mémorisées

Si aucun paramètre de recherche de similarité n'est fourni, RetrieveMemories renvoie toutes les mémoires ayant la portée indiquée, quelle que soit leur similarité avec la conversation en cours.

results = client.agent_engines.memories.retrieve(
    name=agent_engine.api_resource.name,
    scope=SCOPE
)
# RetrieveMemories returns a pager. You can use `list` to retrieve all pages'
# memories.

list(results)

"""
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"}. Seuls les souvenirs ayant la même portée que la requête sont renvoyés.

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_groups pour la récupération basée sur le champ d'application.

• Champs système utilisant filter. Les champs système incluent topics, create_time, update_time et fact des souvenirs.

Vous pouvez utiliser le filtrage des champs de métadonnées et des champs système dans la même requête.

Filtrer par métadonnées

Lorsque vous créez, modifiez ou générez des souvenirs, vous pouvez appliquer des métadonnées structurées aux souvenirs stockés :

import datetime

from vertexai 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.agent_engines.memories.create(
  ...,
  config={"metadata": metadata}
)

client.agent_engines.memories.update(
  ...,
  config={"metadata": metadata}
)

client.agent_engines.memories.generate(
  ...,
  config={"metadata": metadata}
)

Vous pouvez filtrer ces métadonnées lorsque vous récupérez des souvenirs à l'aide de l'attribut filter_groups. Les filtres de métadonnées sont définis dans la forme normale disjonctive (DNF), qui est une expression logique de disjonctions de conjonctions.

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"}}.

results = client.agent_engines.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"}
          }
        ]
      }
    ]
  }
)

from vertexai import types

results = client.agent_engines.memories.retrieve(
  ...,
  config=types.RetrieveAgentEngineMemoriesConfig(
    # 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 présente les exigences suivantes lors de la création d'une chaîne de filtre :

• Pour combiner des filtres, utilisez AND et OR.
• La chaîne doit utiliser des guillemets doubles ".
• Les champs de date et heure (comme create_time) utilisent une chaîne entre guillemets doubles représentant la date et l'heure au format ISO 8601 ou un champ numérique représentant les microsecondes depuis l'époque 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.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.agent_engines.memories.list(
  ...,
  config={"filter": filter_string}
)

Filtrer par thème

Les souvenirs générés sont automatiquement associés à la thématique de souvenir correspondante.

Pour filtrer les thèmes gérés, utilisez topics.managed_memory_topic comme nom de champ et la valeur ManagedTopicEnum attendue, comme 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, comme topics.custom_memory_topic_label: custom-label.

filter_string = "topics.managed_memory_topic: USER_PREFERENCES " + \
"OR topics.custom_memory_topic_label: custom-label"

client.agent_engines.memories.retrieve(
  ...,
  config={"filter": filter_string}
)

client.agent_engines.memories.list(
  ...,
  config={"filter": filter_string}
)