Curso intensivo sobre el ADK: De principiante a experto

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 enfocamos en la Agent Development Kit (ADK) para crear sistemas autónomos sofisticados que puedan razonar, planificar y usar herramientas para completar tareas complejas.

Todo este codelab principal será un recorrido práctico, y te guiaré por 2 notebooks de Colab principales que contienen todo el código y los ejemplos para nuestras sesiones. Colab 1: Herramientas y memoria, Colab 2: MultiAgents

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

• Crea tu primer agente de IA: Pasa 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.
• Master Custom Tools: Libera el verdadero potencial de los agentes conectándolos a tus propias funciones y APIs personalizadas. Le enseñarás a tu agente a recuperar datos en tiempo real, como pronósticos del clima en vivo.
• Construye sistemas multiagente: Aprende 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 en conjunto.
• Orquesta flujos de trabajo complejos: Ve más allá de la delegación simple y domina patrones avanzados como Routers, Sequential Chains, Loops y Parallel Execution para crear aplicaciones sólidas, eficientes e inteligentes que puedan controlar casi cualquier solicitud.
• Cómo darles memoria a tus agentes: Comprende el papel fundamental de la memoria conversacional, que permite que tus agentes manejen preguntas de seguimiento, aprendan de los comentarios y administren tareas de varios pasos sin problemas.

Comencemos. 🚀

2. Configura la clave de API de GCP y Gemini

Cómo configurar tu proyecto de GCP y la clave de API de Gemini

Para potenciar nuestros agentes de IA, necesitamos dos cosas: un proyecto de Google Cloud que proporcione la base y una clave de API de Gemini para acceder a los potentes modelos de Google.

Paso 1: Habilita la cuenta de facturación

• Reclama tu cuenta de facturación con un crédito de USD 5, ya que lo necesitarás para la implementación. Asegúrate de que sea tu cuenta de Gmail.

No se requiere tarjeta de crédito ni pago: Recibirás USD 5 en créditos gratis. Solo te llevará menos de 2 minutos. Ingresa tu nombre y acepta los créditos.

Paso 2: Crea un proyecto de GCP nuevo

• Ve a la consola de Google Cloud y crea un proyecto nuevo.

• Ve a la consola de Google Cloud y crea un proyecto nuevo.
• Abre el panel izquierdo, haz clic en Billing y verifica si la cuenta de facturación está vinculada a esta cuenta de GCP.

Si ves esta página, marca la casilla de verificación manage billing account, elige la prueba de Google Cloud One y vincúlala.

Paso 3: Genera tu clave de API de Gemini

Antes de proteger la llave, debes tener una.

• Navega a Google AI Studio : https://aistudio.google.com/
• Accede con tu cuenta de Gmail.
• Haz clic en el botón "Obtener clave de API", que suele encontrarse en el panel de navegación de la izquierda o en la esquina superior derecha.
• En el diálogo "Claves de API", haz clic en "Crear clave de API en un proyecto nuevo".
• Elige el proyecto nuevo que creaste y que tiene configurada la cuenta de facturación.
• Se generará una nueva clave de API para ti. Copia esta clave de inmediato y guárdala en un lugar seguro de forma temporal (como un administrador de contraseñas o una nota segura). Este es el valor que usarás en los siguientes pasos.

3. Sesión 1: Tu primer agente con Runner

Comencemos con los conceptos básicos. Aquí creamos nuestro primer agente simple, el day_trip_agent. El propósito de este agente es generar un itinerario de viaje de un día completo basado en la solicitud de un usuario, incluidas las consideraciones de presupuesto. En este ejemplo, se presentan los tres componentes principales de cualquier interacción del agente en el ADK:

