Guía de inicio rápido: Agrega memoria a largo plazo a un agente de ADK con Memory Bank

Agent Platform Memory Bank les brinda a los agentes que creas con el Kit de desarrollo de agentes (ADK) memoria a largo plazo en todas las sesiones. En esta guía de inicio rápido, ejecutarás un agente que aprende la temperatura preferida de un usuario en una sesión y recuerda la preferencia en la siguiente sesión.

En esta guía de inicio rápido, se te guiará por los siguientes pasos:

  • Configura el entorno.
  • Crea una instancia de Memory Bank.
  • Ejecutar un agente del ADK con memoria habilitada de forma local
  • Verifica que el agente recuerde la preferencia en una sesión nueva.

Para llamar a Memory Bank directamente sin ADK, consulta la guía de inicio rápido de la API de Memory Bank. Para elegir otras herramientas de memoria, devoluciones de llamada o entornos de ejecución, consulta Usa Memory Bank con el ADK.

Antes de comenzar

  1. 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.
  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. Configura un entorno de desarrollo de Python.
  11. 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.

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.

Configura tu entorno

  1. En la terminal, instala el ADK y el SDK de Agent Platform:

    pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"
  2. Establece las variables de entorno que leen las secuencias de comandos de esta guía de inicio rápido:

    export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
    export GOOGLE_CLOUD_PROJECT=PROJECT_ID
    export GOOGLE_CLOUD_LOCATION=global

    Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud .

    En esta guía de inicio rápido, se usa el extremo global. Para usar una ubicación regional o multirregional, reemplaza global por una de las ubicaciones admitidas. Si necesitas claves de encriptación administradas por el cliente (CMEK), usa una ubicación regional o multirregional, ya que las CMEK no están disponibles con el extremo global.

    Ejecuta el resto de esta guía de inicio rápido en la misma sesión de terminal y el mismo directorio para que las secuencias de comandos puedan leer estas variables.

Crea una instancia de banco de memoria

  1. Crea un archivo llamado create_memory_bank.py con el siguiente código:

    import os
    
    import agentplatform
    
    client = agentplatform.Client(
        project=os.environ["GOOGLE_CLOUD_PROJECT"],
        location=os.environ["GOOGLE_CLOUD_LOCATION"],
    )
    
    memory_bank = client.memory_banks.create(
        config={"display_name": "Memory Bank quickstart"}
    )
    
    # Print only the instance ID, for example 1234567890.
    print(memory_bank.name.split("/")[-1])
    
  2. Ejecuta la secuencia de comandos y guarda el ID de la instancia en la variable de entorno MEMORY_BANK_ID:

    export MEMORY_BANK_ID=$(python create_memory_bank.py)

    Si esta es tu primera instancia de Memory Bank, la creación puede tardar entre 1 y 2 minutos.

  3. Confirma que la variable contenga el ID de la instancia:

    echo $MEMORY_BANK_ID

    El resultado es un ID, como 1234567890. Si el resultado está vacío o devuelve un error 401 o 403, verifica tus roles obligatorios y ejecuta gcloud auth application-default login. Si una instancia nueva de global devuelve un error 403 transitorio en el primer uso, espera 30 segundos y vuelve a ejecutar la secuencia de comandos.

Ejecuta un agente con memoria habilitada

La secuencia de comandos de esta sección ejecuta dos sesiones para el mismo usuario. En la primera sesión, el usuario indica una preferencia de temperatura. En la segunda sesión, el agente recupera esa preferencia de Memory Bank.

