Usar o Memory Bank com o ADK

O Kit de Desenvolvimento de Agente (ADK) conecta agentes ao Memory Bank da Plataforma de Agentes por meio de VertexAiMemoryBankService, uma implementação da interface BaseMemoryService do ADK. Neste documento, explicamos como escolher uma ferramenta de callback e recuperação de memória e como conectar o serviço de memória em cada ambiente de execução do ADK.

Para executar um exemplo completo primeiro, consulte o guia de início rápido do Memory Bank com o ADK.

Antes de começar

  1. Faça login na sua conta do Google Cloud . Se você começou a usar o Google Cloudagora, crie uma conta para avaliar o desempenho dos nossos produtos em situações reais. Clientes novos também recebem US $300 em créditos para executar, testar e implantar cargas de trabalho sem custos financeiros.
  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  4. Verify that billing is enabled for your Google Cloud project.

  5. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  6. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  7. If you're using an existing project for this guide, verify that you have the permissions required to complete this guide. If you created a new project, then you already have the required permissions.

  8. Verify that billing is enabled for your Google Cloud project.

  9. Enable the Agent Platform API, if it is not already enabled.

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.

    Enable the API

  10. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário:

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade externo (IdP), confirme se você fez login na CLI gcloud com sua identidade federada.

  11. Instale o ADK e o SDK da Agent Platform:
    pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
  12. Crie uma instância do Memory Bank no console do Google Cloud ou com o SDK da Agent Platform. Na página Memory Bank, clique em Vincular a um agente > Usar com o ADK para receber um código de configuração pré-preenchido. Pule esta etapa se o Agent Runtime criar a instância para você.

Funções exigidas

Para receber as permissões necessárias para criar uma instância do Memory Bank e gerar e recuperar memórias, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

  • Criar ou atualizar uma instância do Memory Bank: Usuário da Agent Platform (`roles/aiplatform.user`)
  • Ler, gravar ou gerar memórias: Usuário do Memory Bank (`roles/aiplatform.memoryUser`)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Como os componentes do ADK funcionam com o Memory Bank

Um agente do ADK usa os seguintes componentes para ler e gravar memórias:

Componente Papel Obrigatório
Instância do Memory Bank Armazena e consolida memórias. Sim
VertexAiMemoryBankService Conecta seu agente ao Memory Bank como o serviço de memória do ADK. Sim
Serviço de sessão Armazena o histórico de conversas. Você pode usar qualquer serviço de sessão do ADK. Sim
Ferramenta de recuperação de memória Recupera as memórias do agente. Consulte Recuperar memórias com uma ferramenta. Para ler as recordações
Callback de geração de dados de memória Envia eventos de conversa para o Memory Bank depois que o agente responde. Consulte Gerar recordações com um callback. Para escrever recordações
Executor do ADK ou AdkApp Orquestra o agente, os serviços, as ferramentas e os callbacks. Sim

O diagrama a seguir mostra como esses componentes interagem em cada turno quando um agente usa PreloadMemoryTool e um callback de memória:

O Memory Bank define o escopo de cada memória para o ID do usuário e o nome do app que executam o agente, como {"user_id": USER_ID, "app_name": APP_NAME}. Somente solicitações com o mesmo ID do usuário e nome de app recuperam essas memórias.

Gerar recordações com um callback

Um callback de geração de memória envia eventos de conversa para o Memory Bank. O Memory Bank extrai memórias desses eventos e as consolida com as memórias existentes. Escolha um método com base na frequência com que você processa eventos:

Método Eventos enviados Quando usar
callback_context.add_events_to_memory Um subconjunto de eventos que você selecionar Recomendado. Processar eventos de forma incremental, por exemplo, após cada turno.
callback_context.add_session_to_memory Todos os eventos na sessão Chame uma vez no final de uma sessão para que os mesmos eventos não sejam processados mais de uma vez.

O exemplo a seguir envia eventos recentes após cada resposta do agente:

from google.adk.agents.callback_context import CallbackContext


async def generate_memories_callback(
    callback_context: CallbackContext,
) -> None:
    await callback_context.add_events_to_memory(
        events=callback_context.session.events[-5:]
    )
    return None

Para enviar a sessão completa, chame await callback_context.add_session_to_memory() em um callback no final da sessão.

Por padrão, o VertexAiMemoryBankService envia eventos usando a ingestão de eventos. Para aguardar até que a geração de memória seja concluída em testes ou demonstrações, transmita custom_metadata={"wait_for_completion": True} para add_events_to_memory.

Recuperar recordações com uma ferramenta

Uma ferramenta de recuperação de memória controla quando o agente recupera memórias e como elas entram no comando. Escolha uma das seguintes ferramentas:

Ferramenta Quando as recordações são recuperadas Quando usar
PreloadMemoryTool No início de cada turno. As memórias são injetadas no contexto da solicitação do modelo antes da vez do usuário atual. Estabeleça um contexto de referência sobre o usuário em cada turno.
LoadMemoryTool Quando o modelo decide que as memórias são necessárias para responder à consulta. Deixe o modelo decidir quando as memórias são relevantes.
Personalizado FunctionTool Quando o modelo chama sua ferramenta, guiado pela descrição dela. Dê instruções ao agente sobre quando recuperar as memórias.