• Agente: Es el cerebro principal de la operación. Se define por sus instrucciones (su personalidad y misión), el modelo de IA que usa (como Gemini) y las herramientas a las que puede acceder.
• Sesión: Es la memoria de la conversación. Almacena el historial de interacciones (mensajes del usuario y respuestas del agente), lo que permite un diálogo continuo.
• Runner: Es el motor que ejecuta la tarea. Toma el agente y la sesión, procesa la nueva consulta del usuario y coordina los pasos para generar una respuesta.

➡️ Dónde encontrarlo en el notebook

👉 Esto corresponde a las celdas de Parte 1: Tu primer agente: El Genio de los viajes de un día 🧞.🌟

• Definición del agente: Busca la función create_day_trip_agent(). Aquí es donde se define el agente. Observa la cadena de instrucciones detallada: esta es la instrucción que le indica al agente cómo debe comportarse. También le proporcionamos su primera herramienta: la Búsqueda de Google.
• Función auxiliar: Aquí se define la función auxiliar run_agent_query(). Usaremos esta utilidad en todo el notebook para simplificar la ejecución de consultas.
• Ejecución de prueba: La función run_day_trip_genie() simula a un usuario que solicita una excursión de un día "económica" y "relajante". El agente usa sus instrucciones y la herramienta de Búsqueda de Google para encontrar ubicaciones adecuadas y crear un itinerario con formato de Markdown.

➡️ Acción: Examina la instrucción del mensaje para day_trip_agent. Observa cómo la solicitud de un viaje "económico" en la búsqueda de prueba se relaciona directamente con el lineamiento del agente de ser "consciente del presupuesto".

4. Sesión 2: Herramientas personalizadas 🛠️

Si bien la Búsqueda de Google es potente, el verdadero potencial de los agentes de IA se libera cuando los conectas a tus propias fuentes de datos, APIs o lógica personalizada únicas. En esta sección, crearemos una herramienta personalizada a partir de una función de Python simple.

La parte más importante de una herramienta de función es su docstring. El ADK analiza automáticamente la cadena de documentación para comprender qué hace la herramienta, qué parámetros acepta (Args) y qué devuelve (Returns). El modelo de lenguaje grande (LLM) lee esta descripción para decidir cuándo y cómo usar la herramienta.

➡️ Dónde encontrarlo en el notebook

👉 Esto corresponde a las celdas de 2.1 La herramienta Simple FunctionTool: Cómo llamar a una API de clima en tiempo real. 🌟

• Definición de la herramienta: La función get_live_weather_forecast(location: str) es el núcleo de nuestra herramienta personalizada. Toma el nombre de una ciudad, llama a la API pública del Servicio Meteorológico Nacional y devuelve un diccionario con la temperatura y el pronóstico.
• Definición del agente: Se crea el agente weather_agent y se lo equipa con nuestra nueva herramienta pasando tools=[get_live_weather_forecast] durante su inicialización. Las instrucciones del agente le indican explícitamente que use esta herramienta antes de sugerir actividades al aire libre.
• Ejecución de prueba: La búsqueda "Quiero ir de excursión cerca del lago Tahoe. ¿Cómo está el clima?" activa directamente al agente para que use la herramienta get_live_weather_forecast porque sus instrucciones lo requieren.

➡️ Acción: Lee la cadena de documentación de la función get_live_weather_forecast y la instrucción para weather_agent. Ten en cuenta la relación directa entre ellos.

5. Sesión 3: Agent-as-a-Tool 🧑‍🍳

¿Por qué crear un agente monolítico único cuando puedes crear un equipo de especialistas? El patrón Agent-as-a-Tool es una forma eficaz de crear sistemas complejos en los que un agente principal, a menudo llamado orquestador o router, delega tareas a otros agentes más enfocados.

Este patrón te permite crear agentes modulares y reutilizables. Por ejemplo, puedes tener un agente experto en consultas de bases de datos, otro experto en escritura creativa y un tercero que actúe como un conserje amigable. El trabajo del orquestador es comprender la solicitud del usuario y dirigirla al especialista correcto.

