Patrón de agente de ADK con memoria y MCP

1. Qué aprenderás

Te damos la bienvenida a la clase magistral del ADK: Tu recorrido por los sistemas multiagente

Estás a punto de ingresar al emocionante mundo de los agentes de IA. Olvídate de los chatbots simples que solo responden preguntas. Nos adentraremos en el Agent Development Kit (ADK) para crear sistemas autónomos y sofisticados que puedan razonar, planificar y usar herramientas para realizar tareas complejas.

Todo este codelab será un recorrido práctico, este 1 repositorio de GitHub que contiene todo el código y los ejemplos para nuestras sesiones. repositorio de github

Al final de este instructivo, podrás hacer lo siguiente:

• Crear tu primer agente de IA: Pasar de cero a un agente completamente funcional que pueda comprender las necesidades de un usuario, usar herramientas como la Búsqueda de Google y generar respuestas detalladas y útiles
• Construir sistemas multiagente: Aprender el patrón "Agente como herramienta", un concepto revolucionario en el que los agentes delegan tareas a otros agentes especializados, lo que crea un equipo de expertos en IA que trabajan juntos
• Organizar flujos de trabajo complejos: Ir más allá de la delegación simple y dominar patrones avanzados como routers, cadenas secuenciales, bucles y ejecución paralela para crear aplicaciones sólidas, eficientes e inteligentes que puedan controlar casi cualquier solicitud
• Dar memoria a tus agentes: Comprender el rol fundamental de la memoria conversacional, lo que permite que tus agentes controlen preguntas de seguimiento, aprendan de los comentarios y administren tareas de varios pasos sin problemas
• Conectarse con MCP: Conéctate con la caja de herramientas de MCP.

¡Comencemos! 🚀

2. Configuración: Obtén tu clave de API

Configuración de la clave de API de Google AI Studio

Este codelab se ejecuta por completo en una clave de API gratuita de Google AI Studio. No se requiere ningún proyecto de Google Cloud, cuenta de facturación ni créditos. Cada sesión, incluida la memoria (sesión 6) y el MCP (sesión 7), se ejecuta de forma local en tu clave. Cada alumno usa su propia clave, por lo que la cuota de la API es por persona y no se comparte.

Qué necesitarás:

• Python 3.9 o versiones posteriores (python3 --version para verificar)
• Una Cuenta de Google (para crear la clave de AI Studio)
• Una terminal: funciona tu máquina local o Cloud Shell
• Aprox. 10 minutos

Para potenciar nuestros agentes de IA, necesitamos una clave de API de Gemini de Google AI Studio. Esta es la forma más rápida de comenzar.

Paso 1: Obtén tu clave de API de Gemini de AI Studio (1 min)

1. Abre https://aistudio.google.com/app/apikey en una pestaña nueva del navegador.
2. Accede con tu Cuenta de Google.
3. Haz clic en "Crear clave de API" (en la esquina superior derecha).
4. Se abrirá un diálogo con un menú desplegable del proyecto:

• Si ya tienes un proyecto de Google creado anteriormente: Selecciónalo y haz clic en "Crear clave de API en un proyecto existente"
• Si NO está en la lista: Haz clic en "Crear proyecto".

5. Copia la clave de API que aparece. Comienza con AIza... y tiene aproximadamente 40 caracteres.

✏️ Pégala en un lugar seguro , la necesitarás en el paso 4 a continuación.

Trata la clave de API como una contraseña. No la pegues en chats públicos, capturas de pantalla ni la confirmes en un repositorio público de GitHub.

Paso 2: Clona el repositorio (1 min)

👉💻 Abre tu terminal (o Cloud Shell) y clona el repositorio del instructivo:

git clone https://github.com/cuppibla/adk_tutorial.git
cd ~/adk_tutorial

Paso 3: Crea el entorno virtual y, luego, instala las dependencias

👉💻 Crea y activa un entorno virtual llamado .adk_env y, luego, instala las dependencias:

python3 -m venv .adk_env
source .adk_env/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Deberías ver (.adk_env) al comienzo de tu mensaje de terminal.

Paso 4: 🔥 IMPORTANTE: Agrega tu clave de API

⚠️ No omitas este paso. Crea un archivo .env en la raíz de la carpeta adk_tutorial. Este archivo potencia cada sesión de este codelab: las sesiones web del ADK (1 a 5) y las sesiones de memoria y MCP de la línea de comandos (6 a 7) lo leen automáticamente.

