Buscar recordações

O Memory Bank da Plataforma de Agentes permite recuperar memórias armazenadas usando diferentes operações, dependendo das suas necessidades. É possível buscar uma única memória, listar e filtrar memórias ou realizar uma recuperação com base em escopo usando a pesquisa de similaridade.

Neste documento, explicamos como buscar e inspecionar memórias no console do Google Cloud ou com o SDK da Plataforma de Agentes.

Se você usar o Kit de Desenvolvimento de Agente (ADK), seu agente poderá organizar essas chamadas automaticamente. Consulte o Guia de início rápido com o ADK.

Antes de começar

Para concluir as etapas desta página, primeiro conclua as etapas em Configurar o banco de memória.

Operações de busca

Você tem as seguintes opções para buscar recordações geradas:

• Acessar memória: acesse o conteúdo completo de uma única memória usando o SDK da Agent Platform.

• Recuperar memórias: use o SDK da Agent Platform para recuperar memórias com base em escopo. Recupere memórias usando a pesquisa por similaridade ou todas as memórias no escopo.

• Listar memórias: liste e filtre memórias no console doGoogle Cloud ou com o SDK da Agent Platform.

Acessar memória

Use GetMemories para acessar o conteúdo completo de uma única memória:

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

Substitua:

• MEMORY_NAME: um nome de memória totalmente qualificado no formato "projects/.../locations/.../reasoningEngines/.../memories...".

Buscar recordações usando a recuperação baseada em escopo

Use RetrieveMemories para recuperar memórias de um escopo específico. Somente as memórias que têm exatamente o mesmo escopo (independentemente da ordem) que a solicitação de recuperação são retornadas. Por exemplo, é possível recuperar todas as memórias que estão no escopo de um usuário específico usando {"user_id": "123"}. Se nenhuma memória for retornada, o Memory Bank não tem memórias para o escopo fornecido.

O escopo de uma memória é definido quando ela é gerada ou criada e é imutável.

É possível usar RetrieveMemories para realizar as seguintes operações em um determinado escopo:

• Recuperar memórias usando a pesquisa de similaridade
• Recuperar todas as recordações

Recuperar memórias usando a pesquisa de similaridade

Nos casos em que você tem muitas memórias para um escopo específico, é possível usar a pesquisa de similaridade para recuperar apenas as memórias mais semelhantes, fornecendo parâmetros de pesquisa de similaridade. O banco de memória só considera memórias que têm exatamente o mesmo escopo da solicitação ao realizar a pesquisa de similaridade. A pesquisa de similaridade compara os vetores de embedding entre os fatos das memórias e a consulta de pesquisa da solicitação.

As memórias retornadas são classificadas da mais semelhante (menor distância euclidiana) para a menos semelhante (maior distância euclidiana):

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
    ),
]
"""

Substitua:

• QUERY: a consulta para realizar a pesquisa de similaridade. Por exemplo, é possível usar a última fala do usuário na conversa como a consulta.

• SCOPE: um dicionário que representa o escopo da pesquisa por similaridade. Por exemplo, {"user_id": "123"}. Somente as memórias com o mesmo escopo da solicitação são consideradas.

Recuperar todas as memórias

Se nenhum parâmetro de pesquisa de similaridade for fornecido, RetrieveMemories vai retornar todas as memórias que têm o escopo fornecido, independentemente da similaridade com a conversa atual.

Aviso: recuperar todas as memórias sem pesquisa de similaridade pode retornar várias páginas. Chamar list() em uma resposta RetrieveMemories aciona a paginação automática em todas as páginas. Para coleções grandes, use response.page diretamente para buscar itens uma página por vez e evitar chamadas inesperadas.

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."
      }
    ),
]
"""

Substitua:

• SCOPE: um dicionário que representa o escopo da recuperação. Por exemplo, {"user_id": "123"}. Somente as memórias com o mesmo escopo da solicitação são retornadas.

Listar dados de memória

É possível listar e inspecionar memórias no console do Google Cloud ou com o SDK da Agent Platform.

Console

Para conferir e filtrar memórias no console do Google Cloud (requer aiplatform.memories.list, incluído em roles/aiplatform.memoryViewer e roles/aiplatform.memoryUser):