➡️ Dónde encontrarlo en el notebook

👉 Esto corresponde a las celdas de 2.2 El agente como herramienta: Consultar a un especialista 🧑‍🍳.🌟

En este ejemplo, se compila un sistema de agentes sofisticado y de varias capas:

• Los especialistas:
  • food_critic_agent: Es un agente altamente especializado que solo proporciona sugerencias de restaurantes.
  • db_agent: Es un agente simulado que pretende consultar una base de datos para obtener información sobre hoteles.
  • concierge_agent: Es un agente de nivel medio que actúa como un conserje cortés. Fundamentalmente, tiene food_critic_agent como su propia herramienta.
• El organizador (trip_data_concierge_agent): Es el agente de nivel superior con el que interactúa el usuario. Sus instrucciones lo convierten en un "planificador de viajes maestro", y se le proporcionan dos herramientas que llaman a los otros agentes:
  • call_db_agent: Es una función que llama a db_agent.
  • call_concierge_agent: Es una función que llama a concierge_agent.
• El flujo: La ejecución de prueba en run_trip_data_concierge() demuestra la cadena de delegación completa.
  • Un usuario le pide al orquestador un hotel y un restaurante cercano.
  • Las instrucciones del orquestador le indican que primero use la herramienta call_db_agent para obtener datos de hoteles.
  • Luego, el orquestador usa la herramienta call_concierge_agent para obtener una recomendación.
  • El concierge_agent, al recibir la solicitud, usa su propia herramienta, el food_critic_agent, para obtener una idea de restaurante.

La respuesta del crítico gastronómico se pasa al asistente, quien la formatea de manera cortés y la envía de vuelta al orquestador, quien finalmente se la presenta al usuario.

➡️ Acción: Realiza un seguimiento del flujo de ejecución en la ejecución de prueba en run_trip_data_concierge(). Observa cómo las impresiones de TOOL CALLED muestran la cadena de delegación desde el orquestador hasta los especialistas. Esta es una cadena de mando secuencial.

6. Sesión 4: Memoria del agente 🧠

Un agente verdaderamente inteligente debe hacer más que solo responder consultas únicas. Debe recordar la conversación, comprender el contexto y adaptarse a los comentarios. Esto se logra a través de una administración adecuada de las sesiones. Piensa en un "agente de bucle" como un agente que participa en un bucle conversacional continuo, potenciado por su memoria.

Cuando usas el mismo objeto de sesión para varias consultas secuenciales, el agente puede "ver" todo el historial de la conversación. Esto le permite responder preguntas de seguimiento, corregirse en función de los comentarios y planificar tareas de varios pasos.

➡️ Dónde encontrarlo en el notebook

👉 Esto corresponde a las celdas de Parte 3: Agente con memoria: el planificador adaptable 🗺️. 🌟

• Definición del agente: La función create_multi_day_trip_agent() define un agente diseñado para planificar un viaje de forma progresiva. Sus instrucciones enfatizan recordar el contexto, manejar los comentarios y planificar un día a la vez.

Escenario 3a: Agente CON memoria (✅)

Esta prueba se ejecuta en la función run_adaptive_memory_demonstration().

• Se crea un solo trip_session y se reutiliza durante tres turnos consecutivos.
• Turno 1: El usuario inicia un plan de viaje de 2 días.
• Turno 2: El usuario da comentarios ("No soy muy fan de los castillos"). Dado que el agente tiene la memoria del turno 1, comprende qué parte del plan debe cambiar y proporciona una alternativa.
• Turno 3: El usuario confirma el cambio y pregunta cuál es el siguiente paso. El agente recuerda todo y continúa planificando el día 2.

Situación 3b: Agente SIN memoria (❌)

Esta prueba se ejecuta en la función run_memory_failure_demonstration().

Esto demuestra la importancia crítica de la administración de sesiones al cometer un error a propósito. Se crea una sesión nueva para cada turno.

