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

Use o SDK da Plataforma de Agentes para fazer chamadas de API diretamente para o Memory Bank. Use o SDK da Agent Platform se você não quiser que um framework de agente orquestre chamadas para você ou se quiser integrar o Memory Bank com frameworks de agente que não sejam o 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.

Para conferir um exemplo de como usar com o SDK, execute o notebook "Começar a usar o banco de memória" em um dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Workbench da plataforma de agentes | Ver no GitHub

Para conferir um exemplo de uso do com o LangGraph, execute o notebook "Começar a usar o - LangGraph" em um dos seguintes ambientes:

Abrir no Colab | Abrir no Colab Enterprise | Abrir no Workbench da plataforma de agentes | Ver no GitHub

Antes de começar

Para concluir as etapas demonstradas neste tutorial, primeiro siga as etapas em Configurar o banco de memória. Antes de começar este guia de início rápido, verifique se você criou uma instância do Memory Bank e uma instância de sessões, como mostrado no exemplo a seguir:

import agentplatform

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

memory_bank = client.memory_banks.create()
sessions = client.runtimes.create()

Gerar memórias com as sessões da plataforma de agentes

Depois de configurar as sessões da Agent Platform, você pode criar sessões e adicionar eventos a elas. Em seguida, use o Memory Bank para gerar memórias da conversa do usuário com o agente, de modo que elas fiquem disponíveis para interações futuras. Para mais informações, consulte Gerar recordações e Buscar recordações.

Observação: também é possível fornecer o histórico de conversas diretamente no payload GenerateMemories usando a origem de conteúdo direto.

1. Crie uma sessão com um ID do usuário opaco. Todas as memórias geradas nessa sessão são automaticamente codificadas pelo escopo {"user_id": "USER_ID"}, a menos que você forneça explicitamente um escopo ao gerar memórias.

   import agentplatform
   
   client = agentplatform.Client(
     project="PROJECT_ID",
     location="LOCATION"
   )
   
   session = client.sessions.create(
     # The name can be fetched using `sessions.name`.
     name="SESSIONS_NAME",
     user_id="USER_ID"
   )
   

   Substitua:

   • PROJECT_ID: o ID do projeto.

   • LOCATION: sua região. Consulte as regiões compatíveis com o Memory Bank.

   • SESSIONS_NAME: o nome da instância de sessões que você criou ou uma instância de sessões atual. O nome precisa estar no seguinte formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}.

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

2. Faça upload de eventos para sua sessão de forma iterativa. Os eventos podem incluir qualquer interação 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.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 com base no histórico de conversas, acione uma solicitação de geração de memória para a sessão:

   client.memory_banks.memories.generate(
     name=memory_bank.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 no máximo 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 recordações

Como alternativa à geração de memórias usando diálogos brutos, é possível 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 Banco de Memória extrair informações do seu conteúdo, você fornece os fatos que devem ser armazenados sobre o usuário diretamente.

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

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

Substitua:

• FACT: o fato pré-extraído que deve ser consolidado com as 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, use CreateMemory para fazer upload de memórias sem usar o Memory Bank para extração ou consolidação de memória.

Atenção: as memórias enviadas usando CreateMemory não serão consolidadas com as memórias atuais. Portanto, você pode acabar com memórias duplicadas para o mesmo escopo. As memórias criadas estão disponíveis para pesquisa de similaridade e podem ser consolidadas para solicitações futuras ao gerar memórias.

memory = client.memory_banks.memories.create(
    name=memory_bank.name,
    fact="This is a fact.",
    scope={"user_id": "123"}
)

"""
Returns a MemoryOperation containing the created Memory like:

MemoryOperation(
  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 as memórias do usuário e incluí-las nas instruções do sistema para dar ao LLM acesso ao contexto pessoal.

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

# Retrieve memories for User ID 123.
retrieved_memories = client.memory_banks.memories.retrieve(
    name=memory_bank.name,
    scope={"user_id": "123"}
).page

Use 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 recordações

Há várias maneiras de excluir recordações da instância do banco de recordações, dependendo de como você quer selecionar as recordações que serão removidas.

Remover por 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.memory_banks.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 que será excluída. O nome precisa estar no seguinte formato: projects/{your project}/locations/{your location}/reasoningEngine/{your reasoning engine}/memories/{your memory}. Para encontrar o nome da memória, busque as memórias.

Remover por critérios

Você pode usar a exclusão com base em critérios para remover uma ou mais recordações. Somente as recordações que corresponderem 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.memory_banks.memories.purge(
    name=memory_bank.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 a sintaxe EBNF 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 memórias".
• 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 memórias".

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 memórias que pertencem a um escopo para o user_id "123":

operation = client.memory_banks.memories.purge(
    name=memory_bank.name,
    filter="scope.user_id=\"123\"",
    force=True
)

Remover por significado semântico

Observação: o comportamento esperado pode variar de acordo com os tópicos de memória e os exemplos com poucos exemplos (few-shot) que você configurou.

Durante a geração de memórias, o Memory Bank decide se vai criar, atualizar ou excluir memórias com base no conteúdo das informações recém-extraídas e nas memórias atuais. Uma memória pode ser excluída se as novas informações a contradisserem ou se o conteúdo extraído instruir o Memory Bank a esquecer um assunto (no caso do tópico de memória EXPLICIT_INSTRUCTIONS).

Por exemplo, a solicitação a seguir excluiria as memórias que contêm informações sobre preferências alimentares, se existirem para o scope fornecido:

from google import genai

client.memory_banks.memories.generate(
    name=memory_bank.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, exclua o projeto do Google Cloud usado no guia de início rápido.

Você também pode excluir os recursos criados neste tutorial individualmente, da seguinte maneira:

1. Use o exemplo de código a seguir para excluir o Memory Bank e o Agent Runtime nas instâncias do Gemini Enterprise Agent Platform:

   client.memory_banks.delete(name=memory_bank.name, force=True)
   client.runtimes.delete(name=sessions.name, force=True)
   

2. Exclua todos os arquivos criados localmente.

A seguir

Guia de início rápido

Guia de início rápido do Kit de Desenvolvimento de Agente

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