O exemplo a seguir cria um agente que usa PreloadMemoryTool e o callback da seção anterior:

from google import adk
from google.adk.tools.preload_memory_tool import PreloadMemoryTool

agent = adk.Agent(
    model="gemini-3.5-flash",
    name="stateful_agent",
    instruction="You are a vehicle voice agent. Limit responses to 30 words.",
    tools=[PreloadMemoryTool()],
    after_agent_callback=generate_memories_callback,
)

Para permitir que o modelo decida quando recuperar memórias, importe LoadMemoryTool de google.adk.tools.load_memory_tool e transmita LoadMemoryTool() em tools.

Para escrever uma ferramenta de recuperação personalizada, chame tool_context.search_memory de uma chamada de ferramenta de função:

from typing import Any

from google import adk
from google.adk.tools import FunctionTool, ToolContext


async def search_memories(query: str, tool_context: ToolContext) -> Any:
    """Query this tool when you need information about user preferences."""
    return await tool_context.search_memory(query)


agent = adk.Agent(
    model="gemini-3.5-flash",
    name="stateful_agent",
    instruction=(
        "You are a vehicle voice agent. Before you change a setting, call "
        "search_memories to look up the user's preferences. Limit responses "
        "to 30 words."
    ),
    tools=[FunctionTool(func=search_memories)],
    after_agent_callback=generate_memories_callback,
)

Conectar o serviço de memória ao ambiente de execução

A forma de conectar o VertexAiMemoryBankService depende de onde o agente é executado. Selecione o ambiente de execução:

Corredor local

Ao executar o agente com adk.Runner, crie o serviço de memória e transmita-o para o executor:

import asyncio
import os

from google import adk
from google.adk.memory import VertexAiMemoryBankService
from google.adk.sessions import InMemorySessionService
from google.genai import types

os.environ["GOOGLE_GENAI_USE_ENTERPRISE"] = "TRUE"
os.environ["GOOGLE_CLOUD_PROJECT"] = "PROJECT_ID"
os.environ["GOOGLE_CLOUD_LOCATION"] = "LOCATION"

memory_service = VertexAiMemoryBankService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="MEMORY_BANK_ID",
)

# You can use any ADK session service. This example keeps sessions in memory.
# To persist conversation history, use VertexAiSessionService with a
# Sessions instance instead.
session_service = InMemorySessionService()

runner = adk.Runner(
    agent=agent,
    app_name="APP_NAME",
    session_service=session_service,
    memory_service=memory_service,
)

async def main() -> None:
    session = await session_service.create_session(
        app_name="APP_NAME",
        user_id="USER_ID",
    )
    message = types.Content(
        role="user", parts=[types.Part(text="Can you fix the temperature?")]
    )
    async for event in runner.run_async(
        user_id="USER_ID",
        session_id=session.id,
        new_message=message,
    ):
        if event.is_final_response() and event.content:
            print(event.content.parts[0].text)

asyncio.run(main())

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud , por exemplo, my-project.
  • LOCATION: seu local, por exemplo, global. Consulte os locais compatíveis e os endpoints globais e multirregionais do Memory Bank.
  • MEMORY_BANK_ID: o ID da instância do banco de memória, por exemplo, 456 em projects/my-project/locations/us-central1/reasoningEngines/456.
  • APP_NAME: o nome do app do ADK, por exemplo, my_agent. O Memory Bank inclui o nome do app no escopo da memória, para que as memórias sejam isoladas entre os apps.
  • USER_ID: um identificador para o usuário, por exemplo, user-123. As memórias geradas nesta sessão são limitadas a esse identificador.

Agent Runtime na Gemini Enterprise Agent Platform

Quando você implanta um agente do ADK no Agent Runtime com o modelo do ADK (AdkApp), o modelo usa VertexAiMemoryBankService por padrão. É possível criar a instância do Memory Bank e implantar o agente em uma etapa:

import asyncio

import agentplatform
from agentplatform.frameworks import AdkApp

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

adk_app = AdkApp(agent=agent)

# Create a resource with your agent deployed to Agent Runtime. The
# resource also includes an empty Memory Bank instance.
runtime_instance = client.runtimes.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

async def main() -> None:
    session = await runtime_instance.async_create_session(
        user_id="USER_ID"
    )
    async for event in runtime_instance.async_stream_query(
        user_id="USER_ID",
        session_id=session.get("id"),
        message="Can you fix the temperature?",
    ):
        print(event)

asyncio.run(main())

Para implantar o agente em um recurso atual e manter as memórias dele, chame client.runtimes.update:

