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

Com o Memory Bank da Agent Platform, é possível fazer chamadas de API diretamente para sessões e o Memory Bank usando o SDK da Agent Platform. Use o SDK da plataforma de agentes se não quiser que uma estrutura de agentes organize as chamadas para você ou se quiser integrar sessões e o Memory Bank com estruturas de agentes que não sejam o 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 ADK.

Antes de começar

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

Gerar lembranças com as sessões da plataforma de agentes

Depois de configurar as sessões da plataforma do agente 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. Para mais informações, consulte Gerar memórias e Buscar memórias.

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 explicitamente 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 de uma instância atual 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 nesta sessão são automaticamente identificadas pelo escopo {"user_id": "USER_ID"}, a menos que você forneça explicitamente um escopo ao gerar recordações.

Faça upload iterativo de eventos para sua sessão. 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 sua sessão. Esse histórico de conversa é 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"}]
  }
}
)

Para gerar recordações com base no 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 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 recordações

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

Para garantir a consistência com as memórias geradas, tente escrever fatos pré-extraídos na mesma perspectiva que você configurou para o escopo específico. Por padrão, as recordações são geradas na perspectiva de 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, use CreateMemory para fazer upload de recordações sem usar o Memory Bank para extração ou consolidação de recordações.

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

Você pode recuperar memórias do usuário e incluí-las nas instruções do sistema para dar ao LLM acesso ao seu 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"}
    )
)

Use o 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 sua instância do Memory Bank dependendo de como você quer selecionar quais recordações devem ser removidas.

Remover pelo nome do recurso

Se você souber exatamente qual recurso de memória quer remover, exclua 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}. Para encontrar o nome de uma recordação, busque recordações.

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 dos atributos 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 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 recordações".
FILTER_GROUPS: uma lista de dicionários ou objetos para filtrar em relação aos 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 memórias foram excluídas (se force=True) ou seriam excluídas 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 decide 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 pode 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 tópico de memória EXPLICIT_INSTRUCTIONS).

Por exemplo, a solicitação a seguir excluiria as recordações 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, exclua o projeto Google Cloud usado no guia de início rápido.

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

Use o exemplo de código a seguir para excluir a instância da plataforma do agente, o que também exclui todas as sessões ou memórias associadas a ela.
```
agent_engine.delete(force=True)
```
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

Comece a usar o Kit de Desenvolvimento de Agente (ADK).

Guia de início rápido da API Agent Platform Memory Bank Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Antes de começar

Gerar lembranças com as sessões da plataforma de agentes

Fazer upload de recordações

Recuperar e usar recordações

Remover recordações

Remover pelo nome do recurso

Remover por critérios

Remover por significado semântico

Limpar

A seguir

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

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