Guía de inicio rápido de Memory Bank con el ADK

Agent Platform Memory Bank permite que tus agentes administren memorias a largo plazo en todas las sesiones. Cuando se usa con el Kit de desarrollo de agentes (ADK), tu agente puede organizar automáticamente las llamadas a Memory Bank para almacenar y recuperar memorias en función de las interacciones del usuario.

En este documento, se explica cómo crear un agente del ADK, configurarlo para que use Memory Bank y cómo interactuar con él para generar memorias y acceder a ellas.

Para obtener información sobre cómo realizar llamadas directas a la API sin el ADK, consulta la guía de inicio rápido de la API de Memory Bank.

Importante: El ADK usa principalmente funciones asíncronas. Si ejecutas código en un notebook como Colaboratory, puedes await directamente las funciones asíncronas porque ya se está ejecutando un bucle de eventos. Si ejecutas este código como una secuencia de comandos estándar de Python, debes incluir las llamadas a funciones asíncronas en asyncio.run() para crear y administrar un bucle de eventos que ejecute tus funciones asíncronas. De lo contrario, es posible que recibas un error como 'await' outside function.

Para ver un ejemplo del uso de Memory Bank con el ADK, ejecuta el notebook "Comienza a usar Memory Bank en el ADK" en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Agent Platform Workbench | Ver en GitHub

Administra memorias con el servicio de memoria del ADK y Memory Bank

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

La interfaz VertexAiMemoryBankService incluye lo siguiente:

• memory_service.add_session_to_memory activa una solicitud GenerateMemories a Memory Bank con todos los eventos del adk.Session proporcionado como contenido fuente. Puedes organizar 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 GenerateMemories solicitud a Memory Bank con un subconjunto de eventos. Puedes organizar 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 RetrieveMemories solicitud a Memory Bank para recuperar memorias relevantes para el actual user_id y app_name. Puedes organizar 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 de introducción de la página Configura Memory Bank.

Configura las variables de entorno

Para usar el ADK, configura las variables de entorno:

import os

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

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto.
• LOCATION: Es tu región. Consulta las regiones admitidas para Memory Bank.

Crea tu agente del ADK

Para crear un agente habilitado para la memoria, configura herramientas y devoluciones de llamada que organicen las llamadas a tu servicio de memoria.

Define una devolución de llamada de generación de memoria

Para organizar 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 memorias y cómo se incluyen en la instrucción.

Si usas PreloadMemoryTool, tu agente recuperará memorias al comienzo de cada turno y las 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 las memorias son necesarias 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-3.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 memorias, lo que es útil cuando deseas proporcionar instrucciones a tu agente sobre cuándo recuperar memorias:

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-3.5-flash",
    name='stateful_agent',
    instruction="""...""",
    tools=[FunctionTool(func=search_memories)],
    after_agent_callback=generate_memories_callback
)

Define un servicio de memoria de Memory Bank del ADK y una instancia de Memory Bank

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

Crea una instancia de Memory Bank

Nota: Omite esta sección si ya tienes una instancia de Memory Bank existente.

Primero debes crear una instancia de Memory Bank. Este paso es opcional si usas Agent Runtime 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 Memory Bank en la página Configura Memory Bank.

import vertexai

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

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

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

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto.
• LOCATION: Es tu región. Consulta las regiones admitidas para Memory Bank.

Crea un entorno de ejecución del ADK

Pasa el ID de la instancia de Memory Bank a los scripts de entorno de ejecución o implementación para que tu agente use Memory Bank como el servicio de memoria del ADK.

Ejecutor 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="MEMORY_BANK_ID",
)