runtime_instance = client.runtimes.update(
    name="RUNTIME_NAME",
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

Quando você executa AdkApp localmente, ele usa InMemoryMemoryService por padrão. Para usar o Memory Bank localmente, substitua o serviço de memória:

from google.adk.memory import VertexAiMemoryBankService

def memory_bank_service_builder() -> VertexAiMemoryBankService:
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="MEMORY_BANK_ID",
    )

adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder,
)

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud , por exemplo, my-project.
  • LOCATION: a região ou multirregião do Agent Runtime, por exemplo, us-central1. Somente instâncias independentes do VertexAiMemoryBankService oferecem suporte ao global, não ao client.runtimes.create. Consulte os locais compatíveis.
  • STAGING_BUCKET: o URI do bucket do Cloud Storage para preparar o Agent Runtime, por exemplo, gs://my-staging-bucket.
  • USER_ID: um identificador para o usuário, por exemplo, user-123.
  • RUNTIME_NAME: o nome do recurso do Agent Runtime atual, no formato projects/.../locations/.../reasoningEngines/....
  • MEMORY_BANK_ID: o ID da instância do banco de memória, por exemplo, 456 em projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Para implantar o agente no Cloud Run, siga a documentação do ADK e transmita sua instância do Banco de Memória como o serviço de memória:

adk deploy cloud_run \
    ...
    --memory_service_uri=agentengine://MEMORY_BANK_ID

Substitua MEMORY_BANK_ID pelo ID da instância do banco de memória, por exemplo, 456. Para testar o agente implantado, consulte a documentação de implantação do ADK no Cloud Run.

Google Kubernetes Engine (GKE)

Para implantar o agente no GKE, siga a documentação do ADK e transmita a instância do Memory Bank como o serviço de memória:

adk deploy gke \
    ...
    --memory_service_uri=agentengine://MEMORY_BANK_ID

Substitua MEMORY_BANK_ID pelo ID da instância do banco de memória, por exemplo, 456. Para testar o agente implantado, consulte a seção Como testar seu agente da documentação de implantação do ADK no GKE.

Web do ADK

O ADK Web é uma interface de navegador local para testar e inspecionar seu agente durante o desenvolvimento.

O ADK Web lê o projeto e o local das variáveis de ambiente. Execute os comandos a seguir no terminal, no diretório que contém a pasta do agente:

export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
export GOOGLE_CLOUD_LOCATION=LOCATION
adk web --memory_service_uri=agentengine://MEMORY_BANK_ID

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud , por exemplo, my-project.
  • LOCATION: seu local, por exemplo, global. Consulte os locais compatíveis e os endpoints globais e multirregionais do Memory Bank.
  • MEMORY_BANK_ID: o ID da instância do Memory Bank, por exemplo, 456.

Em seguida, abra http://localhost:8000 no navegador. Por padrão, o ADK Web define o ID do usuário como user. Para usar um ID do usuário diferente, adicione o parâmetro de consulta userId, por exemplo, http://localhost:8000?userId=USER_ID.

Usar um Memory Bank multirregional com um ambiente de execução regional

Por padrão, quando você usa o ambiente de execução com o banco de memória integrado, o agente e o banco de memória são implantados na mesma região. Para manter um Memory Bank central em implantações regionais, é possível parear um Memory Bank multirregional (como us) com um ambiente de execução regional (como us-central1).

Para usar um banco de memória multirregional, substitua o builder de serviço de memória padrão do ADK para que ele aponte para o local e o ID da instância multirregionais:

import agentplatform
from agentplatform.frameworks import AdkApp
from google.adk.memory import VertexAiMemoryBankService

# Create the Memory Bank instance in a multi-region location.
client_mb = agentplatform.Client(
    project="PROJECT_ID",
    location="us",
)
memory_bank = client_mb.memory_banks.create()
memory_bank_id = memory_bank.name.split("/")[-1]


# Point the memory service to the multi-regional instance.
def memory_bank_service_builder() -> VertexAiMemoryBankService:
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="us",
        agent_engine_id=memory_bank_id,
    )


adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder,
)

# Deploy the runtime to a specific region.
client_runtime = agentplatform.Client(
    project="PROJECT_ID",
    location="us-central1",
)
runtime_instance = client_runtime.runtimes.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-agentplatform[runtimes,adk]"],
    },
)

Substitua:

  • PROJECT_ID: o ID do projeto do Google Cloud , por exemplo, my-project.
  • STAGING_BUCKET: o URI do bucket do Cloud Storage para preparar o Agent Runtime, por exemplo, gs://my-staging-bucket.

Para excluir esses recursos, exclua o ambiente de execução e a instância multirregional. Se você excluir uma instância logo após uma conversa, a solicitação poderá falhar com um erro FAILED_PRECONDITION enquanto a geração de memória é concluída. Se isso acontecer, aguarde um minuto e execute a exclusão novamente.

client_runtime.runtimes.delete(
    name=runtime_instance.api_resource.name,
    force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)

A seguir

Guia de início rápido

Criar um agente do ADK que se lembra das preferências do usuário.

Guia

Saiba como gerar recordações no Memory Bank.

Guia

Saiba como configurar o Banco de Memória.