Guia de início rápido da API Agent Platform Memory Bank

O Memory Bank do Agent Platform permite fazer chamadas de API diretamente para sessões e o Memory Bank usando o SDK do Agent Platform. Use o SDK do Agent Platform se você não quiser que uma estrutura de agentes orquestre chamadas ou se quiser integrar sessões e o Memory Bank com estruturas de agentes diferentes do Kit de Desenvolvimento de Agente (ADK).

Este documento mostra como criar, fazer upload, recuperar e remover recordações usando chamadas de API.

Para o guia de início rápido usando o ADK, consulte Guia de início rápido do Memory Bank com o ADK.

Antes de começar

Para concluir as etapas demonstradas neste tutorial, siga primeiro as etapas em Configurar o Memory Bank.

Gerar recordações com as sessões da Agent Platform

Depois de configurar as sessões do Agent Platform e o Memory Bank, você pode criar sessões e anexar eventos a elas. As recordações são geradas como fatos da conversa do usuário com o agente para que fiquem disponíveis para interações futuras do usuário. Para mais informações, consulte Gerar recordações e Buscar recordações.

  1. Crie uma sessão com um ID de usuário opaco. Todas as recordações geradas nessa sessão são automaticamente identificadas pelo escopo {"user_id": "USER_ID"} , a menos que você forneça um escopo ao gerar recordações.

    import vertexai

client = vertexai.Client(
project="PROJECT_ID",
location="LOCATION"
)

# This assumes that you already have an Agent Platform instance. If you don't,
# you can create one using `agent_engine = client.agent_engines.create()`.
session = client.agent_engines.sessions.create(
# The name can be fetched using `agent_engine.api_resource.name`.
name="AGENT_ENGINE_NAME",
user_id="USER_ID"
)

    Substitua:

    • PROJECT_ID: o ID do projeto.

    • LOCATION: sua região. Consulte as regiões com suporte do Memory Bank.

    • AGENT_ENGINE_NAME: o nome da instância do Agent Platform que você criou ou uma instância do Agent Platform. O nome precisa estar no seguinte formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

    • USER_ID: um identificador do usuário. Todas as recordações geradas nessa sessão são automaticamente identificadas pelo escopo {"user_id": "USER_ID"} , a menos que você forneça um escopo explicitamente ao gerar recordações.

  2. Faça upload de eventos de forma iterativa para sua sessão. Os eventos podem incluir interações entre o usuário, o agente e as ferramentas. A lista ordenada de eventos representa o histórico de conversas da sessão. Esse histórico de conversas é usado como material de origem para gerar recordações para esse usuário específico.

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

  3. Para gerar recordações do histórico de conversas, acione uma solicitação de geração de recordações para a sessão:

    client.agent_engines.memories.generate(
name=agent_engine.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
)

Substitua:

  • (Opcional) SCOPE: um dicionário que representa o escopo das recordações geradas, com um máximo de cinco pares de chave-valor e sem * caracteres. Por exemplo, {"session_id": "MY_SESSION"}. Somente as recordações com o mesmo escopo são consideradas para consolidação. Se não for fornecido, {"user_id": session.user_id} será usado.

Fazer upload de recordações

Como alternativa à geração de recordações usando diálogos brutos, você pode fazer upload de recordações ou fazer com que seus agentes as adicionem diretamente usando GenerateMemories com fatos pré-extraídos. Em vez de o Memory Bank extrair informações do seu conteúdo, você fornece os fatos que precisam ser armazenados sobre o usuário diretamente.

Para garantir a consistência com recordações geradas, tente escrever fatos pré-extraídos na mesma perspectiva que você configurou para o escopo especificado. Por padrão, as recordações são geradas na perspectiva da primeira pessoa (por exemplo, I am a software engineer).

client.agent_engines.memories.generate(
    name=agent_engine.api_resource.name,
    direct_memories_source={"direct_memories": [{"fact": "FACT"}]},
    scope=SCOPE
)