• Turn 1: El usuario inicia el viaje en session_one. El agente responde correctamente.
• Turn 2: El usuario pide que se planifique el día 2, pero la búsqueda se envía en una sesión_dos completamente nueva. Como esta nueva sesión no tiene historial, el agente se confunde. ¡Tiene amnesia! No sabe qué viaje se está planificando.

Acción: Compara las respuestas del agente en run_adaptive_memory_demonstration() y run_memory_failure_demonstration(). Este es el concepto más importante del notebook: Una conversación continua requiere una sesión continua.

7. Sesión 5: El agente de Router 🚏

Un solo agente no puede hacer mucho. Para abordar las solicitudes de los usuarios verdaderamente complejas, necesitamos un equipo de agentes especializados. Pero, ¿cómo sabemos qué agente usar para una consulta determinada? Ahí es donde entra en juego el agente de Router.

El agente de Router actúa como un agente "principal" o un distribuidor. Su único propósito es analizar una búsqueda entrante del usuario y decidir qué agente especializado (o flujo de trabajo de agentes) es el más adecuado para el trabajo. No responde la consulta en sí, sino que simplemente la enruta al agente de nivel inferior correcto.

Por ejemplo, una búsqueda sobre "el mejor sushi" debe dirigirse a un foodie_agent, mientras que una pregunta sobre "conciertos este fin de semana" debe ser atendida por un weekend_guide_agent.

➡️ Dónde encontrarlo en el notebook:

👉 Este concepto es fundamental para todo el notebook, pero se presenta por primera vez en la Parte 1: Multi-Agent Mayhem - Flujos de trabajo secuenciales 🧠→🤖→🤖 🌟

• Definiciones de agentes: La celda de código define varios agentes especialistas (day_trip_agent, foodie_agent, transportation_agent) y, lo que es más importante, el agente router_agent. Presta mucha atención a la instrucción del router_agent, ya que se le indica explícitamente que solo devuelva el nombre del mejor agente para el trabajo.
• Lógica de ejecución: La función run_sequential_app muestra cómo llamar primero al router_agent para obtener una decisión (chosen_route) y, luego, usar esa decisión en un bloque if/elif para ejecutar el agente especializado adecuado.

8. Sesión 6: SequentialAgent ⛓️

Algunas tareas requieren varios pasos en un orden específico. Por ejemplo, "Busca el mejor sushi en Palo Alto y, luego, dime cómo llegar allí". Este es un proceso de dos pasos: primero, busca el restaurante y, luego, obtén las indicaciones para llegar.

El ADK proporciona una forma clara y potente de administrar esto con SequentialAgent. Este es un agente de flujo de trabajo especial que ejecuta una lista de subagentes en un orden predefinido.

La magia radica en el estado compartido. El resultado de un agente en la secuencia se puede guardar automáticamente en un diccionario de estado compartido y, luego, usarse como entrada para el siguiente agente, lo que elimina la necesidad de código manual complejo para pasar información entre los pasos.

➡️ Dónde encontrarlo en el notebook:

👉 Este tema se aborda en la Parte 2 (La forma del ADK): Caos multiagente con SequentialAgent 🧠→⛓️→🤖. 🌟

• Refactorización del agente: En la primera celda de código de esta sección, observa los cambios clave en foodie_agent y transportation_agent:
  • foodie_agent ahora tiene un output_key="destination". Esto le indica al ADK que guarde su respuesta final en una variable llamada destination en el estado compartido.
  • Ahora, transportation_agent tiene el marcador de posición {destination} en su instrucción. El ADK inyecta automáticamente el valor del estado compartido en este marcador de posición.
• Definición del flujo de trabajo: El find_and_navigate_agent se define como un SequentialAgent, con sus sub_agents establecidos en [foodie_agent, transportation_agent], lo que garantiza que se ejecuten en ese orden exacto.
• Ejecución simplificada: Observa la función run_sequential_app en esta sección. ¡Se quitó la lógica compleja de if/elif! Ahora, el find_and_navigate_agent se trata como una sola unidad invocable, y el ADK controla los pasos secuenciales internos de forma automática.

