Leccion 1: Construye tu primer agente con Google ADK

Sebastian Gomez

Oct 16, 2025

Updated: Jun 25, 2026

Leccion 1: Construye tu primer agente con Google ADK

Notebook de la lección: Lesson_1.ipynb

Bienvenida o bienvenido a la aventura de crear tu primer agente de noticias de IA con el Agent Development Kit (ADK) de Google. En esta lección sentamos las bases de un agente capaz de conversar, conectarse al mundo real y entregar información fresca. Aquí tienes un recorrido claro del cuaderno Lesson_1.ipynb, con consejos prácticos para avanzar con confianza.

Nota sobre los nombres de modelo. El ecosistema de Gemini se mueve muy rápido y los identificadores de modelo cambian con frecuencia, sobre todo los que llevan la etiqueta preview y una fecha. En este post uso nombres concretos como ejemplo, pero antes de copiarlos consulta la lista vigente en la documentación de ADK y de Gemini y elige un modelo estable (GA) cuando exista.

Panorama general

Anatomía de un agente: modelo más instrucciones más herramientas.
Preparar el entorno y conocer la Web UI de ADK.
Añadir búsqueda en tiempo real y probar modelos Gemini.
Configurar agentes con Python o con YAML.
Afinar instrucciones para un comportamiento consistente.

1.1 Preparativos iniciales

ADK incluye las librerías esenciales (google-adk, utilidades de CLI, helpers). Aun así, verifica las dependencias y aísla tu entorno con un virtualenv. Si vas a extender la demo, agrega un requirements.txt propio para fijar versiones y evitar sorpresas.

1.2 Estructura base de un proyecto ADK

Genera el esqueleto con el siguiente comando (proyecto basado en código):

adk create app_01 --model gemini-2.5-flash --api_key $GOOGLE_API_KEY

Esto crea una estructura mínima:

app_01/agent.py: la lógica del agente.
.env: credenciales y configuración.
__init__.py: importaciones limpias.

Recuerda que el ID de modelo del ejemplo es solo un punto de partida; cámbialo por el que necesites según la lista vigente.

1.3 Autenticación sin dolor

Puedes usar una API key de Gemini (Google AI Studio) o credenciales de Vertex AI.

Con Google AI Studio, crea un archivo .env dentro de app_01/:

GOOGLE_GENAI_USE_VERTEXAI=FALSE
GOOGLE_API_KEY=<tu_api_key>

Con Vertex AI, usa el .env o variables de entorno:

GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=<proyecto>
GOOGLE_CLOUD_LOCATION=<ubicacion>

Nunca publiques tus claves ni hagas commit del .env a GitHub.

1.4 Escribiendo el primer agent.py

Con el cell magic %%writefile puedes escribir el archivo desde el notebook. El agente mínimo define:

Un nombre legible (ai_news_agent).
Un modelo base. Para voz conviene un modelo compatible con la Gemini Live API.
Instrucciones breves que describen su rol.

Tip: ADK es agnóstico al modelo; puedes usar Gemini, Claude, Ollama o integraciones vía LiteLLM. Define pronto si priorizas voz, multimodalidad o latencia, porque eso condiciona qué modelo eliges.

1.5 Probando en la ADK Web UI

Para conversar con el agente tienes dos opciones.

Desde la carpeta padre del agente, ejecuta adk web y luego selecciona "app_01" en el menú. O apunta directo a la app:

adk web --port 8000 app_01