1. Abra a instância no console do Google Cloud :

   • Instância independente do Memory Bank: acesse a página Memory Bank da Plataforma de Agentes e clique na sua instância.

     Acessar o Memory Bank

   • Agente implantado no Agent Runtime: acesse a página Implantações da plataforma de agentes e clique no seu agente.

     Acessar "Implantações"

2. Abra a guia Recordações. Por padrão, a visualização Não estruturada mostra uma tabela de memórias (Escopo, Nome do recurso, Fato, Criado e Atualizado).

3. Opcional: filtre ou gerencie as recordações:

   • Filtrar por escopo: digite um par key:value (como user_id:123) na barra de filtros ou clique em um ícone de escopo em qualquer linha.
   • Ver perfis estruturados: mude para Estruturado e selecione um escopo completo ou aplique um filtro de escopo em Não estruturado e clique em Pesquisar memórias estruturadas. Para mais detalhes, consulte Perfis de memória.
   • Editar, inspecionar revisões ou excluir: clique no menu mais ações () em uma linha de memória e selecione Editar, Ver revisões ou Excluir.

SDK da plataforma de agentes

Aviso: chamar list() em uma resposta ListMemories aciona a paginação automática em todas as páginas. Para coleções grandes, use response.page diretamente para buscar itens uma página por vez e evitar chamadas inesperadas.

Use ListMemories para listar as memórias do seu banco de memórias sem filtragem baseada em escopo. Para recuperação com base em escopo, use RetrieveMemories. ListMemories não é recomendado para recuperação de baixa latência.

pager = client.memory_banks.memories.list(name=memory_bank.name)
for page in pager:
  print(page)

Filtrar memórias de tradução

Nesta seção, descrevemos como usar filtros para restringir quais recordações são buscadas. É possível filtrar por:

• Metadados que usam o atributo filter_groups para recuperação com base em escopo.

• Campos do sistema que usam filter. Os campos do sistema incluem topics, create_time, update_time e fact das recordações.

A filtragem de metadados e de campos do sistema pode ser usada na mesma solicitação.

Filtrar por metadados

Observação: a filtragem por metadados só é compatível com a recuperação baseada em escopo e a limpeza de memórias.

Ao criar, atualizar ou gerar memórias, é possível aplicar metadados estruturados às memórias armazenadas:

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}
)

É possível filtrar esses metadados ao recuperar memórias usando o atributo filter_groups. Os filtros de metadados são definidos na forma normal disjuntiva (DNF, na sigla em inglês), que é uma expressão lógica de ORs de ANDs.

Por exemplo, a solicitação a seguir vai recuperar recordações que incluem os metadados ({"my_string_key": {"string_value": "my_value"}} E {"my_double_key": {"double": 1.23}}) OU {"my_string_key": {"string_value": "other"}}.

Dicionário

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"}
          }
        ]
      }
    ]
  }
)

Com base em 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")
          )
        ]
      )
    ]
  )
)

Filtrar por campos do sistema

É possível filtrar campos do sistema usando o atributo filter, que espera um valor de string usando a sintaxe EBNF. Os campos do sistema incluem create_time, update_time, fact e topics.

A sintaxe EBNF tem os seguintes requisitos ao criar uma string de filtro:

• Para combinar filtros, use AND e OR.
• A string precisa usar aspas duplas ".
• Os campos de data e hora (como create_time) usam uma string entre aspas duplas que representa a data e hora ISO 8601 ou um campo numérico que representa microssegundos da época Unix.

Por exemplo, o filtro a seguir pode ser usado para buscar recordações em que o fact inclui a substring "alergias" e o update_time foi depois de 1º de janeiro de 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}
)

Filtrar por temas

As recordações geradas são rotuladas automaticamente com o tema de recordação relevante.

Para filtrar por tópicos gerenciados, use topics.managed_memory_topic como o nome do campo e o ManagedTopicEnum esperado como o valor, como topics.managed_memory_topic: USER_PREFERENCES.

Para filtrar por temas personalizados, use topics.custom_memory_topic_label como o nome do campo e o rótulo do tema esperado como o valor, como 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}
)