Guía de inicio rápido con el kit de desarrollo de agentes

En este instructivo, se muestra cómo puedes usar Memory Bank con el ADK para administrar recuerdos a largo plazo. Después de configurar tu agente del Kit de desarrollo de agentes (ADK) para que use Memory Bank, tu agente coordina las llamadas a Memory Bank para administrar las memorias a largo plazo por ti.

Para usar Memory Bank con el ADK, sigue estos pasos:

Crea tu agente y tu objeto Runner del ADK. Los ejecutores del ADK conectan tu agente a los servicios que proporcionan administración de sesión y memoria.
Interactúa con tu agente para generar de forma dinámica recuerdos a largo plazo a los que se puede acceder en todas las sesiones.
Realiza una limpieza.

Para realizar llamadas directamente a Memory Bank sin la organización de ADK, consulta la Guía de inicio rápido con el SDK de Agent Engine. Usar el SDK de Agent Engine es útil para comprender cómo Memory Bank genera recuerdos o para inspeccionar el contenido de Memory Bank.

Administra la memoria con el servicio de memoria de ADK y Memory Bank

VertexAiMemoryBankService es un wrapper del ADK alrededor de Memory Bank que se define con BaseMemoryService del ADK. Puedes definir devoluciones de llamada y herramientas que interactúen con el servicio de memoria para leer y escribir recuerdos.

La interfaz VertexAiMemoryBankService incluye lo siguiente:

memory_service.add_session_to_memory activa una solicitud de GenerateMemories a Memory Bank con todos los eventos del adk.Session proporcionado como contenido fuente. Puedes coordinar las llamadas a este método con callback_context.add_session_to_memory en tus devoluciones de llamada.
```
from google.adk.agents.callback_context import CallbackContext

async def add_session_to_memory_callback(callback_context: CallbackContext):
    await callback_context.add_session_to_memory()
    return None
```

memory_service.add_events_to_memory, que activa una solicitud de GenerateMemories a Memory Bank con un subconjunto de eventos. Puedes coordinar las llamadas a este método con callback_context.add_events_to_memory en tus devoluciones de llamada.

from google.adk.agents.callback_context import CallbackContext

async def add_events_to_memory_callback(callback_context: CallbackContext):
    await callback_context.add_events_to_memory(events=callback_context.session.events[-5:-1])
    return None

memory_service.search_memory activa una solicitud de RetrieveMemories a Memory Bank para recuperar recuerdos relevantes para el user_id y el app_name actuales. Puedes coordinar las llamadas a este método con herramientas de memoria integradas (LoadMemoryTool o PreloadMemoryTool) o una herramienta personalizada que invoque tool_context.search_memory.

Antes de comenzar

Para completar los pasos que se muestran en este instructivo, primero debes seguir los pasos de la sección Comienza a usar Memory Bank de la página Configura Memory Bank.

Configura las variables de entorno

Para usar el ADK, configura tus variables de entorno:

import os

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

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones compatibles con Memory Bank.

Crea tu agente del ADK

Para crear un agente con memoria, configura herramientas y devoluciones de llamada que orquesten las llamadas a tu servicio de memoria.

Cómo definir una devolución de llamada de generación de memoria

Para coordinar las llamadas para la generación de memoria, crea una función de devolución de llamada que active la generación de memoria. Puedes enviar un subconjunto de eventos (con callback_context.add_events_to_memory) o todos los eventos de una sesión (con callback_context.add_session_to_memory) para que se procesen en segundo plano:

  from google.adk.agents.callback_context import CallbackContext

  async def generate_memories_callback(callback_context: CallbackContext):
      # Option 1 (Recommended): Send events to Memory Bank for memory generation,
      # which is ideal for incremental processing of events.
      await callback_context.add_events_to_memory(
        events=callback_context.session.events[-5:-1])

      # Option 2: Send the full session to Memory Bank for memory generation.
      # It's recommended to only call this at the end of a session to minimize
      # how many times a single event is re-processed.
      await callback_context.add_session_to_memory()

      return None

Define una herramienta de recuperación de memoria

Cuando desarrolles tu agente del ADK, incluye una herramienta de memoria que controle cuándo el agente recupera recuerdos y cómo se incluyen en la instrucción.