👉💻 Crea el archivo .env con tu clave (reemplaza your_actual_api_key_here por la clave del paso 1):

cat > .env <<'EOF'
GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here
EOF

Tu ~/adk_tutorial/.env ahora debería contener lo siguiente:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=your_actual_api_key_here

🚨 CRÍTICO: Reemplaza your_actual_api_key_here por tu clave de API real del paso 1 (comienza con AIza...).

⚠️ Asegúrate de que GOOGLE_GENAI_USE_VERTEXAI esté configurado como FALSE. Esto le indica al ADK que se autentique con tu clave de API de Google AI Studio en lugar de Vertex AI.

✅ Punto de control: Tienes un archivo .env en ~/adk_tutorial/.env que contiene tu clave AIza... y el mensaje de tu terminal muestra (.adk_env). Todo listo para crear agentes.

3. Sesión 1: Tu primer agente en la Web del ADK

Para abrir la Web del ADK, ejecuta lo siguiente:

cd ~/adk_tutorial
source .adk_env/bin/activate
adk web

Después de ejecutar los comandos, deberías ver un resultado en tu terminal que indica que se inició el servidor web del ADK, similar a este:

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://localhost:8000.                         |
+-----------------------------------------------------------------------------+


INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

👉 A continuación, abre tu navegador en http://localhost:8000 para acceder a la IU de desarrollo del ADK.

¿Se ejecuta en Cloud Shell en lugar de hacerlo de forma local? Haz clic en el ícono de vista previa en la Web en la barra de herramientas de Cloud Shell (por lo general, en la esquina superior derecha), selecciona Cambiar puerto, configura el puerto en 8000 y haz clic en "Cambiar y obtener vista previa". Cloud Shell abrirá la IU de desarrollo del ADK en una pestaña nueva del navegador.

👉 Se completó el ritual de invocación y el agente ahora se está ejecutando. La IU de desarrollo del ADK en tu navegador es tu conexión directa con el Familiar.

Elige tu primer agente En el menú desplegable de la parte superior de la IU, elige a_single_agent.

Puedes seleccionar a_single_agent aquí:

Puedes ver el seguimiento aquí:

👉 Prompt de prueba:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art.

4. Sesión 2: Agente de flujo de trabajo: Agente secuencial, agente paralelo y agente en bucle

Abre la IU web del ADK siguiendo los pasos de la sesión 1.

Parallel Agent

Elige el agente de flujo de trabajo paralelo En el menú desplegable de la parte superior de la IU, elige b2_parallel_agent.

👉 Prompt de prueba:

Plan my trip to San Francisco, I want to find some good concert, restaurant and museum.

Puedes seleccionar b2_parallel_agent aquí:

Puedes ver el seguimiento aquí:

Sequential Agent

Elige el agente de flujo de trabajo secuencial En el menú desplegable de la parte superior de la IU, elige b1_sequential_agent.

👉 Prompt de prueba:

Find a good sushi near Standford and tell me how to get there.

Puedes seleccionar b1_sequential_agent aquí:

Puedes ver el seguimiento aquí:

Loop Agent

Elige el agente de flujo de trabajo en bucle En el menú desplegable de la parte superior de la IU, elige b3_loop_agent.

👉 Prompt de prueba:

Plan a trip from Sunnyvale to San Francisco today.

Puedes seleccionar b3_loop_agent aquí:

Puedes ver el seguimiento aquí:

5. Sesión 3: Agente personalizado

Abre la IU web del ADK siguiendo los pasos de la sesión 1.

Una vez que se abra la IU web del ADK, elige c_custom_agent en el menú desplegable.

👉 Prompt de prueba:

Plan a trip from Sunnyvale to San Francisco this weekend, I love food and art. Make sure within budget of 100 dollars.

Puedes seleccionar c_custom_agent aquí:

Puedes ver el seguimiento aquí:

6. Sesión 4: Patrón de orquestador: Agente de enrutamiento

Abre la IU web del ADK siguiendo los pasos de la sesión 1.

Una vez que se abra la IU web del ADK, elige d_routing_agent en el menú desplegable.

👉 Prompt de prueba:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Puedes seleccionar d_routing_agent aquí:

Puedes ver el seguimiento aquí:

7. Sesión 5: Agente como herramienta

Abre la IU web del ADK siguiendo los pasos de la sesión 1.

Una vez que se abra la IU web del ADK, elige e_agent_as_tool en el menú desplegable.