Substitua:

  • FACT: o fato pré-extraído que precisa ser consolidado com as recordações atuais. É possível fornecer até cinco fatos pré-extraídos em uma lista como esta:

    {"direct_memories": [{"fact": "fact 1"}, {"fact": "fact 2"}]}

  • SCOPE: um dicionário que representa o escopo das recordações geradas. Por exemplo, {"session_id": "MY_SESSION"}. Somente as recordações com o mesmo escopo são consideradas para consolidação.

Como alternativa, você pode usar CreateMemory para fazer upload de recordações sem usar o Memory Bank para extração ou consolidação de memória.

memory = client.agent_engines.memories.create(
    name=agent_engine.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))
  )
)
"""

Recuperar e usar recordações

É possível recuperar recordações do usuário e incluí-las nas instruções do sistema para dar ao LLM acesso ao contexto personalizado.

Para mais informações sobre como recuperar recordações usando um método baseado em escopo, consulte Buscar recordações.

# Retrieve all memories for User ID 123.
retrieved_memories = list(
    client.agent_engines.memories.retrieve(
        name=agent_engine.api_resource.name,
        scope={"user_id": "123"}
    )
)

Você pode usar jinja para converter suas recordações estruturadas em um comando:


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

Remover recordações

Há várias maneiras de excluir recordações da instância do Memory Bank, dependendo de como você quer selecionar quais recordações precisam ser removidas.

Remover pelo nome do recurso

Se você souber exatamente qual recurso de memória quer remover, poderá excluir uma memória específica usando o nome do recurso:

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

Substitua:

  • MEMORY_NAME: o nome da memória a ser excluída. O nome precisa estar no seguinte formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. É possível encontrar o nome da memória buscando recordações.

Remover por critérios

É possível usar a exclusão baseada em critérios para remover uma ou mais recordações. Somente as recordações que correspondem aos filtros fornecidos serão excluídas. É necessário especificar pelo menos um de filter (aplicado a campos do sistema) ou filter_groups (aplicado a campos de metadados).

operation = client.agent_engines.memories.purge(
    name=agent_engine.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
    }
)

Substitua:

  • FILTER_STRING: uma string que usa EBNF sintaxe para filtrar campos do sistema. Os campos do sistema incluem create_time, update_time, fact, e topics. Para mais informações sobre como filtrar campos do sistema, consulte a seção Filtrar por campos de metadados na página Buscar recordações.
  • FILTER_GROUPS: uma lista de dicionários ou objetos para filtrar metadados de memória. Para mais informações sobre como filtrar campos de metadados, consulte a seção Filtrar por campos do sistema na página Buscar recordações.

A operação vai retornar uma contagem de quantas recordações foram limpas (se force=True) ou seriam limpas se a operação fosse executada (se force=False).

print(operation.response.purge_count)

Por exemplo, é possível limpar todas as recordações que pertencem a um escopo para user_id "123":

operation = client.agent_engines.memories.purge(
    name=agent_engine.api_resource.name,
    filter="scope.user_id=\"123\""
    force=True
)

Remover por significado semântico

Durante a geração de dados de memória, o Memory Bank vai decidir se cria, atualiza ou exclui memórias com base no conteúdo das informações recém-extraídas e nas memórias atuais. Uma recordação poderá ser excluída se as novas informações a contradizerem ou se o conteúdo extraído instruir o Memory Bank a esquecer um assunto (no caso do EXPLICIT_INSTRUCTIONS tópico de memória).

Por exemplo, a solicitação a seguir excluiria as recordações atuais que contêm informações sobre preferências alimentares, se elas existirem para o scope especificado:

from google import genai

client.agent_engines.memories.generate(
    name=agent_engine.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={...}
)

Limpar

Para limpar todos os recursos usados neste projeto, você pode excluir o Google Cloud projeto usado no guia de início rápido.

Caso contrário, exclua os recursos individuais criados neste tutorial, da seguinte maneira:

  1. Use o exemplo de código a seguir para excluir a instância do Agent Platform, que também exclui todas as sessões ou recordações associadas a ela.

    agent_engine.delete(force=True)

  2. Exclua todos os arquivos criados localmente.

A seguir

Guia de início rápido

Introdução ao Kit de Desenvolvimento de Agente (ADK).