Abre la URL (http://localhost:8000). En Windows, si ves _make_subprocess_transport NotImplementedError, usa adk web --no-reload. Detén el proceso con Ctrl-C.

La Web UI muestra el trace (paso a paso) y permite interacción por voz en tiempo real. Para voz, usa un modelo compatible con la Gemini Live API.

1.6 Añadiendo la herramienta de búsqueda

El modelo por sí solo no conoce noticias recientes. Para darle acceso a la web añadimos la herramienta google_search:

from google.adk.agents import Agent
from google.adk.tools import google_search

root_agent = Agent(
    name="ai_news_agent_simple",
    model="gemini-2.5-flash",
    instruction="Eres un asistente de noticias de IA. Usa Google Search para hallar información reciente.",
    tools=[google_search],
)

Con esto el agente consulta la web, procesa los resultados y cita fuentes actuales. Ten en cuenta dos detalles:

google_search es compatible con modelos Gemini 2 en adelante, así que funciona con los modelos Gemini 2.5 que usamos aquí.
Si la respuesta incluye "Search suggestions", debes mostrarlas en tu app (es un requisito de la política de Grounding con Google Search). Ver la documentación de ADK: docs/tools/built-in-tools.md y docs/grounding/google_search_grounding.md.

Más adelante puedes explorar otras herramientas (ejecución de código, bases de datos, Workspace) según tu caso de uso.

1.7 Probando modelos de texto

El modelo gemini-2.5-flash prioriza texto y suele responder más rápido cuando no necesitas audio. Puedes crear otra app con el mismo código y cambiar solo el modelo. Experimenta para balancear costo, latencia y capacidades.

1.8 Configuración declarativa con YAML

Si prefieres no escribir Python, usa --type=config para generar root_agent.yaml con los mismos campos (nombre, modelo, instrucciones, herramientas):

name: ai_news_agent_yaml
model: gemini-2.5-flash
description: Agente que resume noticias recientes de IA.
instruction: Usa Google Search para encontrar y resumir novedades de IA.
tools:
  - name: google_search

Sugerencia: documenta tus decisiones en comentarios. ADK valida el esquema y te avisará si falta algún campo clave. Más detalles en la documentación de configuración de agentes.

1.9 Afinando instrucciones avanzadas

Para un comportamiento consistente, agrega reglas claras:

Identidad definida: el agente solo cubre noticias de IA.
Mecanismo de rechazo: un texto exacto para solicitudes fuera de alcance.
Flujos obligatorios: uso de google_search y citas de fuentes.
Controles de contexto: delimitan qué se considera una pregunta válida.

Este patrón reduce al mínimo las alucinaciones y mantiene el propósito del agente.

Buenas prácticas y próximos pasos

Cierra procesos viejos con pkill -f "adk web" para liberar recursos.
Documenta cada variante (app_01 a app_05) con notas y resultados.
Repite prompts con pequeñas variaciones para observar cambios (la salida puede variar por estocasticidad).
Define convenciones de nombres, carpetas y versionado desde ya.

Resumen en 3 puntos

Un agente ADK se compone de tres piezas: un modelo, unas instrucciones y unas herramientas. Con eso ya tienes un asistente conversacional funcional.
Con google_search el agente sale a la web, procesa resultados y cita fuentes recientes; recuerda mostrar las "Search suggestions" cuando aparezcan.
Puedes definir el agente en Python o de forma declarativa en YAML, y los nombres de modelo cambian rápido, así que conviene consultar siempre la lista vigente.

Ejercicios propuestos

Crea tu propio agente con adk create, configúralo con tu GOOGLE_API_KEY y pruébalo en la Web UI.
Añade la herramienta google_search y pídele noticias recientes de IA; comprueba que muestre las fuentes y las "Search suggestions".
Crea una segunda app cambiando solo el modelo (por ejemplo, uno de texto frente a uno de voz) y compara latencia y calidad de respuesta.

Recursos

ADK Quickstart: google.github.io/adk docs/get started/quickstart/
ADK Python: google.github.io/adk docs/get started/python/
Built in Tools (Google Search): google.github.io/adk docs/tools/built in tools/
Siguiente lección: Potencia tu agente con herramientas personalizadas

Este contenido se basa en el curso "Building Live Voice Agents with Google's ADK!" de DeepLearning.AI (learn.deeplearning.ai/courses/building live voice agents with googles adk/). Este blog busca acercar el material de ADK al español.

Eso es todo, espero que esta lección te sea de utilidad y que puedas aplicarla a algún proyecto que tengas en mente. Déjame un comentario si te sirvió, si quieres aportar una opinión o si tienes alguna duda. Y recuerda que si te gustó, también puedes compartirlo usando los links a las redes sociales aquí abajo. Nos vemos en la siguiente lección. Buena suerte.