👉 Prompt de prueba:

Plan a trip from Sunnyvale to San Francisco this weekend, I love concert, restaurant and museum.

Puedes seleccionar e_agent_as_tool aquí:

Puedes ver el seguimiento aquí:

8. Sesión 6: Agente con memoria a largo plazo

Se ejecuta por completo de forma local. En esta sesión, se almacena la memoria de conversación en una base de datos SQLite local (en ~/.adk/), por lo que tus preferencias persisten en los reinicios sin necesidad de Google Cloud, facturación ni créditos. El agente lee tu clave de AI Studio desde el ~/adk_tutorial/.env que creaste en la configuración.

👉💻 Para probar tu memoria a largo plazo, ve a la carpeta y usa el ejecutor para potenciar el agente:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Prompt de prueba:

I like Art and Italian food.

Luego, presiona Ctrl+C para finalizar la sesión. Reinicia la sesión:

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/f_agent_with_memory
python main.py

👉 Prompt de prueba:

Plan a trip to San Francisco based on my preference.

✅ El agente debe recordar "Arte y comida italiana" de la ejecución anterior. Esa es la memoria a largo plazo que funciona en todas las sesiones.

9. Sesión 7: Potencia tu agente con MCP

Se ejecuta por completo de forma local. En esta sesión, se inicia un servidor de MCP Toolbox local que lee una base de datos SQLite local (destinations.db). No se requiere Google Cloud, facturación ni créditos. La única descarga externa es el objeto binario de MCP Toolbox de código abierto.

Paso 1: Prepara la base de datos local

👉💻 Desde la raíz del repositorio, crea la base de datos de muestra:

cd ~/adk_tutorial
source .adk_env/bin/activate
chmod +x setup_trip_database.py
./setup_trip_database.py

Esto crea destinations.db en ~/adk_tutorial/.

⚠️ La base de datos de muestra solo contiene cuatro ciudades: París, Roma, Nueva York y Tokio (tipos de atracciones: Monumento, Museo, Parque). Los prompts que hacen referencia a otras ciudades (p.ej., San Francisco o Sunnyvale) mostrarán correctamente ningún resultado, ya que esas filas no existen. Usa las cuatro ciudades anteriores cuando pruebes esta sesión.

Paso 2: Instala y ejecuta el servidor de MCP Toolbox

👉💻 Descarga el objeto binario de MCP Toolbox para tu sistema operativo:

cd ~/adk_tutorial/mcp_tool_box
export VERSION=0.16.0

# Choose the line that matches your machine:
export OS=linux/amd64      # Cloud Shell or Linux (x86_64)
# export OS=darwin/arm64   # macOS Apple Silicon (M1/M2/M3)
# export OS=darwin/amd64   # macOS Intel

curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/$OS/toolbox

una vez que finalice la descarga, ejecuta

chmod +x toolbox

¿No sabes qué Mac tienes? Ejecuta uname -m (arm64 = Apple Silicon, x86_64 = Intel). En Windows, descarga .../windows/amd64/toolbox.exe y ejecútalo desde PowerShell.

Paso 3

En una terminal , ejecuta el siguiente comando (déjalo en ejecución; el agente se conecta a él en http://127.0.0.1:7001):

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/mcp_tool_box
./toolbox --tools-file "trip_tools.yaml" --port 7001

En otra terminal , ejecuta el siguiente comando.

cd ~/adk_tutorial
source .adk_env/bin/activate
cd ~/adk_tutorial/g_agents_mcp
python main.py

👉 Prompts de prueba (usa las ciudades que existen en la base de datos de muestra: París, Roma, Nueva York o Tokio):

What are the top-rated things to do in Tokyo?

Show me the museums in Rome.

What can I do in New York for under 25 dollars?

Solución de problemas de la sesión 7

• "Se rechazó la conexión" o el agente no encuentra herramientas: El servidor de Toolbox en la primera terminal no se está ejecutando. Reinícialo y confirma que está escuchando en el puerto 7001.
• Cada consulta muestra resultados vacíos: Confirma que ejecutaste el paso 1 para que exista ~/adk_tutorial/destinations.db y que tu prompt use una de las cuatro ciudades (París, Roma, Nueva York, Tokio).
• toolbox: cannot execute binary file en macOS: Descargaste la compilación de Linux. Vuelve a ejecutar el paso 2 con OS=darwin/arm64 (Apple Silicon) o OS=darwin/amd64 (Intel).