9. Sesión 7: LoopAgent 🔁

No todos los problemas tienen una solución directa y única. A veces, debemos proponer una solución, criticarla y perfeccionarla hasta que cumpla con una restricción específica.

Para ello, el ADK ofrece LoopAgent. Este agente de flujo de trabajo ejecuta repetidamente una secuencia de subagentes hasta que se cumple una condición específica. Esto es ideal para crear agentes "perfeccionistas" que puedan planificar, criticar y mejorar su propio trabajo.

En el diagrama, se muestra que Planner Agent crea un plan primero. Luego, ingresamos el LoopAgent. El Critic Agent verifica el plan. Si es defectuoso, Refiner Agent crea una versión nueva y se repite el bucle. Si el plan es bueno, Refiner Agent llama a la herramienta exit_loop y se devuelve el plan final validado.

➡️ Dónde encontrarlo en el notebook:

👉 Esto se explica en Iterative Ideas with LoopAgent 🧠→🔁→🤖. 🌟

• Los agentes principales: El flujo de trabajo usa planner_agent, critic_agent y refiner_agent.
• La definición del bucle: El refinement_loop se define como un LoopAgent que coordina el critic_agent, el refiner_agent y el sets max_iterations=3.
• La condición de salida: El bucle finaliza cuando critic_agent aprueba el plan, lo que lleva a refiner_agent a llamar a la herramienta personalizada exit_loop.

10. Sesión 8: ParallelAgent ⚡️

La eficiencia es clave. Si un usuario solicita varios fragmentos de información no relacionados a la vez, ejecutar estas búsquedas una por una sería lento.

El ParallelAgent es la solución. Este agente de flujo de trabajo ejecuta una lista de subagentes de forma simultánea. Una vez que se completan todas las tareas paralelas, se pueden recopilar sus resultados y sintetizarlos en una sola respuesta integral.

En este diagrama, se muestra el ParallelAgent que toma una sola búsqueda y bifurca el trabajo en tres pistas simultáneas. museum_finder, concert_finder y restaurant_finder se ejecutan al mismo tiempo. Una vez que los tres terminan, sus resultados individuales (guardados en el estado compartido) se unen y se pasan al agente de síntesis final, que los combina en una sola respuesta.

➡️ Dónde encontrarlo en el notebook:

👉 Este flujo de trabajo se detalla en la sección Potencia paralela con ParallelAgent 🧠→⚡️→🤖🤖🤖. 🌟

• Agentes especialistas: Se definen tres agentes especialistas, cada uno con una output_key única (p.ej., museum_result).
• El flujo de trabajo paralelo: El parallel_research_agent se define como un ParallelAgent, con los tres agentes de búsqueda que se indican como sus sub_agents.
• El paso de síntesis: Después del paso paralelo, un agente de síntesis final recopila todos los hallazgos del estado compartido con marcadores de posición ({museum_result}, {concert_result}, etc.) para dar formato a un resumen ordenado.

11. Apéndice: ADK Web - 🍎 Para Mac/Linux

En esta guía, se explica cómo configurar y ejecutar el agente de planificación de viajes de un día del ADK en tu máquina local.

Requisitos previos

• Python 3.8 o una versión posterior
  • Python 3.9 y versiones posteriores: Instala google-adk==1.5.0 (la versión más reciente con todas las funciones).
  • Python 3.8: Instala google-adk==0.3.0 (versión compatible)
• Clave de API de Google AI Studio
• Conexión a Internet

Paso 1: Clona el repositorio

Abre la terminal y ejecuta lo siguiente:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

Paso 2: Configura el entorno virtual y las dependencias

Opción A: Configuración automática (recomendada)

