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
- 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.- Configura un entorno de desarrollo de Python.
-
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
En la terminal, instala el ADK y el SDK de Agent Platform:
pip install --upgrade "google-adk[gcp]" "google-cloud-agentplatform>=2.0.1"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=globalReemplaza 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
globalpor 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
Crea un archivo llamado
create_memory_bank.pycon 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])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.
Confirma que la variable contenga el ID de la instancia:
echo $MEMORY_BANK_IDEl resultado es un ID, como
1234567890. Si el resultado está vacío o devuelve un error401o403, verifica tus roles obligatorios y ejecutagcloud auth application-default login. Si una instancia nueva deglobaldevuelve un error403transitorio 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:
Crea un directorio llamado
memory_agent:mkdir memory_agentCrea un archivo llamado
memory_agent/agent.pycon 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())Ejecuta la secuencia de comandos:
python memory_agent/agent.pyLa 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.
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_agentEn tu navegador, abre
http://localhost:8000?userId=quickstart_user.El parámetro de consulta
userIdcoincide 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.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.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:
Crea un archivo llamado
clean_up.pycon 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, )Ejecuta la secuencia de comandos para borrar la instancia de Memory Bank:
python clean_up.pyBorra los archivos locales que creaste:
rm -r memory_agent create_memory_bank.py clean_up.py
¿Qué sigue?
Guía de inicio rápido de la API de Memory Bank
Comienza a usar la API de Memory Bank para administrar las memorias a largo plazo.
Usa Memory Bank con el ADK
Elige devoluciones de llamada, herramientas y entornos de ejecución para el ADK.