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
- 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.
-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
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 theresourcemanager.projects.createpermission. Learn how to grant roles.
-
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.
-
Verify that billing is enabled for your Google Cloud project.
Enable the Agent Platform API, if it is not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. 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.-
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.
- Instale o ADK e o SDK da Agent Platform:
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
- 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,
456emprojects/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 doVertexAiMemoryBankServiceoferecem suporte aoglobal, não aoclient.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,
456emprojects/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_IDSubstitua:
- 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 do Kit de Desenvolvimento de Agente
Criar um agente do ADK que se lembra das preferências do usuário.