Google ADK: cómo crear agentes Python con tools, MCP y evals sin quedarte en demo
Google ADK no es solo otra forma de llamar a Gemini. Su valor está en darte una estructura de ingeniería para agentes: orquestación, tools, MCP, sesiones, evaluación y despliegue sin esconder todo en un prompt gigante.
Google ADK no es solo otra forma de llamar a Gemini. Su valor está en darte una estructura de ingeniería para agentes: orquestación, tools, MCP, sesiones, evaluación y despliegue sin esconder todo en un prompt gigante.
Google ADK, Agent Development Kit, es un framework code-first para construir, evaluar y desplegar agentes de IA. Está optimizado para Gemini y Google Cloud, pero su idea importante no es el proveedor: es tratar el agente como una aplicación con runner, tools, estado, evals y runtime.
Checklist
Qué es Google ADK en una frase citable
Google ADK es un framework para crear agentes de IA como software: defines agentes, instrucciones, modelos, tools, workflows, sesiones, evaluación y despliegue con código en vez de confiar en prompts sueltos.
La diferencia frente a una llamada directa al modelo es la arquitectura. En una llamada normal tienes prompt, modelo y respuesta. En ADK tienes un runtime que puede gestionar eventos, estado, tools, subagentes, callbacks, evals y canales de despliegue.
Eso importa porque los agentes reales no fallan solo por el modelo. Fallan por permisos demasiado amplios, tools vagas, estado implícito, rutas de ejecución imposibles de reproducir y cambios de prompt que nadie evalúa antes de publicar.
Recibe una lectura semanal de herramientas IA para devs
Si quieres seguir frameworks de agentes como Google ADK, Pydantic AI, OpenAI Agents SDK, Claude Agent SDK y MCP sin tragarte cada changelog, DevAI Semanal te lo resume en un email de 5 minutos.
Suscribirme gratis
Primer ejemplo: un agente Python pequeño
La forma más sana de empezar no es un sistema multiagente. Es un agente con una instrucción concreta y una tool de lectura. Si esto no es reproducible y medible, añadir subagentes solo amplifica el ruido.
from google.adk.agents import Agent
from google.adk.tools import google_search
root_agent = Agent(
name="research_assistant",
model="gemini-flash-latest",
instruction=(
"Busca informacion tecnica actual, cita fuentes y di cuando "
"no tengas evidencia suficiente. No ejecutes acciones mutantes."
),
tools=[google_search],
)Checklist
Tools: el contrato importa más que la lista
ADK permite conectar tools propias, herramientas integradas, OpenAPI y MCP. La tentación es enchufar todo lo que el agente podría necesitar. Mala idea. Una tool debe tener nombre claro, argumentos mínimos, output predecible y permisos acordes al riesgo.
Regla práctica: tools de lectura primero; tools mutantes solo con scopes estrechos, logging y aprobación humana cuando afecten repos, datos de cliente, facturación, infraestructura o producción.
La documentación de ADK incluye `McpToolset` para conectar servidores MCP por transportes locales o remotos. Eso es potente, pero MCP no sustituye el diseño de permisos. Si un servidor MCP expone demasiadas acciones, ADK solo será el sitio donde ese riesgo se vuelve fácil de invocar.
import os
from google.adk.agents import Agent
from google.adk.tools.mcp_tool import McpToolset
from google.adk.tools.mcp_tool.mcp_session_manager import (
StreamableHTTPConnectionParams,
)
docs_mcp = McpToolset(
connection_params=StreamableHTTPConnectionParams(
url="https://developerknowledge.googleapis.com/mcp",
headers={"X-Goog-Api-Key": os.environ["DEVELOPER_KNOWLEDGE_API_KEY"]},
)
)
root_agent = Agent(
name="google_docs_agent",
model="gemini-flash-latest",
instruction=(
"Responde preguntas de implementacion usando documentacion oficial. "
"Cita la pagina consultada y marca incertidumbre."
),
tools=[docs_mcp],
)Workflow agents: cuándo salir del agente único
ADK cubre agentes de workflow como `SequentialAgent`, `ParallelAgent` y `LoopAgent`. La señal para usarlos no es que suenen sofisticados; es que tu proceso ya tiene fases claras.
Puntos a revisar
Lo que conviene comprobar
Un `SequentialAgent` encaja en pipelines como investigar, sintetizar y validar. Un `ParallelAgent` encaja cuando puedes separar tareas independientes, por ejemplo comprobar documentación, changelog y repositorio. Un `LoopAgent` solo debería existir con condición de parada clara, presupuesto y salida observable.
La ruta mala es meter routing dinámico desde el día uno. Primero escribe el flujo determinista que un humano seguiría. Luego permite adaptación donde de verdad haya incertidumbre.
Checklist
Sesiones y memoria: no todo contexto merece entrar al prompt
ADK separa conversación, eventos, estado y memoria. Esa separación ayuda a evitar el clásico prompt gigante que mezcla preferencias, datos vivos, resultados intermedios y reglas de seguridad.
Para un agente interno, guardaría en sesión lo necesario para continuar una ejecución; en memoria, preferencias o hechos reutilizables; y fuera del prompt, cualquier dato sensible que solo debería consultarse bajo tool controlada.
Si no puedes explicar qué parte del contexto viene de sesión, memoria o tool call, no estás listo para auditar el agente cuando se equivoque.
Checklist
Evaluación: el punto donde ADK deja de ser demo
ADK incluye evaluación de respuestas y trayectorias. La parte clave es la trayectoria: no basta con que la respuesta final suene bien; importa qué tools llamó, en qué orden, con qué argumentos y si ignoró instrucciones críticas.
Una batería mínima debería tener casos normales, ambiguos y hostiles. Para agentes con MCP, añade casos donde la tool devuelve datos incompletos, una fuente irrelevante, un error de permisos y una respuesta que debería terminar en revisión humana.
Mide al menos: exactitud, uso correcto de tools, coste, latencia, número de llamadas, refusals útiles, errores de permisos y cambios entre modelos. Cambiar de `gemini-flash` a un modelo más capaz sin evals es una apuesta, no ingeniería.
Errores que evitaría
- El primero es vender ADK como garantía de calidad por estar cerca de Google. Un framework no convierte tools vagas en decisiones buenas.
- El segundo es conectar MCP sin política. Si el agente puede descubrir o ejecutar demasiadas cosas, el problema ya no es el modelo: es tu superficie de permisos.
- El tercero es usar workflow agents para impresionar. Si el flujo no está claro en una pizarra, tampoco estará claro cuando lo ejecute un LLM.
- El cuarto es desplegar antes de evaluar trayectorias. Una respuesta correcta con tool calls incorrectas es una incidencia esperando fecha.
Cuándo elegir ADK frente a OpenAI Agents SDK o Pydantic AI
Elige ADK si tu stack está en Google Cloud, usas Gemini/Vertex AI, quieres una ruta clara a Cloud Run o Agent Engine y necesitas orquestación con tools, sesiones y evals dentro del ecosistema Google.
Puntos a revisar
Lo que conviene comprobar
Elige OpenAI Agents SDK si tu producto depende de la superficie OpenAI, tracing y handoffs propios del SDK. Elige Pydantic AI si tu equipo Python prioriza tipos, output estructurado y portabilidad entre proveedores.
La decisión no debería ser religiosa. Haz una prueba con el mismo caso, las mismas tools y las mismas evals. El framework que haga más fácil auditar el fallo gana.
Plan de adopción en cinco días
- Día 1: elige una tarea de lectura con impacto real, como responder dudas de documentación interna o preparar un briefing técnico.
- Día 2: crea un agente ADK con una sola tool y logs básicos. Nada de acciones mutantes.
- Día 3: añade session state y diez evals: cinco normales, tres ambiguas y dos hostiles.
- Día 4: prueba MCP solo para una fuente concreta y mide si mejora la respuesta o solo añade coste.
- Día 5: decide runtime. Si las evals no son estables, no despliegues; deja el agente como CLI interna.
Checklist
Conclusión
Google ADK es interesante porque empuja los agentes hacia una forma más operable: runner, tools, workflows, sesiones, evaluación y despliegue. Esa estructura no elimina el riesgo, pero lo hace visible.
Mi recomendación es usar ADK como disciplina, no como excusa para meter más IA en producción. Empieza estrecho, mide trayectorias, limita MCP, audita permisos y despliega solo cuando puedas reproducir una run mala sin leer la mente del modelo.
Preguntas frecuentes
¿Qué es Google ADK?
Google ADK, Agent Development Kit, es un framework code-first para construir, evaluar y desplegar agentes de IA con modelos, tools, workflows, sesiones y runtimes.
¿Google ADK solo sirve con Gemini?
Está optimizado para Gemini y Google Cloud, pero la idea del framework es modular y puede integrarse con tools, MCP y distintos patrones de despliegue.
¿ADK soporta MCP?
Sí. ADK puede conectar servidores MCP mediante `McpToolset`, incluyendo transportes locales y remotos, para exponer capacidades externas como tools del agente.
¿Cuándo usar workflow agents en ADK?
Úsalos cuando el proceso tenga fases claras: secuencial para pipelines, paralelo para tareas independientes y loop solo con condición de parada y presupuesto.
¿Qué debo evaluar en un agente ADK?
Evalúa respuesta final, trayectoria, llamadas a tools, argumentos, latencia, coste, errores, refusals útiles y comportamiento ante datos ambiguos o hostiles.
¿ADK reemplaza a OpenAI Agents SDK o Pydantic AI?
No. ADK compite como framework de agentes, pero conviene elegir según stack, proveedor, despliegue, tipado, observabilidad y facilidad de evaluación.
Fuentes y referencias
También te puede interesar
OpenAI Agents SDK: MCP, guardrails y tracingPydantic AI: agentes Python tipadosClaude Agent SDK en Python y TypeScriptDocker MCP Toolkit para agentes localesMétricas para agentes de códigoRecibe una lectura semanal de herramientas IA para devs
Cada semana te resumo herramientas de IA para devs, agentes, MCP, seguridad y workflows en un email de 5 minutos. En español y sin ruido.
Suscribirme gratis
