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

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 para você 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 memórias 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 memórias com as sessões do Agent Platform

Depois de configurar as sessões da plataforma de agentes e o Memory Bank, você pode criar sessões e anexar eventos a elas. As memórias 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 memórias e Buscar memórias.

  1. Crie uma sessão com um ID de usuário opaco. Todas as memórias 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 memórias.

    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 memórias 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 memórias.

  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 memórias 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 memórias do histórico de conversas, acione uma solicitação de geração de memória 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 memórias geradas, com um máximo de cinco pares de chave-valor e sem * caracteres. Por exemplo, {"session_id": "MY_SESSION"}. Somente as memórias 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 memórias

Como alternativa à geração de memórias usando diálogo bruto, você pode fazer upload de memórias 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 memórias geradas, tente escrever fatos pré-extraídos na mesma perspectiva que você configurou para o escopo especificado. Por padrão, as memórias 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 memórias 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 memórias geradas. Por exemplo, {"session_id": "MY_SESSION"}. Somente as memórias com o mesmo escopo são consideradas para consolidação.

Como alternativa, você pode usar CreateMemory para fazer upload de memórias 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 memórias

É possível recuperar memórias 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 memórias usando um método baseado em escopo, consulte Buscar memórias.

# 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 memórias 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 memórias

Há várias maneiras de excluir memórias da instância do Memory Bank, dependendo de como você quer selecionar quais memórias 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 memórias.

Remover por critérios

É possível usar a exclusão baseada em critérios para remover uma ou mais memórias. Somente as memórias 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:

A operação vai retornar uma contagem de quantas memórias 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 memórias 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 memória 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 memórias 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 memórias associadas à instância do Agent Platform.

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