Si usas PreloadMemoryTool, tu agente recuperará recuerdos al comienzo de cada turno y los incluirá en la instrucción del sistema, lo que es útil para establecer un contexto de referencia sobre el usuario. Si usas LoadMemoryTool, el modelo llamará a esta herramienta cuando decida que los recuerdos son necesarios para responder la consulta del usuario.

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

  memory_retrieval_tools = [
    # Option 1: Retrieve memories at the start of every turn.
    PreloadMemoryTool(),
    # Option 2: Retrieve memories via tool calls. The model will only call this tool
    # when it decides that memories are necessary to respond to the user query.
    LoadMemoryTool()
  ]

  agent = adk.Agent(
      model="gemini-2.5-flash",
      name='stateful_agent',
      instruction="""You are a Vehicle Voice Agent, designed to assist users with information and in-vehicle actions.

  1.  **Direct Action:** If a user requests a specific vehicle function (e.g., "turn on the AC"), execute it immediately using the corresponding tool. You don't have the outcome of the actual tool execution, so provide a hypothetical tool execution outcome.
  2.  **Information Retrieval:** Respond concisely to general information requests with your own knowledge (e.g., restaurant recommendation).
  3.  **Clarity:** When necessary, try to seek clarification to better understand the user's needs and preference before taking an action.
  4.  **Brevity:** Limit responses to under 30 words.
  """,
      tools=memory_retrieval_tools,
      after_agent_callback=generate_memories_callback
  )

Como alternativa, puedes crear tu propia herramienta personalizada para recuperar recuerdos, lo que resulta útil cuando quieres darle instrucciones a tu agente sobre cuándo recuperar recuerdos:

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

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

  agent = adk.Agent(
      model="gemini-2.5-flash",
      name='stateful_agent',
      instruction="""...""",
      tools=[FunctionTool(func=search_memories)],
      after_agent_callback=generate_memories_callback
  )

Define un servicio de memoria y un tiempo de ejecución de Memory Bank de ADK

Después de crear tu agente con memoria, debes vincularlo a un servicio de memoria. El proceso de configuración del servicio de memoria del ADK depende de dónde se ejecuta el agente del ADK, que organiza la ejecución de tus agentes, herramientas y devoluciones de llamada.

Primero, debes crear una instancia de Agent Engine para usarla con Memory Bank. Este paso es opcional si usas el entorno de ejecución de Agent Engine para implementar tu agente. Para obtener más información sobre cómo personalizar el comportamiento de Memory Bank, consulta la sección Configura tu instancia de Agent Engine para Memory Bank en la página Configura Memory Bank.

import vertexai

client = vertexai.Client(
  project="PROJECT_ID",
  location="LOCATION"
)
# If you don't have an Agent Engine instance already, create an Agent Engine
# Memory Bank instance using the default configuration.
agent_engine = client.agent_engines.create()

# Optionally, print out the Agent Engine resource name. You will need the
# resource name if you want to interact with your Agent Engine instance later on.
print(agent_engine.api_resource.name)

agent_engine_id = agent_engine.api_resource.name.split("/")[-1]

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones compatibles con Memory Bank.

Luego, pasa el ID de Agent Engine a los scripts de implementación o de tiempo de ejecución para que tu agente use Memory Bank como el servicio de memoria del ADK.

Corredor local

Por lo general, adk.Runner se usa en un entorno local, como Colab. En este caso, debes crear directamente el servicio de memoria y el ejecutor.

import asyncio

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

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

# You can use any ADK session service. This example uses Agent Engine Sessions.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id=agent_engine_id
)

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

async def call_agent(query, session, user_id):
  content = types.Content(role='user', parts=[types.Part(text=query)])
  events = runner.run_async(
    user_id=user_id, session_id=session, new_message=content)

  async for event in events:
      if event.is_final_response():
          final_response = event.content.parts[0].text
          print("Agent Response: ", final_response)

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones compatibles con Memory Bank.
APP_NAME: Nombre de la app del ADK. El nombre de la app se incluirá en el diccionario scope de los recuerdos generados para que los recuerdos se aíslen entre los usuarios y las apps.

Motor del agente

La plantilla del ADK de Agent Engine (AdkApp) se puede usar de forma local y para implementar un agente del ADK en el entorno de ejecución de Agent Engine. Cuando se implementa en el entorno de ejecución de Agent Engine, la plantilla del ADK de Agent Engine usa VertexAiMemoryBankService como servicio de memoria predeterminado, con la misma instancia de Agent Engine para Memory Bank que el entorno de ejecución de Agent Engine. Por lo tanto, puedes crear tu instancia de Memory Bank y realizar la implementación en un entorno de ejecución en un solo paso.

Consulta Configura Agent Engine para obtener más detalles sobre cómo configurar tu entorno de ejecución de Agent Engine, incluido cómo personalizar el comportamiento de tu banco de memoria.

