内容
# Get started with Agent Development Kit (ADK)
> **⚡ Powered by aaronthewarrior**
> Repositorio base, adaptación práctica y curaduría técnica creada por [aaronthewarrior](https://github.com/aaron-the-warrior).
[](https://github.com/aaron-the-warrior)
[](https://adk.dev/)
[](https://aistudio.google.com/)
[](#prerrequisitos-y-configuración-del-entorno)
[](#prerrequisitos-y-configuración-del-entorno)
Guía completa y práctica paso a paso para aprender a diseñar, desarrollar y desplegar agentes inteligentes utilizando el **Agent Development Kit (ADK)** de Google. Esta guía combina los fundamentos de desarrollo de software tradicional para IA, uso de herramientas deterministas en Python (*Function Calling*), búsqueda en tiempo real (*Grounding*), integración con fuentes de datos mediante **Model Context Protocol (MCP)** y flujos multi-agente.
> [!TIP]
> El taller se realiza en **Windows PowerShell**. Cada comando incluye también su equivalente para **Linux / macOS (Bash)**. Si no puedes instalar nada, usa el [notebook de Google Colab](#plan-b-google-colab).
---
## 📑 Tabla de Contenidos
1. [Créditos y Cita de la Fuente Original](#créditos-y-cita-de-la-fuente-original)
2. [Conceptos Clave del Video Oficial](#conceptos-clave-del-video-oficial)
3. [Ecosistema y Flujo de Trabajo con ADK CLI (`adk.dev`)](#ecosistema-y-flujo-de-trabajo-con-adk-cli-adkdev)
4. [Arquitectura del Proyecto](#arquitectura-del-proyecto)
5. [Prerrequisitos y Configuración del Entorno](#prerrequisitos-y-configuración-del-entorno)
6. [Paso 1: Tu Primer Agente con ADK (`paso1_basic_agent`)](#paso-1-tu-primer-agente-con-adk-paso1_basic_agent)
7. [Paso 2: Herramientas de Python Nativas (`paso2_function_tools`)](#paso-2-herramientas-de-python-nativas-paso2_function_tools)
8. [Paso 3: Grounding con Búsqueda en Google (`paso3_builtin_tools`)](#paso-3-grounding-con-búsqueda-en-google-paso3_builtin_tools)
9. [Paso 4: Conexión de Datos y Servidores MCP (`paso4_mcp_database`)](#paso-4-conexión-de-datos-y-servidores-mcp-paso4_mcp_database)
10. [Paso 5: Orquestación Multi-Agente (`paso5_multi_agent`)](#paso-5-orquestación-multi-agente-paso5_multi_agent)
11. [Depuración e Inspección Visual con `adk web`](#depuración-e-inspección-visual-con-adk-web)
12. [Plan B: Google Colab](#plan-b-google-colab)
13. [Solución de Problemas](#solución-de-problemas)
14. [Recursos para Seguir Aprendiendo](#recursos-para-seguir-aprendiendo)
---
## 🎖️ Créditos y Cita de la Fuente Original
Este repositorio y material didáctico es un proyecto **Powered by [aaronthewarrior](https://github.com/aaron-the-warrior)**, creado para estructurar, traducir y llevar al plano práctico los conceptos presentados en las fuentes oficiales de Google Developers:
* **Autor y Curador:**
* Aarón Guerrero (**aaronthewarrior**) — [GitHub Profile](https://github.com/aaron-the-warrior)
* **Video Oficial:**
* *Título:* **Introducing Agent Development Kit**
* *Canal:* Google for Developers
* *Enlace:* [https://www.youtube.com/watch?v=zgrOwow_uTQ](https://www.youtube.com/watch?v=zgrOwow_uTQ)
* **Codelab Oficial:**
* *Título:* **Tools Make an Agent: From Zero to Assistant with ADK**
* *Plataforma:* Google Developers Codelabs / Cloud Run
* *Enlace:* [https://codelabs.developers.google.com/codelabs/cloud-run/tools-make-an-agent](https://codelabs.developers.google.com/codelabs/cloud-run/tools-make-an-agent)
* **Documentación Oficial y Guía de Inicio:**
* *Título:* **Python Quickstart - Agent Development Kit (ADK)**
* *Portal:* [https://adk.dev/get-started/python/](https://adk.dev/get-started/python/)
* *Portal Principal:* [https://adk.dev/](https://adk.dev/)
---
## 💡 Conceptos Clave del Video Oficial
En la presentación oficial del **Agent Development Kit**, el equipo de Google expone los pilares fundamentales que diferencian a ADK de otros frameworks:
1. **El desarrollo de agentes se siente como desarrollo de software estándar:**
En lugar de depender de cadenas de prompts extensas o formatos propietarios, los agentes se declaran con clases de Python estándar (`Agent`), firmas de funciones con tipos estáticos (`type hints`) y patrones de diseño familiares.
2. **Agnóstico al modelo y portable:**
Aunque está optimizado para la familia de modelos Gemini (en este taller usamos `gemini-3.8-flash`), la arquitectura de ADK permite intercambiar modelos y ejecutarse en cualquier infraestructura: máquina local, contenedores Docker, **Google Cloud Run** o **Vertex AI**.
3. **Capacidades Multimodales y Streaming Bidireccional en Tiempo Real:**
ADK cuenta con soporte nativo para streaming de audio y video de ultra baja latencia sobre WebSockets, sin necesidad de librerías intermedias de audio.
4. **Inspección de eventos lista para usar:**
Con una única instrucción de terminal (`adk web`), se levanta un servidor de depuración que expone la línea de tiempo completa: prompts enviados, decisión de invocación de herramientas (*tool call*), argumentos parseados y la respuesta estructurada final.
---
## 🛠️ Ecosistema y Flujo de Trabajo con ADK CLI (`adk.dev`)
De acuerdo con la guía oficial de [adk.dev/get-started/python/](https://adk.dev/get-started/python/), ADK introduce una convención estándar y herramientas de línea de comandos para agilizar el ciclo de vida del proyecto:
* **Convención `root_agent`:**
ADK busca por convención una variable llamada `root_agent` dentro de tu archivo `agent.py`. Este es el punto de entrada principal que utilizarán las utilidades CLI para ejecutar o inspeccionar tu agente.
* **Comandos esenciales de la CLI:**
* `adk create <nombre_agente>`: Inicializa un proyecto de agente con la estructura recomendada.
* `adk run <directorio_agente>`: Inicia un bucle de chat interactivo directamente en tu consola.
* `adk web`: Despliega la interfaz gráfica web en `http://localhost:8000` para probar e inspeccionar trazas.
> [!NOTE]
> El nombre de cada carpeta de agente **debe empezar con una letra** (por eso usamos `paso1_basic_agent` y no `01_basic_agent`); de lo contrario `adk run` rechaza el nombre de la aplicación.
---
## 🏛️ Arquitectura del Proyecto
El repositorio es modular, con pasos incrementales desde un agente básico hasta arquitecturas multi-agente con consulta a base de datos:
```text
get_started_with_agent_development_kit_adk/
├── README.md
├── get_started_with_agent_development_kit_adk.ipynb # Plan B: el taller completo en Google Colab
└── intro-adk-tools/
├── requirements.txt
├── .env.example
├── paso1_basic_agent/
│ ├── __init__.py
│ └── agent.py # Agente base y convención root_agent
├── paso2_function_tools/
│ ├── __init__.py
│ └── agent.py # Agente con herramientas de funciones Python nativas
├── paso3_builtin_tools/
│ ├── __init__.py
│ └── agent.py # Agente con Grounding de Google Search
├── paso4_mcp_database/
│ ├── __init__.py
│ ├── database.py # Base de datos SQLite de incidentes
│ └── agent.py # Agente con herramienta de consulta a la base de datos
├── paso4b_mcp_sqlite/
│ ├── __init__.py
│ ├── mcp_server.py # Servidor MCP propio sobre la base de datos
│ └── agent.py # Agente que consume el servidor MCP
└── paso5_multi_agent/
├── __init__.py
└── agent.py # Orquestador con agentes especialistas
```
---
## ⚙️ Prerrequisitos y Configuración del Entorno
### 1. Requisitos del Sistema
* **Python:** Versión 3.10 o superior instalada.
* **Git** para clonar el repositorio.
* **Clave de API de Gemini:** Obtenida gratuitamente en [Google AI Studio](https://aistudio.google.com/apikey).
> [!WARNING]
> La clave gratuita sirve para casi todo el taller. **Grounding con Google Search no está disponible en el nivel gratuito**, así que los pasos 3 y 5 necesitan una clave de un proyecto con [facturación habilitada](https://ai.google.dev/gemini-api/docs/billing) (los modelos Gemini 3.x incluyen 5,000 búsquedas gratis al mes).
#### En Windows (PowerShell):
```powershell
winget install Python.Python.3.12
winget install Git.Git
# Cierra y vuelve a abrir PowerShell
python --version
git --version
```
#### En Linux o macOS:
```bash
# Ubuntu / Debian
sudo apt update && sudo apt install -y python3 python3-venv python3-pip git
# macOS
brew install python git
```
### 2. Clonar el Repositorio y Crear el Entorno Virtual
#### En Windows (PowerShell):
```powershell
# 1. Clonar el repositorio (en una ruta corta, ver Solución de Problemas)
cd $HOME
git clone https://github.com/aaron-the-warrior/get_started_with_agent_development_kit_adk.git
cd get_started_with_agent_development_kit_adk\intro-adk-tools
# 2. Crear y activar entorno virtual
python -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
```
#### En Linux o macOS:
```bash
# 1. Clonar el repositorio
cd ~
git clone https://github.com/aaron-the-warrior/get_started_with_agent_development_kit_adk.git
cd get_started_with_agent_development_kit_adk/intro-adk-tools
# 2. Crear y activar entorno virtual
python3 -m venv .venv
source .venv/bin/activate
```
### 3. Instalación de Dependencias
El archivo `intro-adk-tools/requirements.txt` contiene:
```text
google-adk
mcp
python-dotenv
```
Instala las librerías requeridas (igual en PowerShell y Bash) y comprueba la CLI de ADK:
```bash
pip install -r requirements.txt
adk --version
```
### 4. Configuración de Variables de Entorno (`.env`)
Copia la plantilla `.env.example` a `.env` y coloca tu clave real:
#### En Windows (PowerShell):
```powershell
Copy-Item .env.example .env
notepad .env
```
#### En Linux o macOS:
```bash
cp .env.example .env
nano .env
```
Contenido del archivo `.env`:
```bash
GOOGLE_API_KEY="tu-api-key-aqui"
GOOGLE_GENAI_USE_VERTEXAI=FALSE
ADK_MODEL="gemini-3.8-flash"
```
> [!CAUTION]
> El archivo `.env` está en `.gitignore`: **nunca** subas tu API Key a GitHub.
> [!TIP]
> **Compatibilidad de Modelos:** El taller está configurado por defecto con `gemini-3.8-flash`. Si utilizas una clave gratuita o estándar de Google AI Studio y dicho modelo aún no está disponible en tu cuenta o región (error *404 Model Not Found*), puedes definir en tu `.env` un modelo público como `ADK_MODEL="gemini-2.5-flash"` o `ADK_MODEL="gemini-2.0-flash"` sin modificar nada del código de los pasos. También puedes usar `gemini-3.7-flash` o `gemini-3.5-flash-lite`. Consulta la [lista de modelos](https://ai.google.dev/gemini-api/docs/models).
---
## 🚀 Paso 1: Tu Primer Agente con ADK (`paso1_basic_agent`)
Siguiendo la convención descrita en `adk.dev`, definimos un `root_agent`. El modelo se indica con su nombre y ADK toma la API Key de la variable de entorno `GOOGLE_API_KEY`.
Archivo `paso1_basic_agent/agent.py`:
```python
import os
from dotenv import load_dotenv
from google.adk.agents import Agent
load_dotenv()
MODEL = os.getenv("ADK_MODEL", "gemini-3.8-flash")
# Definir el agente raíz (root_agent)
root_agent = Agent(
name="quantum_support_agent",
model=MODEL,
description="Asistente de soporte técnico e infraestructura de QuantumRoast.",
instruction="""
Eres el asistente técnico de operaciones de QuantumRoast.
Tu misión es brindar diagnósticos claros, directos y estructurados a los ingenieros
de guardia cuando reporten anomalías en los sistemas.
""",
)
```
Pruébalo interactivamente por consola con la CLI de ADK (igual en PowerShell y Bash):
```bash
adk run paso1_basic_agent
```
Mensaje de prueba (escribe `exit` para salir):
```text
Hola, se detectó una sobrecarga de memoria en el cluster principal. ¿Cuál es el primer paso?
```
---
## 🔧 Paso 2: Herramientas de Python Nativas (`paso2_function_tools`)
Los modelos de lenguaje pueden fallar realizando cálculos matemáticos o aplicando reglas rígidas de negocio. La forma correcta de resolver esto es mediante herramientas deterministas de Python: funciones tipadas pasadas directamente en la lista `tools`. ADK usa la firma con *type hints* y el *docstring* para describirle la herramienta al modelo.
Archivo `paso2_function_tools/agent.py`:
```python
import os
from dotenv import load_dotenv
from google.adk.agents import Agent
load_dotenv()
MODEL = os.getenv("ADK_MODEL", "gemini-3.8-flash")
# Función determinista en Python con type hints y docstring descriptivo
def calcular_severidad_incidente(usuarios_afectados: int, afecta_facturacion: bool, latencia_ms: float) -> dict:
"""Calcula de forma estricta la severidad técnica de un incidente y el tiempo máximo de SLA.
Args:
usuarios_afectados: Cantidad estimada de usuarios con errores.
afecta_facturacion: Verdadero si la pasarela de pagos o cobros está degradada.
latencia_ms: Latencia promedio actual en milisegundos.
"""
if afecta_facturacion or usuarios_afectados > 2000 or latencia_ms > 2500.0:
return {"severidad": "P0 - Bloqueante", "sla_minutos": 15, "escalar_inmediato": True}
elif usuarios_afectados > 300 or latencia_ms > 800.0:
return {"severidad": "P1 - Crítico", "sla_minutos": 60, "escalar_inmediato": True}
elif usuarios_afectados > 30:
return {"severidad": "P2 - Mayor", "sla_minutos": 240, "escalar_inmediato": False}
return {"severidad": "P3 - Menor", "sla_minutos": 1440, "escalar_inmediato": False}
root_agent = Agent(
name="triage_agent",
model=MODEL,
description="Agente clasificador y regulador de severidad de incidentes de software.",
instruction="""
Siempre que un usuario describa métricas o impacto de un problema, DEBES ejecutar
la herramienta calcular_severidad_incidente antes de emitir tu veredicto o plan de acción.
""",
tools=[calcular_severidad_incidente],
)
```
```bash
adk run paso2_function_tools
```
Mensaje de prueba:
```text
Tenemos 1500 usuarios que reciben HTTP 504, la latencia es de 3100ms y no hay afectación en pagos.
```
---
## 🌐 Paso 3: Grounding con Búsqueda en Google (`paso3_builtin_tools`)
Para responder sobre el estado de servicios externos, caídas de nubes públicas o vulnerabilidades recientes, conectamos la herramienta integrada de búsqueda en Google (`google_search`).
Archivo `paso3_builtin_tools/agent.py`:
```python
import os
from dotenv import load_dotenv
from google.adk.agents import Agent
from google.adk.tools import google_search
load_dotenv()
MODEL = os.getenv("ADK_MODEL", "gemini-3.8-flash")
root_agent = Agent(
name="research_agent",
model=MODEL,
description="Agente investigador de incidentes y estado de servicios en tiempo real.",
instruction="""
Eres un analista de incidentes externo. Usa la herramienta de búsqueda en Google
para verificar incidentes públicos, caídas de proveedores cloud o reportes de estado
técnico en tiempo real. Siempre referencia las fuentes encontradas.
""",
tools=[google_search],
)
```
```bash
adk run paso3_builtin_tools
```
Mensaje de prueba:
```text
¿Hay algún reporte reciente de fallas o interrupciones en los servicios de Google Cloud?
```
> [!NOTE]
> Las herramientas integradas como `google_search` no pueden combinarse con otras herramientas en el mismo agente. En el Paso 5 vemos cómo resolverlo con `AgentTool`.
> [!WARNING]
> Este paso requiere una API Key con facturación habilitada (Grounding con Google Search no está en el nivel gratuito).
---
## 🗄️ Paso 4: Conexión de Datos y Servidores MCP (`paso4_mcp_database`)
Siguiendo el Codelab de Google Cloud (*Tools Make an Agent*), los agentes requieren consultar sistemas de registro corporativos. Primero lo hacemos con una función de Python y después con el estándar **Model Context Protocol (MCP)**.
### 1. Inicialización de la base de datos local (`paso4_mcp_database/database.py`)
```python
import sqlite3
from pathlib import Path
# Ruta absoluta junto a este archivo, para que funcione desde cualquier directorio
DB_PATH = Path(__file__).resolve().parent / "incidentes.db"
def inicializar_base_datos():
conexion = sqlite3.connect(DB_PATH)
cursor = conexion.cursor()
cursor.execute("""
CREATE TABLE IF NOT EXISTS historial_incidentes (
id TEXT PRIMARY KEY,
servicio TEXT,
estado TEXT,
solucion_aplicada TEXT
)
""")
cursor.execute("DELETE FROM historial_incidentes")
cursor.executemany("""
INSERT INTO historial_incidentes VALUES (?, ?, ?, ?)
""", [
("INC-801", "pagos-api", "RESUELTO", "Se incrementó el tamaño del pool de conexiones en Cloud SQL"),
("INC-802", "usuarios-auth", "INVESTIGANDO", "Se reiniciaron réplicas en Cloud Run tras fuga de memoria en Node.js"),
("INC-803", "catalogo-productos", "ABIERTO", "Latencia elevada causada por indexación pendiente en la tabla de productos"),
])
conexion.commit()
conexion.close()
if __name__ == "__main__":
inicializar_base_datos()
print(f"Base de datos de incidentes inicializada con éxito en {DB_PATH}")
```
Crea la base de datos (solo una vez):
#### En Windows (PowerShell):
```powershell
python paso4_mcp_database\database.py
```
#### En Linux o macOS:
```bash
python paso4_mcp_database/database.py
```
### 2. Agente con consulta a Base de Datos (`paso4_mcp_database/agent.py`)
```python
import os
import sqlite3
from pathlib import Path
from dotenv import load_dotenv
from google.adk.agents import Agent
load_dotenv()
MODEL = os.getenv("ADK_MODEL", "gemini-3.8-flash")
DB_PATH = Path(__file__).resolve().parent / "incidentes.db"
def consultar_historial_servicio(nombre_servicio: str) -> list[dict]:
"""Consulta en la base de datos interna los incidentes registrados de un microservicio específico.
Args:
nombre_servicio: El nombre o identificador del microservicio a buscar (ej. 'pagos-api', 'usuarios-auth').
"""
conexion = sqlite3.connect(DB_PATH)
cursor = conexion.cursor()
cursor.execute(
"SELECT id, servicio, estado, solucion_aplicada FROM historial_incidentes WHERE servicio LIKE ?",
(f"%{nombre_servicio}%",),
)
filas = cursor.fetchall()
conexion.close()
return [{"id": f[0], "servicio": f[1], "estado": f[2], "solucion": f[3]} for f in filas]
root_agent = Agent(
name="db_support_agent",
model=MODEL,
description="Agente con acceso al registro histórico de incidentes en base de datos.",
instruction="""
Cuando el operador mencione un problema en un microservicio, consulta primero
la base de datos interna con consultar_historial_servicio para ver soluciones anteriores
antes de sugerir nuevas medidas.
""",
tools=[consultar_historial_servicio],
)
```
```bash
adk run paso4_mcp_database
```
Mensaje de prueba:
```text
El microservicio pagos-api vuelve a tener lentitud. ¿Tenemos algún historial registrado de problemas similares?
```
### 3. La misma base de datos vía servidor MCP (`paso4b_mcp_sqlite`)
Con MCP, el equipo dueño de los datos publica un **servidor** una sola vez y cualquier agente o cliente compatible (ADK, Gemini CLI, IDEs) lo consume sin reescribir código.
> [!IMPORTANT]
> **Requisito previo:** Este servidor MCP se conecta al archivo `incidentes.db` ubicado en `paso4_mcp_database/`. Asegúrate de haber ejecutado previamente la inicialización de la base de datos con `python paso4_mcp_database/database.py` (o en PowerShell: `python paso4_mcp_database\database.py`).
Servidor MCP de solo lectura (`paso4b_mcp_sqlite/mcp_server.py`):
```python
"""Servidor MCP de solo lectura sobre la base de datos de incidentes."""
import sqlite3
from pathlib import Path
try:
from mcp.server.mcpserver import MCPServer # mcp >= 2.0
except ImportError:
from mcp.server.fastmcp import FastMCP as MCPServer # mcp 1.x
DB_PATH = Path(__file__).resolve().parent.parent / "paso4_mcp_database" / "incidentes.db"
servidor = MCPServer("incidentes-quantumroast")
def _consultar(sql: str, parametros: tuple = ()) -> list[dict]:
# Conexión en modo solo lectura
conexion = sqlite3.connect(f"file:{DB_PATH}?mode=ro", uri=True)
conexion.row_factory = sqlite3.Row
filas = [dict(f) for f in conexion.execute(sql, parametros).fetchall()]
conexion.close()
return filas
@servidor.tool()
def listar_servicios() -> list[str]:
"""Lista los microservicios que tienen incidentes registrados."""
return [f["servicio"] for f in _consultar("SELECT DISTINCT servicio FROM historial_incidentes ORDER BY servicio")]
@servidor.tool()
def buscar_incidentes(servicio: str) -> list[dict]:
"""Busca los incidentes de un microservicio (coincidencia parcial del nombre).
Args:
servicio: Nombre o fragmento del nombre del microservicio, ej. 'pagos'.
"""
return _consultar("SELECT * FROM historial_incidentes WHERE servicio LIKE ?", (f"%{servicio}%",))
@servidor.tool()
def incidentes_por_estado(estado: str) -> list[dict]:
"""Devuelve los incidentes con un estado dado.
Args:
estado: Uno de 'ABIERTO', 'INVESTIGANDO' o 'RESUELTO'.
"""
return _consultar("SELECT * FROM historial_incidentes WHERE estado = ?", (estado.upper(),))
if __name__ == "__main__":
servidor.run() # transporte stdio por defecto
```
Agente que se conecta al servidor con `McpToolset` (`paso4b_mcp_sqlite/agent.py`). ADK arranca el servidor como subproceso y **descubre** sus herramientas automáticamente:
```python
import os
import sys
from pathlib import Path
from dotenv import load_dotenv
from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset, StdioConnectionParams
from mcp import StdioServerParameters
load_dotenv()
MODEL = os.getenv("ADK_MODEL", "gemini-3.8-flash")
SERVIDOR_MCP = Path(__file__).resolve().parent / "mcp_server.py"
# ADK arranca el servidor MCP como subproceso y se comunica por stdio
incidentes_mcp = McpToolset(
connection_params=StdioConnectionParams(
server_params=StdioServerParameters(command=sys.executable, args=[str(SERVIDOR_MCP)]),
timeout=30,
),
)
root_agent = Agent(
name="mcp_db_agent",
model=MODEL,
description="Agente que consulta el historial de incidentes a través de un servidor MCP.",
instruction="""
Tienes acceso de solo lectura al historial de incidentes mediante herramientas MCP.
Úsalas para responder con datos reales y termina con una recomendación breve.
""",
tools=[incidentes_mcp],
)
```
```bash
adk run paso4b_mcp_sqlite
```
Mensaje de prueba:
```text
¿Qué incidentes siguen sin resolverse y qué se ha intentado en cada uno?
```
---
## 🤝 Paso 5: Orquestación Multi-Agente (`paso5_multi_agent`)
Como se muestra en el video de introducción a ADK, los agentes complejos no intentan resolverlo todo con un único prompt masivo; delegan responsabilidades a **agentes especializados**, coordinados por un agente comandante u orquestador. ADK ofrece dos mecanismos:
| Mecanismo | Cómo funciona | Cuándo usarlo |
|---|---|---|
| `sub_agents=[...]` | El orquestador **transfiere** la conversación al especialista, que responde directamente al usuario. | Enrutamiento: "te paso con el especialista". |
| `AgentTool(agente)` | El orquestador **llama** al especialista como herramienta, recibe su resultado y sigue razonando. | Cuando el orquestador debe **sintetizar** lo que aportan varios especialistas. |
El Comandante debe combinar SLA e investigación externa en un solo plan, así que usa `AgentTool`. Además, es la forma de usar `google_search` junto a otras herramientas.
Archivo `paso5_multi_agent/agent.py`:
```python
import os
from dotenv import load_dotenv
from google.adk.agents import Agent
from google.adk.tools import google_search
from google.adk.tools.agent_tool import AgentTool
load_dotenv()
MODEL = os.getenv("ADK_MODEL", "gemini-3.8-flash")
# Especialista 1: cálculo y verificación de SLAs
def verificar_sla_guardia(nivel_severidad: str) -> str:
"""Retorna la política de tiempo de respuesta acordada para la guardia.
Args:
nivel_severidad: Nivel de severidad del incidente: 'P0', 'P1', 'P2' o 'P3'.
"""
reglas = {
"P0": "15 minutos (notificación sonora inmediata a jefatura y equipo on-call)",
"P1": "45 minutos (notificación a canal de Slack de operaciones)",
"P2": "4 horas en horario laboral",
}
return reglas.get(nivel_severidad.upper(), "24 horas hábiles")
agente_sla = Agent(
name="especialista_sla",
model=MODEL,
description="Especialista en clasificar tiempos de respuesta y escalamiento de guardias.",
instruction="Analiza la urgencia, determina la severidad (P0-P3) y define el protocolo de escalamiento estricto usando verificar_sla_guardia.",
tools=[verificar_sla_guardia],
)
# Especialista 2: monitoreo de la web y proveedores externos
agente_investigador = Agent(
name="especialista_red",
model=MODEL,
description="Especialista en investigar caídas de proveedores de nube o telecomunicaciones.",
instruction="Usa la búsqueda en Google para corroborar caídas masivas en proveedores cloud o CDN. Cita tus fuentes.",
tools=[google_search],
)
# Agente orquestador raíz
root_agent = Agent(
name="comandante_incidentes",
model=MODEL,
description="Coordinador en jefe para resolución de incidentes técnicos en QuantumRoast.",
instruction="""
Eres el Comandante de Incidentes.
Tienes a tu disposición a dos especialistas:
1. 'especialista_sla': Para determinar ventanas de respuesta y alertas on-call.
2. 'especialista_red': Para verificar si el fallo proviene de proveedores de nube externos.
Recibe el reporte del ingeniero, consulta a AMBOS especialistas y sintetiza un plan de acción
ejecutivo, claro y priorizado.
""",
tools=[AgentTool(agent=agente_sla), AgentTool(agent=agente_investigador)],
)
```
```bash
adk run paso5_multi_agent
```
Mensaje de prueba:
```text
URGENTE: La API de pagos no responde. Parece que hay una caída masiva en la región us-central1 de Google Cloud. ¿Qué hacemos?
```
> [!WARNING]
> Igual que el Paso 3, este paso usa Google Search y requiere facturación habilitada.
---
## 🖥️ Depuración e Inspección Visual con `adk web`
Una de las ventajas clave presentadas en `adk.dev` y en la charla de Google for Developers es la consola visual local integrada.
Para iniciar el servidor de desarrollo e inspección, ejecuta desde la carpeta `intro-adk-tools` (igual en PowerShell y Bash):
```bash
adk web
```
*(O especificando el puerto si el 8000 está ocupado: `adk web --port 8080`)*
Abre en tu navegador:
```text
http://localhost:8000
```
### Características de la interfaz:
1. **Selector de Agentes:** En la esquina superior izquierda puedes alternar entre cualquiera de los agentes (`paso1_basic_agent`, `paso2_function_tools`, `paso5_multi_agent`, etc.).
2. **Chat en Vivo:** Prueba mensajes conversacionales en tiempo real.
3. **Árbol de Ejecución (Execution Trace):** Observa exactamente en qué momento el agente decide pausar la generación de texto, ejecutar una función de Python, llamar a Google Search, a un servidor MCP o a otro agente, junto con los argumentos JSON recibidos y las respuestas procesadas.
Para detener el servidor presiona `Ctrl + C`.
---
## 🧪 Plan B: Google Colab
[](https://colab.research.google.com/github/aaron-the-warrior/get_started_with_agent_development_kit_adk/blob/main/get_started_with_agent_development_kit_adk.ipynb)
Si no puedes instalar Python en tu computadora, sigue el taller completo en el navegador:
1. Haz clic en **Open in Colab**.
2. En la barra lateral izquierda abre **🔑 Secretos**, crea un secreto llamado `GOOGLE_API_KEY` con tu clave y activa el acceso para el notebook.
3. Ejecuta las celdas en orden (`Shift + Enter`).
El notebook crea los mismos archivos de `intro-adk-tools/` y al final permite abrir `adk web` desde Colab.
---
## 🩺 Solución de Problemas
<details>
<summary><b>🪟 <code>Activate.ps1 no se puede cargar porque la ejecución de scripts está deshabilitada</code></b></summary>
PowerShell bloquea scripts por defecto. Permítelos solo en la ventana actual y vuelve a activar:
```powershell
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\.venv\Scripts\Activate.ps1
```
</details>
<details>
<summary><b>🪟 <code>OSError: [Errno 2] No such file or directory</code> durante <code>pip install</code></b></summary>
Windows limita las rutas a 260 caracteres y algunas dependencias de ADK tienen rutas muy largas. Tienes dos opciones:
1. Clonar el repo en una ruta corta, por ejemplo `C:\Users\tu-usuario\adk`.
2. Habilitar rutas largas (en PowerShell **como administrador**) y reiniciar la terminal:
```powershell
New-ItemProperty -Path "HKLM:\SYSTEM\CurrentControlSet\Control\FileSystem" -Name "LongPathsEnabled" -Value 1 -PropertyType DWORD -Force
```
</details>
<details>
<summary><b>🪟 <code>python</code> abre la Microsoft Store o no se reconoce</b></summary>
Instala Python con `winget install Python.Python.3.12`, cierra y vuelve a abrir PowerShell. También puedes usar el lanzador `py` en lugar de `python`, por ejemplo `py -m venv .venv`.
</details>
<details>
<summary><b><code>adk</code> no se reconoce como comando</b></summary>
El entorno virtual no está activo. Actívalo de nuevo desde `intro-adk-tools`:
- 🪟 PowerShell: `.\.venv\Scripts\Activate.ps1`
- 🐧 Bash: `source .venv/bin/activate`
</details>
<details>
<summary><b>Error de autenticación o <code>API key not valid</code></b></summary>
Revisa que `.env` esté dentro de `intro-adk-tools` y que `GOOGLE_API_KEY` tenga tu clave real. Otra opción es definirla solo para la sesión actual:
- 🪟 PowerShell: `$env:GOOGLE_API_KEY = "AIzaSy...tu-clave"`
- 🐧 Bash: `export GOOGLE_API_KEY="AIzaSy...tu-clave"`
</details>
<details>
<summary><b>Error de cuota o permiso en los pasos 3 y 5 (búsqueda en Google)</b></summary>
*Grounding* con Google Search no está incluido en el nivel gratuito. Habilita la [facturación](https://ai.google.dev/gemini-api/docs/billing) en el proyecto de tu API Key (incluye 5,000 búsquedas gratis al mes con Gemini 3.x) o sáltate esos dos pasos.
</details>
<details>
<summary><b><code>no such table: historial_incidentes</code> en el Paso 4</b></summary>
Falta crear la base de datos: ejecuta `python paso4_mcp_database\database.py` (en Bash, `python paso4_mcp_database/database.py`).
</details>
---
## 📚 Recursos para Seguir Aprendiendo
* 🌐 **[adk.dev](https://adk.dev/)**: documentación oficial de ADK.
* 🐙 **[google/adk-python](https://github.com/google/adk-python)**: código fuente de ADK para Python.
* 🧩 **[google/adk-samples](https://github.com/google/adk-samples)**: agentes de ejemplo listos para usar.
* 🚀 **[Desplegar en Cloud Run](https://adk.dev/deploy/cloud-run/)**: lleva tu agente a producción con `adk deploy cloud_run`.
* 🔌 **[modelcontextprotocol.io](https://modelcontextprotocol.io/)**: especificación y guías de MCP.
* 🗄️ **[MCP Toolbox for Databases](https://googleapis.github.io/genai-toolbox/)**: servidor MCP de Google para bases de datos en producción.
* 🔑 **[Google AI Studio](https://aistudio.google.com/)**: consigue tu API Key y prueba modelos.
---
<p align="center">
<b>Powered by aaronthewarrior</b> • Construido con ❤️ para la comunidad de desarrolladores de IA
</p>
连接信息
猜你喜欢
暂无推荐服务器