# Run the setup script
chmod +x setup_venv.sh
./setup_venv.sh

Opción B: Configuración manual

# Create virtual environment
python3 -m venv .adk_env

# Activate virtual environment
source .adk_env/bin/activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Paso 3: 🔥 IMPORTANTE: Crea variables de entorno

⚠️ No omitas este paso. Crea un archivo .env en el directorio agent/:

# Create the .env file
touch agent/.env

# Open it in your default text editor
open agent/.env

Agrega estas líneas al archivo:

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.

Paso 4: Activa el entorno virtual (si aún no está activo)

source .adk_env/bin/activate

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

Paso 5: Ejecuta la interfaz web del ADK

adk web

Paso 6: Abre tu navegador

1. Abre el navegador y ve a la URL que se muestra en la terminal (por lo general, http://localhost:8000).
2. En el menú desplegable de la esquina superior izquierda, selecciona agent.
3. Comienza a chatear con tu agente de planificación de viajes de un día.

Verás una conversación como la siguiente:

Cómo desactivar el entorno

Cuando termines de trabajar en el proyecto, haz lo siguiente:

deactivate

Este comando funciona de la misma manera en Mac/Linux y Windows. Verás que el prefijo (.adk_env) desaparece del mensaje de la terminal.

Solución de problemas en Mac

• No se encontró Python: Usa python3 en lugar de python
• Permiso denegado: Ejecuta chmod +x setup_venv.sh antes de ejecutar la secuencia de comandos

12. Apéndice: ADK Web: 🪟 Para usuarios de Windows

En esta guía, se explica cómo configurar y ejecutar el agente de planificación de viajes de un día del ADK en tu máquina local.

Requisitos previos

• Python 3.8 o una versión posterior
  • Python 3.9 y versiones posteriores: Instala google-adk==1.5.0 (la versión más reciente con todas las funciones).
  • Python 3.8: Instala google-adk==0.3.0 (versión compatible)
• Clave de API de Google AI Studio
• Conexión a Internet

Paso 1: Clona el repositorio

Abre el símbolo del sistema o PowerShell y ejecuta lo siguiente:

git clone https://github.com/cuppibla/ADK_Basic.git
cd ADK_Basic

Paso 2: Configura el entorno virtual y las dependencias

Opción A: Configuración automática (recomendada)

# Run the setup script in Command Prompt
setup_venv.bat

Opción B: Configuración manual

Para el símbolo del sistema:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Para PowerShell:

# Create virtual environment
python -m venv .adk_env

# Activate virtual environment
.adk_env\Scripts\Activate.ps1

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

Paso 3: 🔥 IMPORTANTE: Crea variables de entorno

⚠️ No omitas este paso. Crea un archivo .env en el directorio agent/:

# Create the .env file
type nul > agent\.env

# Open it in Notepad
notepad agent\.env

Agrega estas líneas al archivo:

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.

Paso 4: Activa el entorno virtual (si aún no está activo)

Símbolo del sistema:

.adk_env\Scripts\activate

PowerShell:

.adk_env\Scripts\Activate.ps1

Deberías ver (.adk_env) al comienzo de la instrucción.

Paso 5: Ejecuta la interfaz web del ADK

adk web

Paso 6: Abre tu navegador

1. Abre el navegador y ve a la URL que se muestra en la terminal (por lo general, http://localhost:8000).
2. En el menú desplegable de la esquina superior izquierda, selecciona agent.
3. Comienza a chatear con tu agente de planificación de viajes de un día.

Solución de problemas de Windows

• Error de política de ejecución de PowerShell: Ejecuta Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Verás una conversación como la siguiente:

Cómo desactivar el entorno

Cuando termines de trabajar en el proyecto, haz lo siguiente:

deactivate

Este comando funciona de la misma manera en Mac/Linux y Windows. Verás que el prefijo (.adk_env) desaparece del mensaje de la terminal.