Usa el siguiente código para implementar tu agente del ADK habilitado para la memoria en el entorno de ejecución de Agent Engine:

import asyncio

import vertexai
from vertexai.agent_engines import AdkApp

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

adk_app = AdkApp(agent=agent)

# Create a new Agent Engine with your agent deployed to Agent Engine Runtime.
# The Agent Engine instance will also include an empty Memory Bank.
agent_engine = client.agent_engines.create(
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

# Alternatively, update an existing Agent Engine to deploy your agent to Agent Engine Runtime.
# Your agent will have access to the Agent Engine instance's existing memories.
agent_engine = client.agent_engines.update(
      name=agent_engine.api_resource.name,
      agent_engine=adk_app,
      config={
            "staging_bucket": "STAGING_BUCKET",
            "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
      }
)

async def call_agent(query, session_id, user_id):
    async for event in agent_engine.async_stream_query(
        user_id=user_id,
        session_id=session_id,
        message=query,
    ):
        print(event)

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones compatibles con Memory Bank.
STAGING_BUCKET: Es tu bucket de Cloud Storage que se usará para la etapa intermedia de tu Agent Engine Runtime.

Cuando se ejecuta de forma local, la plantilla del ADK usa InMemoryMemoryService como el servicio de memoria predeterminado. Sin embargo, puedes anular el servicio de memoria predeterminado para usar VertexAiMemoryBankService:

def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="LOCATION",
        agent_engine_id="AGENT_ENGINE_ID"
    )

adk_app = AdkApp(
      agent=adk_agent,
      # Override the default memory service.
      memory_service_builder=memory_bank_service_builder
)

async def call_agent(query, session_id, user_id):
  # adk_app is a local agent. If you want to deploy it to Agent Engine Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Engine instance instead.
  async for event in adk_app.async_stream_query(
      user_id=user_id,
      session_id=session_id,
      message=query,
  ):
      print(event)

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones compatibles con Memory Bank.
AGENT_ENGINE_ID: Es el ID de Agent Engine que se usará para Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Para implementar tu agente en Cloud Run, consulta las instrucciones de la documentación del ADK para aprender a definir tu agente y, luego, implementarlo en Cloud Run.

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

GKE

Para implementar tu agente en Google Kubernetes Engine (GKE), consulta las instrucciones de la documentación del ADK para aprender a definir tu agente y, luego, implementarlo en GKE.

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

ADK Web

La interfaz web del ADK te permite probar tus agentes directamente en el navegador.

export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
export GOOGLE_CLOUD_LOCATION="LOCATION"

adk web --memory_service_uri=agentengine://AGENT_ENGINE_ID

Reemplaza lo siguiente:

PROJECT_ID: ID del proyecto
LOCATION: Tu región. Consulta las regiones compatibles con Memory Bank.
AGENT_ENGINE_ID: Es el ID de Agent Engine que se usará para Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.

Interactúa con el agente

Después de definir tu agente y configurar Memory Bank, puedes interactuar con él. Si proporcionaste una devolución de llamada para activar la generación de memoria cuando inicializaste tu agente, la generación de memoria se activará cada vez que se invoque el agente.

Los recuerdos se almacenarán con el alcance {"user_id": USER_ID, "app_name": APP_NAME} correspondiente al ID de usuario y al nombre de la app que se usaron para ejecutar tu agente.

El método para interactuar con tu agente depende de su entorno de ejecución:

Corredor local

# Use `asyncio.run(session_service.create(...))` if you're running this
# code as a standard Python script.
session = await session_service.create_session(
    app_name="APP_NAME",
    user_id="USER_ID"
)

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent(
    "Can you fix the temperature?",
    session.id,
    "USER_ID"
)

Reemplaza lo siguiente:

APP_NAME: Es el nombre de la app para tu runner.
USER_ID: Es un identificador para tu usuario. Las memorias generadas a partir de esta sesión se indexan con este identificador opaco. El alcance de los recuerdos generados se almacena como {"user_id": "USER_ID"}.

Motor del agente

Cuando usas la plantilla del ADK de Agent Engine, puedes llamar a tu entorno de ejecución de Agent Engine para interactuar con la memoria y las sesiones.

# Use `asyncio.run(agent_engine.async_create_session(...))` if you're
# running this code as a standard Python script.
session = await agent_engine.async_create_session(user_id="USER_ID")

# Use `asyncio.run(call_agent(...))` if you're running this code as a
# standard Python script.
await call_agent(
    "Can you fix the temperature?",
    session.get("id"),
    "USER_ID"
)

Reemplaza lo siguiente:

