El Kit de desarrollo de agentes (ADK) conecta a los agentes con Agent Platform Memory Bank a través de
VertexAiMemoryBankService,
una implementación de la interfaz
BaseMemoryService
del ADK. En este documento, se explica cómo elegir una herramienta de recuperación y devolución de llamada de memoria, y cómo conectar el servicio de memoria en cada entorno de ejecución del ADK.
Para ejecutar primero un ejemplo completo, consulta la guía de inicio rápido de Memory Bank con ADK.
Antes de comenzar
- Accede a tu cuenta de Google Cloud . Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.
-
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.-
Si usas una shell local, crea credenciales de autenticación locales para tu cuenta de usuario:
gcloud auth application-default login
No es necesario que lo hagas si usas Cloud Shell.
Si se muestra un error de autenticación y usas un proveedor de identidad externo (IdP), confirma que accediste a gcloud CLI con tu identidad federada.
- Instala el ADK y el SDK de Agent Platform:
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
- Crea una instancia de Memory Bank en la consola de Google Cloud o con el SDK de Agent Platform. En la página Memory Bank, haz clic en Vincular a un agente > Usar con ADK para obtener el código de configuración completado previamente. Omite este paso si Agent Runtime crea la instancia por ti.
Roles obligatorios
Para obtener los permisos que necesitas para crear una instancia de Memory Bank, y generar y recuperar recuerdos, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:
- Crea o actualiza una instancia de Memory Bank: Usuario de Agent Platform (`roles/aiplatform.user`)
- Leer, escribir o generar recuerdos: Usuario de Memory Bank (`roles/aiplatform.memoryUser`)
Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.
También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.
Cómo funcionan los componentes de ADK con Memory Bank
Un agente del ADK usa los siguientes componentes para leer y escribir memorias:
| Componente | Rol | Obligatorio |
|---|---|---|
| Instancia de Memory Bank | Almacena y consolida los recuerdos. | Sí |
VertexAiMemoryBankService |
Conecta tu agente a Memory Bank como el servicio de memoria de ADK. | Sí |
| Servicio de sesión | Almacena el historial de conversaciones. Puedes usar cualquier servicio de sesión de ADK. | Sí |
| Herramienta de recuperación de memoria | Recupera recuerdos para el agente. Consulta Recupera recuerdos con una herramienta. | Para leer recuerdos |
| Devolución de llamada de generación de memoria | Envía eventos de conversación a Memory Bank después de que el agente responde. Consulta Genera recuerdos con una devolución de llamada. | Escribir recuerdos |
ADK Runner o AdkApp |
Organiza el agente, los servicios, las herramientas y las devoluciones de llamada. | Sí |
En el siguiente diagrama, se muestra cómo interactúan estos componentes en cada turno cuando un
agente usa PreloadMemoryTool y una devolución de llamada de memoria:
Memory Bank limita cada memoria al ID de usuario y al nombre de la app que
ejecutan tu agente, como {"user_id": USER_ID, "app_name": APP_NAME}. Solo las solicitudes
con el mismo ID de usuario y nombre de app recuperan esos recuerdos.
Genera recuerdos con una devolución de llamada
Una devolución de llamada de generación de memoria envía eventos de conversación a Memory Bank. Memory Bank extrae memorias de esos eventos y las consolida con las memorias existentes. Elige un método según la frecuencia con la que procesas los eventos:
| Método | Eventos enviados | Cuándo usar |
|---|---|---|
callback_context.add_events_to_memory |
Un subconjunto de eventos que selecciones | (recomendado) Procesa los eventos de forma incremental, por ejemplo, después de cada turno. |
callback_context.add_session_to_memory |
Todos los eventos de la sesión | Llama una vez al final de una sesión para que los mismos eventos no se procesen más de una vez. |
En el siguiente ejemplo, se envían eventos recientes después de cada respuesta del 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 la sesión completa, llama a
await callback_context.add_session_to_memory() en una devolución de llamada al final de
la sesión.
De forma predeterminada, VertexAiMemoryBankService envía eventos con la transferencia
de eventos. Para esperar hasta que finalice la generación de memoria en las pruebas o demostraciones, pasa custom_metadata={"wait_for_completion": True} a add_events_to_memory.
Recupera recuerdos con una herramienta
Una herramienta de recuperación de memoria controla cuándo el agente recupera las memorias y cómo estas ingresan a la instrucción. Elige una de las siguientes herramientas:
| Herramienta | Cuándo se recuperan las memorias | Cuándo usar |
|---|---|---|
PreloadMemoryTool |
Al comienzo de cada turno. Las memorias se insertan en el contexto de la solicitud del modelo antes del turno del usuario actual. | Establece un contexto de referencia sobre el usuario en cada turno. |
LoadMemoryTool |
Cuando el modelo decide que los recuerdos son necesarios para responder la consulta. | Permite que el modelo decida cuándo son pertinentes los recuerdos. |
FunctionTool personalizada |
Cuando el modelo llama a tu herramienta, guiado por la descripción de la herramienta. | Dale instrucciones al agente sobre cuándo recuperar recuerdos. |
En el siguiente ejemplo, se crea un agente que usa PreloadMemoryTool y la devolución de llamada de la sección 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 el modelo decida cuándo recuperar recuerdos, importa LoadMemoryTool de
google.adk.tools.load_memory_tool y pasa LoadMemoryTool() en tools.
Para escribir una herramienta de recuperación personalizada, llama a tool_context.search_memory desde una llamada a la herramienta de función:
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,
)
Conecta el servicio de memoria a tu entorno de ejecución
La forma en que conectas VertexAiMemoryBankService depende de dónde se ejecuta tu agente. Selecciona tu entorno de ejecución:
Corredor local
Cuando ejecutes tu agente con adk.Runner, crea el servicio de memoria y
pásalo al ejecutor:
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())
Reemplaza lo siguiente:
- PROJECT_ID: Es el ID del proyecto de Google Cloud , por ejemplo,
my-project. - LOCATION: Es tu ubicación, por ejemplo,
global. Consulta las ubicaciones admitidas y los extremos globales y multirregionales para Memory Bank. - MEMORY_BANK_ID: Es el ID de la instancia de Memory Bank,
por ejemplo,
456enprojects/my-project/locations/us-central1/reasoningEngines/456. - APP_NAME: Es el nombre de la app de ADK, por ejemplo,
my_agent. Memory Bank incluye el nombre de la app en el alcance de la memoria, por lo que las memorias se aíslan entre las apps. - USER_ID: Es un identificador para tu usuario, por ejemplo,
user-123. Las memorias generadas a partir de esta sesión se limitan a este identificador.
Agent Runtime en Gemini Enterprise Agent Platform
Cuando implementas un agente del ADK en Agent Runtime con la
plantilla del ADK
(AdkApp), la plantilla usa VertexAiMemoryBankService de forma predeterminada. Puedes
crear la instancia de Memory Bank y, luego, implementar el agente en un solo
paso:
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 implementar el agente en un recurso existente y conservar las memorias existentes del recurso, llama a client.runtimes.update en su lugar:
runtime_instance = client.runtimes.update(
name="RUNTIME_NAME",
agent=adk_app,
config={
"staging_bucket": "STAGING_BUCKET",
"requirements": ["google-cloud-agentplatform[runtimes,adk]"],
},
)
Cuando ejecutas AdkApp de forma local, usa InMemoryMemoryService de forma predeterminada.
Para usar Memory Bank de forma local, anula el servicio de memoria:
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,
)
Reemplaza lo siguiente:
- PROJECT_ID: Es el ID del proyecto de Google Cloud , por ejemplo,
my-project. - LOCATION: Es la región o multirregión de Agent Runtime, por
ejemplo,
us-central1. Solo las instancias independientes deVertexAiMemoryBankServiceadmitenglobal, noclient.runtimes.create. Consulta las ubicaciones admitidas. - STAGING_BUCKET: Es el URI del bucket de Cloud Storage para almacenar en etapa intermedia
tu entorno de ejecución de agentes, por ejemplo,
gs://my-staging-bucket. - USER_ID: Es un identificador para tu usuario, por ejemplo,
user-123. - RUNTIME_NAME: Es el nombre del recurso del
Agent Runtime existente, en el formato
projects/.../locations/.../reasoningEngines/.... - MEMORY_BANK_ID: Es el ID de la instancia de Memory Bank,
por ejemplo,
456enprojects/my-project/locations/us-central1/reasoningEngines/456.
Cloud Run
Para implementar tu agente en Cloud Run, sigue la documentación del ADK y pasa tu instancia de Memory Bank como el servicio de memoria:
adk deploy cloud_run \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Reemplaza MEMORY_BANK_ID por el ID de tu instancia de Memory Bank, por ejemplo, 456. Para probar el agente implementado, consulta la
documentación de implementación de Cloud Run del ADK.
Google Kubernetes Engine (GKE)
Para implementar tu agente en GKE, sigue la documentación del ADK y pasa tu instancia de Memory Bank como el servicio de memoria:
adk deploy gke \
...
--memory_service_uri=agentengine://MEMORY_BANK_ID
Reemplaza MEMORY_BANK_ID por el ID de tu instancia de Memory Bank, por ejemplo, 456. Para probar el agente implementado, consulta la sección Prueba
tu agente
de la documentación de implementación de GKE del ADK.
ADK Web
ADK Web es una interfaz de navegador local para probar e inspeccionar tu agente durante el desarrollo.
ADK Web lee tu proyecto y ubicación desde las variables de entorno. Ejecuta los siguientes comandos en la terminal, desde el directorio que contiene la carpeta del 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_IDReemplaza lo siguiente:
- PROJECT_ID: Es el ID del proyecto de Google Cloud , por ejemplo,
my-project. - LOCATION: Es tu ubicación, por ejemplo,
global. Consulta las ubicaciones admitidas y los extremos globales y multirregionales para Memory Bank. - MEMORY_BANK_ID: Es el ID de la instancia de Memory Bank,
por ejemplo,
456.
Luego, abre http://localhost:8000 en tu navegador. De forma predeterminada, ADK Web establece
el ID de usuario en user. Para usar un ID de usuario diferente, agrega el parámetro de consulta userId,
por ejemplo, http://localhost:8000?userId=USER_ID.
Usa un Memory Bank multirregional con un entorno de ejecución regional
De forma predeterminada, cuando usas el entorno de ejecución con el banco de memoria integrado, tu agente y el banco de memoria se implementan en la misma región. Para mantener un banco de memoria central
en las implementaciones regionales, puedes vincular un banco de memoria
multirregional (como us) con un entorno de ejecución regional (como
us-central1).
Para usar un banco de memoria multirregional, anula el compilador de servicios de memoria del ADK predeterminado para que apunte a la ubicación multirregional y al ID de instancia:
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]"],
},
)
Reemplaza lo siguiente:
- PROJECT_ID: Es el ID del proyecto de Google Cloud , por ejemplo,
my-project. - STAGING_BUCKET: Es el URI del bucket de Cloud Storage para almacenar en etapa intermedia
tu entorno de ejecución de agentes, por ejemplo,
gs://my-staging-bucket.
Para borrar estos recursos, borra el entorno de ejecución y la instancia multirregional.
Si borras una instancia justo después de una conversación, la solicitud puede fallar con
un error FAILED_PRECONDITION mientras finaliza la generación de memoria. Si eso
sucede, espera un minuto y vuelve a ejecutar la eliminación.
client_runtime.runtimes.delete(
name=runtime_instance.api_resource.name,
force=True,
)
client_mb.memory_banks.delete(name=memory_bank.name, force=True)
¿Qué sigue?
Guía de inicio rápido con el Kit de desarrollo de agentes
Crear un agente del ADK que recuerde las preferencias del usuario