# You can use any ADK session service. This example uses Sessions.
session_service = VertexAiSessionService(
    project="PROJECT_ID",
    location="LOCATION",
    agent_engine_id="SESSIONS_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: Es el ID del proyecto.
• LOCATION: Es tu región. Consulta las regiones admitidas para Memory Bank.
• APP_NAME: Es el nombre de la app del ADK. El nombre de la app se incluirá en el diccionario scope de las memorias generadas para que las memorias se aíslen entre los usuarios y las apps.
• MEMORY_BANK_ID: Es el ID de la instancia de Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.
• SESSIONS_ID: Es el ID de la instancia de Agent Platform Sessions. Por ejemplo, 789 en projects/my-project/locations/us-central1/reasoningEngines/789.

Agent Runtime en Gemini Enterprise Agent Platform

La plantilla del ADK de Agent Runtime (AdkApp) se puede usar de forma local y para implementar un agente del ADK en Agent Runtime. Cuando se implementa en Agent Platform, la plantilla del ADK de Memory Bank usa VertexAiMemoryBankService como el servicio de memoria predeterminado. 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 Memory Bank para obtener más detalles sobre la configuración de tu instancia de Memory Bank, incluido cómo personalizar el comportamiento de Memory Bank.

Usa el siguiente código para implementar tu agente del ADK habilitado para la memoria en Agent Runtime:

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 resource with your agent deployed to Agent Runtime.
# The Agent Runtime instance will also include an empty Memory Bank instance.
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 resource to deploy your agent to Agent Platform.
# Your agent will have access to the Runtime 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: Es el ID del proyecto.
• LOCATION: Es tu región. Consulta las regiones admitidas para Memory Bank.
• STAGING_BUCKET: Es tu bucket de Cloud Storage para usar en la etapa de pruebas de Agent 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="MEMORY_BANK_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 Runtime,
  # use `client.agent_engines.create(...)` or `client.agent_engines.update(...)`
  # and call the returned Agent Runtime 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: Es el ID del proyecto.
• LOCATION: Es tu región. Consulta las regiones admitidas para Memory Bank.
• MEMORY_BANK_ID: Es el ID de la instancia de Memory Bank que se usará para Memory Bank. Por ejemplo, 456 en projects/my-project/locations/us-central1/reasoningEngines/456.

Cloud Run

Para ver un ejemplo del uso de Memory Bank con Cloud Run, ejecuta el notebook "Comienza a usar Sessions y Memory Bank para agentes del ADK en Cloud Run" en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Agent Platform Workbench | Ver en GitHub

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

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

Google Kubernetes Engine (GKE)

Para ver un ejemplo del uso de Memory Bank con Google Kubernetes Engine, ejecuta el notebook "Comienza a usar Sessions y Memory Bank para agentes del ADK en Google Kubernetes Engine" en uno de los siguientes entornos:

Abrir en Colab | Abrir en Colab Enterprise | Abrir en Agent Platform Workbench | Ver en GitHub

Para implementar tu agente en GKE, consulta las instrucciones de la documentación del ADK para aprender a definir tu agente para la implementación en GKE.

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

ADK Web

Importante: ADK Web no está diseñado para usarse en implementaciones de producción. Debes usar ADK Web solo para fines de desarrollo y depuración.

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://MEMORY_BANK_ID

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto.
• LOCATION: Es tu región. Consulta las regiones admitidas para Memory Bank.
• MEMORY_BANK_ID: Es el ID de la instancia de 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 memorias se activará cada vez que se invoque el agente.

Las memorias 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 de interacción con tu agente depende de su entorno de ejecución:

Ejecutor 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 ejecutor.
• 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 las memorias generadas se almacena como {"user_id": "USER_ID"}.

Agent Runtime

Cuando usas la plantilla del ADK, puedes llamar a Agent Runtime 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 las memorias generadas se almacena como {"user_id": "USER_ID"}.

Cloud Run

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

GKE

Consulta la sección Prueba 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 de ADK Web en la documentación del ADK.

Interacción de ejemplo

Primera sesión

Si usaste PreloadMemoryTool, el agente intentará recuperar memorias 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 memorias 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:

1. Primer turno:

   • Usuario: "¿Puedes arreglar la temperatura?"

   • (Llamada a la herramienta): El ADK intenta recuperar memorias; no hay memorias disponibles.

   • Modelo: "¿Qué temperatura prefieres?"

   • (Devolución de llamada): El ADK activa la generación de memoria. No se extraen memorias.

2. Segundo turno:

   • Usuario: Me siento cómodo a 22 grados.

   • (Llamada a la herramienta): El ADK intenta recuperar memorias; no hay memorias disponibles.

   • Modelo: Muy bien, actualicé la temperatura a 22 grados.

   • (Devolución de llamada): El ADK activa la generación de memoria. Se crea 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 app y el mismo ID de usuario. Si el usuario proporciona información similar o contradictoria a las memorias existentes, la información nueva se consolidará con las memorias existentes.

1. Primer turno

   • Usuario: Arregla la temperatura. ¡Es muy incómodo!

   • (Llamada a la herramienta): El ADK intenta recuperar memorias. Se recupera la memoria "Me gusta la temperatura de 22 grados".

   • Modelo: Muy bien, actualicé la temperatura a 22 grados.

   • (Devolución de llamada): El ADK activa la generación de memoria. No se extraen memorias, ya que el usuario no compartió nada significativo para conservar.

2. Segundo turno

   • Usuario: En realidad, prefiero que haga más calor por las mañanas.

   • (Llamada a la herramienta): El ADK intenta recuperar memorias. Se recupera la memoria "Me gusta la temperatura de 22 grados".

   • Modelo: Muy bien, subí la temperatura.

   • (Devolución de llamada): El ADK activa la generación de memoria. La memoria existente "Me gusta la temperatura de 22 grados" se actualiza a "Por lo general, me gusta que la temperatura sea de 22 grados, pero prefiero que haga más calor por las mañanas".

Nota: Puede haber algunas variaciones en las respuestas del agente y de Memory Bank's según los modelos que se usen.

Usa un Memory Bank multirregional con un entorno de ejecución regional

Cuando usas Runtime con Memory Bank integrado, tu agente y Memory Bank se implementan en la misma región de forma predeterminada. Sin embargo, puedes desacoplarlos para usar un Memory Bank multirregional (por ejemplo, us) con un entorno de ejecución regional (por ejemplo, us-central1). Esta configuración te permite mantener un Memory Bank central en diferentes implementaciones regionales.

Para usar un Memory Bank multirregional, debes anular el compilador de servicios de memoria predeterminado del ADK para que apunte a la ubicación multirregional y al ID de Memory Bank correspondiente.

import vertexai
from google.adk.memory import VertexAiMemoryBankService
from vertexai.agent_engines import AdkApp

# Create the Memory Bank instance in a multi-region location (for example, 'us')
client_mb = vertexai.Client(project="PROJECT_ID", location="us")
memory_bank = client_mb.agent_engines.create()
memory_bank_id = memory_bank.api_resource.name.split(\"/\")[-1]


# Point your memory service to the 'us' location, 'us' Memory Bank
def memory_bank_service_builder():
    return VertexAiMemoryBankService(
        project="PROJECT_ID",
        location="us",
        agent_engine_id=memory_bank_id
    )

# Create the AdkApp with the overridden builder
adk_app = AdkApp(
    agent=agent,
    memory_service_builder=memory_bank_service_builder
)

# Deploy the runtime to a specific region (for example, 'us-central1')
client_runtime = vertexai.Client(project="PROJECT_ID", location="us-central1")
agent_engine = client_runtime.agent_engines.create(
    agent=adk_app,
    config={
        "staging_bucket": "STAGING_BUCKET",
        "requirements": ["google-cloud-aiplatform[agent_engines,adk]"]
    }
)

Reemplaza lo siguiente:

• PROJECT_ID: Es el ID del proyecto.
• STAGING_BUCKET: Es tu bucket de Cloud Storage para usar en la etapa de pruebas de Agent Runtime.

Limpia

Para limpiar todos los recursos usados en este proyecto, puedes borrar el Google Cloud proyecto 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:

1. Usa la siguiente muestra de código para borrar la instancia de Agent Runtime, que también borra cualquier sesión o memoria que pertenezca a ese entorno de ejecución.

   agent_engine.delete(force=True)
   

2. Borra los archivos creados de forma local.

¿Qué sigue?

Guía de inicio rápido

Guía de inicio rápido de la API de Memory Bank

Comienza a usar la API de Memory Bank para administrar memorias a largo plazo.