USER_ID: Es un identificador para tu usuario. Las memorias generadas a partir de esta sesión se indexan con este identificador opaco. El alcance de los recuerdos generados se almacena como {"user_id": "USER_ID"}.

Cloud Run

Consulta la sección Prueba tu agente de la documentación de implementación del ADK en Cloud Run.

GKE

Consulta la sección Cómo probar tu agente de la documentación de implementación de GKE del ADK.

ADK Web

Para usar ADK Web, navega al servidor local en http://localhost:8000.

De forma predeterminada, ADK Web establecerá el ID de usuario en user. Para anular el ID de usuario predeterminado, incluye userId en los parámetros de consulta, como http://localhost:8000?userId=YOUR_USER_ID.

Para obtener más información, consulta la página ADK Web en la documentación del ADK.

Ejemplo de interacción

Primera sesión

Si usaste PreloadMemoryTool, el agente intentará recuperar recuerdos al comienzo de cada turno para acceder a las preferencias que el usuario le comunicó anteriormente. Durante la primera interacción del agente con el usuario, no hay recuerdos disponibles para recuperar. Por lo tanto, el agente no conoce las preferencias del usuario, como su temperatura preferida, como se muestra en el siguiente ejemplo:

Primer turno:
- Usuario: "¿Puedes arreglar la temperatura?"
- (Llamada a la herramienta): El ADK intenta recuperar recuerdos, pero no hay ninguno disponible.
- Modelo: "¿Qué temperatura prefieres?"
- (Devolución de llamada): El ADK activa la generación de memoria. No se extraen recuerdos.
Segundo turno:
- Usuario: Me siento cómodo a 22 °C.
- (Llamada a la herramienta): El ADK intenta recuperar recuerdos, pero no hay ninguno disponible.
- Modelo: De acuerdo. Actualicé la temperatura a 22 °C.
- (Devolución de llamada): El ADK activa la generación de memoria. Se creó la memoria "Me gusta la temperatura de 22 grados".

Segunda sesión

La memoria extraída estará disponible para la próxima sesión con el mismo nombre de la app y el mismo ID de usuario. Si el usuario proporciona información similar o contradictoria a los recuerdos existentes, la información nueva se consolidará con los recuerdos existentes.

Primer turno
- Usuario: Arregla la temperatura. ¡Es tan incómodo!
- (Llamada a la herramienta): El ADK intenta recuperar recuerdos. Se recupera la memoria "Me gusta la temperatura a 22 grados".
- Modelo: De acuerdo. Actualicé la temperatura a 22 °C.
- (Devolución de llamada): El ADK activa la generación de memoria. No se extraen recuerdos porque el usuario no compartió nada significativo para conservar.
Segundo turno
- Usuario: En realidad, prefiero que esté más cálido por las mañanas.
- (Llamada a la herramienta): El ADK intenta recuperar recuerdos. Se recupera la memoria "Me gusta la temperatura a 22 grados".
- Modelo: De acuerdo, subí la temperatura.
- (Devolución de llamada): El ADK activa la generación de memoria. La memoria existente "Me gusta la temperatura a 22 grados" se actualiza a "Por lo general, me gusta la temperatura a 22 grados, pero me gusta que esté más cálida por las mañanas".

Realiza una limpieza

Para limpiar todos los recursos que se usaron en este proyecto, puedes borrar el proyecto Google Cloud que usaste para la guía de inicio rápido.

De lo contrario, puedes borrar los recursos individuales que creaste en este instructivo de la siguiente manera:

Usa el siguiente muestra de código para borrar la instancia de Vertex AI Agent Engine, lo que también borrará las sesiones o memorias que pertenezcan a ese Vertex AI Agent Engine.
```
agent_engine.delete(force=True)
```
Borra los archivos creados de forma local.

¿Qué sigue?

Guía de inicio rápido con el SDK de Agent Engine

Guía de inicio rápido con el kit de desarrollo de agentes Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Administra la memoria con el servicio de memoria de ADK y Memory Bank

Antes de comenzar

Configura las variables de entorno

Crea tu agente del ADK

Cómo definir una devolución de llamada de generación de memoria

Define una herramienta de recuperación de memoria

Define un servicio de memoria y un tiempo de ejecución de Memory Bank de ADK

Corredor local

Motor del agente

Cloud Run

GKE

ADK Web

Interactúa con el agente

Corredor local

Motor del agente

Cloud Run

GKE

ADK Web

Ejemplo de interacción

Realiza una limpieza

¿Qué sigue?

Guía de inicio rápido con el kit de desarrollo de agentes