Cómo construir tu primer agente IA con Google ADK y Python desde cero

Antes de ejecutar el primer comando, revisa esta lista. El único costo real es la clave de API de Gemini: el nivel gratuito de Google AI Studio es suficiente para aprender y para proyectos pequeños.

• Python 3.10 o superior instalado en tu equipo (verifica con 'python3 --version').
• pip disponible en el entorno (viene con Python 3.10+).
• Cuenta Google y acceso a Google AI Studio para crear una clave de API de Gemini.
• Terminal con permisos para instalar paquetes Python.
• Conexión a internet para que el agente pueda usar google_search en tiempo real.

Si tu equipo ya tiene un proyecto de Google Cloud activo y facturación habilitada, puedes alternar a Vertex AI cambiando una variable de entorno y habilitando la API de Vertex. La estructura del código del agente no cambia.

Este es el núcleo del tutorial. El archivo agent.py define el comportamiento del agente: qué modelo usa, cuál es su función y qué herramientas tiene disponibles. El ejemplo construye un asistente que combina búsqueda web en tiempo real con una función Python propia que devuelve el tipo de cambio del día.

Paso 1: escribir agent.py

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

# Herramienta personalizada: funcion Python normal
def tipo_cambio(moneda: str) -> dict:
    """Retorna el tipo de cambio indicativo del dia para una moneda.
    Args:
        moneda: codigo ISO de la moneda (USD, EUR, BRL, etc.)
    Returns:
        dict con el tipo de cambio y la fuente.
    """
    tasas = {
        "USD": {"clp": 960, "fuente": "referencia indicativa"},
        "EUR": {"clp": 1045, "fuente": "referencia indicativa"},
        "BRL": {"clp": 175, "fuente": "referencia indicativa"},
    }
    if moneda.upper() in tasas:
        return {"status": "ok", "moneda": moneda.upper(), "clp": tasas[moneda.upper()]["clp"]}
    return {"status": "error", "mensaje": "Moneda no disponible en esta demo"}

# Definicion del agente
root_agent = Agent(
    model="gemini-flash-latest",
    name="asistente_comercial",
    description="Asistente para consultas de mercado chileno con acceso a busqueda web.",
    instruction=(
        "Eres un asistente comercial para empresas chilenas. "
        "Respondes en espanol formal. Cuando necesitas informacion actual, "
        "usa google_search. Para tipos de cambio usa tipo_cambio. "
        "Siempre cita tus fuentes al responder."
    ),
    tools=[google_search, tipo_cambio],
)

Paso 2: agregar __init__.py

from . import agent

Esta línea permite que ADK descubra el módulo al ejecutar los comandos de la interfaz de línea de comandos.

Conceptos clave del código

Una de las fortalezas de Google ADK frente a alternativas más simples es el soporte nativo para sistemas donde múltiples agentes se coordinan. El agente orquestador recibe la solicitud del usuario y delega a agentes especializados según la 'description' de cada uno.

Estructura de un sistema biagente

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

# Agente especializado: busqueda de mercado
agente_mercado = Agent(
    model="gemini-flash-latest",
    name="agente_mercado",
    description="Especialista en busqueda de informacion de mercado y competencia.",
    instruction="Busca informacion de mercado actualizada. Responde con datos concretos y cita fuentes.",
    tools=[google_search],
)

# Agente especializado: analisis financiero
def calcular_margen(precio_venta: float, costo: float) -> dict:
    """Calcula el margen bruto entre precio de venta y costo."""
    margen = ((precio_venta - costo) / precio_venta) * 100
    return {"margen_pct": round(margen, 2), "precio": precio_venta, "costo": costo}

agente_finanzas = Agent(
    model="gemini-flash-latest",
    name="agente_finanzas",
    description="Especialista en analisis financiero y calculo de margenes.",
    instruction="Analiza datos financieros y calcula indicadores. Usa calcular_margen cuando corresponda.",
    tools=[calcular_margen],
)

# Orquestador: recibe la solicitud y delega
root_agent = Agent(
    model="gemini-flash-latest",
    name="orquestador",
    description="Orquestador principal que coordina busqueda de mercado y analisis financiero.",
    instruction=(
        "Eres el coordinador de un equipo de analistas. "
        "Para consultas de mercado, delega a agente_mercado. "
        "Para calculos financieros, delega a agente_finanzas. "
        "Sintetiza los resultados en una respuesta ejecutiva."
    ),
    agents=[agente_mercado, agente_finanzas],
)

Nota el campo 'agents' en el orquestador: ahí se registran los agentes subordinados. ADK expone la 'description' de cada uno al modelo para que decida a quién delegar. Esta arquitectura escala sin cambiar el código del orquestador.

En Cognitiva aplicamos este criterio cuando un cliente evalúa qué framework de agentes adoptar. No hay una respuesta universal: la elección depende del stack actual del equipo, del nivel de control que necesita sobre el flujo y del ecosistema de despliegue.

La recomendación de Cognitiva: si tu equipo ya opera en Google Cloud y usa Workspace como plataforma de colaboración, Google ADK reduce el tiempo de llegada a producción porque comparte credenciales, región y consola. Si necesitas control total del grafo de estados con trazabilidad avanzada, LangGraph sigue siendo la referencia. Si tu nube principal es AWS, Strands Agents es la alternativa natural.