Completa los siguientes pasos:

  1. Crea un directorio llamado memory_agent:

    mkdir memory_agent
  2. Crea un archivo llamado memory_agent/agent.py con el siguiente código. El código lee el ID del proyecto, la ubicación y la instancia de las variables que configuraste en Configura tu entorno y Crea una instancia de Memory Bank. No es necesario que edites el código.

    import asyncio
    import os
    
    import agentplatform
    from google import adk
    from google.adk.agents.callback_context import CallbackContext
    from google.adk.memory import VertexAiMemoryBankService
    from google.adk.sessions import InMemorySessionService
    from google.adk.tools.preload_memory_tool import PreloadMemoryTool
    from google.genai import types
    
    PROJECT_ID = os.environ["GOOGLE_CLOUD_PROJECT"]
    LOCATION = os.environ["GOOGLE_CLOUD_LOCATION"]
    MEMORY_BANK_ID = os.environ["MEMORY_BANK_ID"]
    # Memory Bank scopes memories to this app name and user ID.
    APP_NAME = "memory_agent"
    USER_ID = "quickstart_user"
    
    async def generate_memories_callback(
        callback_context: CallbackContext,
    ) -> None:
        # Send the latest turn to Memory Bank and wait until memory generation
        # finishes, so that the next session can retrieve the new memory.
        await callback_context.add_events_to_memory(
            events=callback_context.session.events[-5:],
            custom_metadata={"wait_for_completion": True},
        )
        return None
    
    root_agent = adk.Agent(
        model="gemini-3.5-flash",
        name="memory_agent",
        instruction=(
            "You are a vehicle voice agent that controls in-vehicle settings. "
            "Use what you know about the user's preferences. "
            "If you don't know the user's preferred temperature, ask for it. "
            "Limit responses to under 30 words."
        ),
        tools=[PreloadMemoryTool()],
        after_agent_callback=generate_memories_callback,
    )
    
    memory_service = VertexAiMemoryBankService(
        project=PROJECT_ID,
        location=LOCATION,
        agent_engine_id=MEMORY_BANK_ID,
    )
    session_service = InMemorySessionService()
    runner = adk.Runner(
        agent=root_agent,
        app_name=APP_NAME,
        session_service=session_service,
        memory_service=memory_service,
    )
    
    async def send_message(session_id: str, text: str) -> None:
        print(f"User: {text}")
        message = types.Content(role="user", parts=[types.Part(text=text)])
        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(f"Agent: {event.content.parts[0].text}")
    
    async def main() -> None:
        print("--- Session 1: share a preference ---")
        session = await session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID
        )
        await send_message(session.id, "Can you fix the temperature?")
        await send_message(session.id, "I'm comfortable at 71 degrees.")
    
        print("--- Session 2: recall the preference ---")
        session = await session_service.create_session(
            app_name=APP_NAME, user_id=USER_ID
        )
        await send_message(session.id, "Fix the temperature.")
    
        print("--- Memories stored in Memory Bank ---")
        client = agentplatform.Client(project=PROJECT_ID, location=LOCATION)
        memory_bank_name = (
            f"projects/{PROJECT_ID}/locations/{LOCATION}"
            f"/reasoningEngines/{MEMORY_BANK_ID}"
        )
        results = client.memory_banks.memories.retrieve(
            name=memory_bank_name,
            scope={"app_name": APP_NAME, "user_id": USER_ID},
        )
        for retrieved_memory in results.page:
            print(f"* {retrieved_memory.memory.fact}")
    
    if __name__ == "__main__":
        asyncio.run(main())
    
  3. Ejecuta la secuencia de comandos:

    python memory_agent/agent.py

    La devolución de llamada espera a que finalice la generación de memoria después de cada turno, por lo que la memoria está disponible cuando comienza la segunda sesión.

Verifica que el agente recuerde

Cuando la secuencia de comandos finaliza, imprime las conversaciones y la memoria almacenada en tu terminal. Compara ese resultado con los siguientes ejemplos para confirmar que el agente recordó la preferencia en una sesión nueva.

En la primera sesión, el agente no tiene recuerdos del usuario, por lo que solicita una temperatura:

--- Session 1: share a preference ---
User: Can you fix the temperature?
Agent: Sure. What temperature would you like?
User: I'm comfortable at 71 degrees.
Agent: Okay, I've set the temperature to 71 degrees.

En la segunda sesión, el agente recupera la memoria de Memory Bank y establece la temperatura en 71 grados sin preguntar. La memoria almacenada aparece al final del resultado:

--- Session 2: recall the preference ---
User: Fix the temperature.
Agent: Okay, I've set the temperature to 71 degrees, as you prefer.
--- Memories stored in Memory Bank ---
* I like the temperature to be 71 degrees.

La redacción de las respuestas y las memorias del agente varía según los modelos que usan el agente y el banco de memoria.

Opcional: Chatea con tu agente en la Web del ADK

ADK Web es una interfaz basada en el navegador para probar agentes durante el desarrollo.

  1. En la misma sesión de terminal, desde el directorio que contiene el directorio memory_agent, ejecuta el siguiente comando:

    adk web --memory_service_uri=agentengine://$MEMORY_BANK_ID memory_agent
  2. En tu navegador, abre http://localhost:8000?userId=quickstart_user.

    El parámetro de consulta userId coincide con el ID de usuario de la secuencia de comandos, por lo que el agente puede recuperar la memoria que creó la secuencia de comandos.

  3. Envía el mensaje Fix the temperature. y confirma que el agente establezca la temperatura en 21 grados sin preguntar. El agente usa la preferencia que la secuencia de comandos almacenó en Ejecuta un agente con memoria habilitada.

  4. Para detener ADK Web, presiona Control + C en la terminal.

Realiza una limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos que usaste en esta página, puedes borrar el proyecto de Google Cloud. De lo contrario, borra los recursos individuales:

  1. Crea un archivo llamado clean_up.py con el siguiente código:

    import os
    
    import agentplatform
    
    project = os.environ["GOOGLE_CLOUD_PROJECT"]
    location = os.environ["GOOGLE_CLOUD_LOCATION"]
    memory_bank_id = os.environ["MEMORY_BANK_ID"]
    
    client = agentplatform.Client(project=project, location=location)
    client.memory_banks.delete(
        name=f"projects/{project}/locations/{location}/reasoningEngines/{memory_bank_id}",
        force=True,
    )
    
  2. Ejecuta la secuencia de comandos para borrar la instancia de Memory Bank:

    python clean_up.py
  3. Borra los archivos locales que creaste:

    rm -r memory_agent create_memory_bank.py clean_up.py

¿Qué sigue?

Guía de inicio rápido

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

Guía

Elige devoluciones de llamada, herramientas y entornos de ejecución para el ADK.

Guía

Aprende a generar recuerdos en Memory Bank.

Guía

Obtén más información para configurar Memory Bank.