¡Bienvenido a la primera parte de la serie "Construyendo Agentes de IA con ADK"! En esta serie de codelabs prácticos, te embarcarás en un emocionante viaje para crear tu propio agente de IA inteligente utilizando el Agent Development Kit (ADK) de Google.

Comenzaremos con lo esencial, guiándote a través de la configuración de tu entorno de desarrollo y la creación de un agente conversacional fundamental. Al final de este codelab, habrás construido tu primera IA interactiva, lista para ser expandida en las partes posteriores de esta serie mientras la transformamos en un sofisticado Sistema Multi-Agente (MAS).

Puedes completar este codelab ya sea en tu entorno local o en Google Cloud. Para la experiencia más consistente, recomendamos usar Cloud Shell desde el entorno de Google Cloud. Cloud Shell también proporciona 5 GB de almacenamiento persistente en el directorio $HOME. Esto es útil para almacenar scripts, archivos de configuración o repositorios clonados.

Nota: Si eliges trabajar localmente, podrías requerir pasos adicionales de configuración, instalación y autenticación, que no están cubiertos por la sección de configuración del entorno de este laboratorio.

Prerrequisitos

• Comprensión de los conceptos de IA Generativa
• Competencia básica en programación Python
• Familiaridad con línea de comandos / terminal

Qué aprenderás

• Cómo configurar un entorno Python
• Cómo crear un Agente de Asistente Personal simple usando ADK
• Cómo ejecutar, probar y depurar el agente

Qué necesitarás

• Una computadora funcional y wifi confiable
• Un navegador, como Chrome, para acceder a Google Cloud Console
• Un Proyecto de Google Cloud con facturación habilitada
• Una mente curiosa y ganas de aprender

Los agentes de IA están revolucionando la forma en que interactuamos con la tecnología. Un agente de IA es un programa inteligente diseñado para actuar en tu nombre, similar a un asistente personal digital. Puede percibir su entorno, tomar decisiones y realizar acciones para lograr objetivos específicos de forma autónoma.

¿Qué es un agente de IA?

En esencia, un agente de IA utiliza un Modelo de Lenguaje Grande (LLM) como su "cerebro" para entender y razonar. Esto le permite:

• Procesar información de diversas fuentes (texto, imágenes, audio)
• Comprender el contexto y las intenciones del usuario
• Crear planes de acción
• Ejecutar tareas de forma autónoma
• Aprender y adaptarse con el tiempo

Agent Development Kit (ADK)

El ADK de Google es un framework que simplifica la creación de agentes de IA. Proporciona:

• Herramientas de desarrollo listas para usar
• Integración con modelos Gemini
• Interfaces de usuario predefinidas
• Capacidades de extensión y personalización

En este codelab, crearemos un agente asistente personal que te ayudará con tareas cotidianas.

Crear un Proyecto de Google Cloud

Este codelab asume que ya tienes un proyecto de Google Cloud con facturación habilitada. Si aún no lo tienes, sigue estos pasos:

Seleccionar o crear un proyecto

• Ve a Google Cloud Console.
• En la parte superior, haz clic en el selector de proyectos (junto al logo de Google Cloud).
• Elige un proyecto existente o crea uno nuevo.

Habilitar la facturación

• Asegúrate de que la facturación esté habilitada para el proyecto seleccionado.
• Consulta cómo verificarlo en la documentación de Facturación de Google Cloud.

Nota: La facturación debe estar habilitada incluso para el nivel gratuito, ya que es el mecanismo para rastrear uso. Solo se te cobrará si excedes los límites del nivel gratuito o usas servicios de pago.

Configurar Cloud Shell

Verifica que estás correctamente configurado en Cloud Shell, la interfaz de línea de comandos integrada en Google Cloud Console.

Iniciar Cloud Shell

En la esquina superior derecha de Google Cloud Console, haz clic en el ícono de terminal (>_) para activar Cloud Shell.

Autorizar acceso

Si se te solicita, haz clic en Autorizar para conceder a Cloud Shell los permisos necesarios sobre tu proyecto.

Verificar tu cuenta

Una vez cargado Cloud Shell, confirma que usas la cuenta correcta. Ejecuta:

gcloud auth list

Deberías ver algo similar:

Credentialed Accounts

ACTIVE: *
ACCOUNT: cuenta_actual@example.com

To set the active account, run:
    $ gcloud config set account `ACCOUNT`

Cambiar de cuenta (si es necesario)

Si la cuenta activa no es la correcta para este codelab, cámbiala reemplazando por tu email real:

gcloud config set account <tu_cuenta_deseada@example.com>

Confirmar tu proyecto

Verifica que Cloud Shell usa el proyecto correcto. Ejecuta:

gcloud config list project

Busca la sección [core] y confirma que el ID coincide con el proyecto deseado:

[core]
project = <id-proyecto-actual>

Establecer tu proyecto (si es necesario)

Si no coincide, establece el proyecto correcto:

gcloud config set project <tu-id-proyecto-deseado>

Habilitar APIs requeridas

Antes de usar los servicios de Google Cloud, habilita las APIs necesarias para tu proyecto. En Cloud Shell, ejecuta:

gcloud services enable aiplatform.googleapis.com

Si la operación fue exitosa, verás Operation/... finished successfully en el terminal.

Antes de iniciar cualquier proyecto de Python, es una buena práctica crear un entorno virtual. Esto aísla las dependencias del proyecto, previniendo conflictos con otros proyectos o con los paquetes globales de Python del sistema. Dado que el Agent Development Kit (ADK) requiere Python 3.9 o superior, usaremos una herramienta como uv para gestionar tanto el entorno virtual como asegurar que se use la versión correcta de Python.

uv es una herramienta moderna, rápida y eficiente para gestionar proyectos y entornos de Python, combinando funcionalidades que tradicionalmente se encuentran en herramientas como pip, venv, pip-tools y pipx. Está escrita en Rust para mayor velocidad.

Aunque hay varios métodos para instalar uv, usaremos pip para obtenerlo desde PyPI, ya que Cloud Shell ya tiene pip disponible. Usamos uv porque es una herramienta extremadamente rápida y todo-en-uno que maneja tanto la instalación de paquetes (como pip) como los entornos virtuales (como venv), simplificando nuestro flujo de trabajo.

Instalar el paquete uv

pip install uv

Reiniciar el terminal de Cloud Shell

Después de la instalación, debes reiniciar el terminal de Cloud Shell para que el sistema pueda reconocer el nuevo comando uv.

1. Escribe exit en el terminal de Cloud Shell
2. Vuélvelo a abrir haciendo clic en el ícono del terminal (>_) en la esquina superior derecha

Verificar si uv se instaló correctamente

uv --version

Crear una nueva carpeta de proyecto para tu agente de IA

uv init ai-agents-adk
cd ai-agents-adk

Crear un entorno virtual con Python 3.12

uv venv --python 3.12

Instalar la librería Google ADK dentro de tu entorno virtual

uv add google-adk

Verificar si has instalado el paquete google-adk exitosamente

uv pip list | grep google-adk

Si ves una línea de salida con google-adk y su versión, estás listo para proceder al siguiente paso.

Agregar soporte para variables de entorno (.env)

Para cargar variables desde un archivo .env dentro de tu código Python, instala python-dotenv en el entorno y úsalo al inicio de tus scripts.

Instalar python-dotenv

uv add python-dotenv

Habilite las API necesarias

Haz clic en el siguiente botón para habilitar las APIs necesarias para este codelab en tu proyecto de Google Cloud: Vertex AI, Dataform y Compute Engine.

Habilita las APIs

Ahora que tu entorno de desarrollo está configurado y listo, es momento de establecer los fundamentos para tu agente de IA. El Agent Development Kit (ADK) simplifica este proceso, requiriendo solo unos pocos archivos esenciales para definir la lógica central y la configuración de tu agente.

Estos tres archivos trabajan juntos para hacer que tu agente sea descubrible, ejecutable y configurable:

• agent.py: Este es el corazón de tu agente. Contiene el código Python principal que define el comportamiento de tu agente, incluyendo su nombre, el modelo de lenguaje grande (LLM) que usa como su "cerebro", y las instrucciones centrales que guían sus respuestas.
• __init__.py: En Python, el archivo __init__.py marca un directorio como un paquete de Python. Para ADK, es crucial porque ayuda al framework a descubrir y cargar la definición de tu agente desde agent.py. En proyectos ADK simples, a menudo contiene una sola línea para importar tu módulo del agente, haciendo que tu agente sea accesible al ejecutor de ADK.
• .env: Este archivo (abreviatura de "environment") se usa para almacenar información sensible y variables de configuración que tu agente necesita, como claves API, IDs de proyecto y ubicaciones geográficas. Mantener estos detalles en un archivo .env separado es una buena práctica para seguridad y portabilidad, ya que previene codificar datos sensibles directamente en tu código. También te permite cambiar configuraciones fácilmente sin modificar la lógica principal de tu agente.

Usa los comandos a continuación para crear estos archivos dentro de una carpeta dedicada para tu agente asistente personal:

Crear el agente

uv run adk create personal_assistant

Una vez ejecutado el comando, se te pedirá elegir algunas opciones para configurar tu agente. Para el primer paso, elige la opción 1 para usar el modelo gemini-2.0-flash-001, un modelo rápido y eficiente perfecto para tareas conversacionales.

Choose a model for the root agent:
1. gemini-2.0-flash-001
2. Other models (fill later)
Choose model (1, 2): 1

Para el segundo paso, elige Vertex AI (opción 2), la poderosa plataforma de IA gestionada de Google Cloud, como proveedor de servicios backend.

1. Google AI
2. Vertex AI
Choose a backend (1, 2): 2

Finalmente, se te pedirá confirmar tu ID de proyecto de Google Cloud y región. Si los valores pre-llenados (current-project-id y current-region) son los que intentas usar, simplemente presiona Enter para cada pregunta.

Enter Google Cloud project ID [current-project-id]: 
Enter Google Cloud region [current-region]:

Deberías ver una salida similar en tu terminal.

Agent created in /home/<your-username>/ai-agent-adk/personal_assistant:
- .env
- __init__.py
- agent.py

Abrir el Editor

Ahora, haz clic en el botón Open Editor en la parte superior de tu ventana de Cloud Shell. Hacer clic en ese botón te llevará a la ventana del Editor, lo que hace mucho más fácil explorar el contenido de tus archivos. El cambio puede tomar un momento; si te quedas atascado en una pantalla de carga por más de unos minutos, intenta refrescar tu navegador.

Nota: Puedes usar un editor de línea de comandos como Vim, pero necesitarás conocer los comandos para abrir y salir de Vim por tu cuenta.

Una vez que la ventana del Editor esté completamente cargada, navega a la carpeta personal-assistant. Verás los archivos necesarios como se mencionó arriba (agent.py, __init__.py, y .env). Exploremos el contenido.

Si no ves el archivo .env en la carpeta, ve a la barra de menú en la parte superior, haz clic en View, y luego selecciona Toggle Hidden Files. Esta es una configuración común ya que los archivos .env a menudo están ocultos por defecto para prevenir exposición accidental.

Explorar el contenido de cada archivo

agent.py

Este archivo instancia tu agente usando la clase Agent de la librería google.adk.agents.

from google.adk.agents import Agent

root_agent = Agent(
    model='gemini-2.0-flash-001',
    name='root_agent',
    description='A helpful assistant for user questions.',
    instruction='Answer user questions to the best of your knowledge',
)

• from google.adk.agents import Agent: Esta línea importa la clase Agent necesaria de la librería ADK.
• root_agent = Agent(...): Aquí, estás creando una instancia de tu agente de IA.
• name="personal_assistant": Un identificador único para tu agente. Así es como ADK reconocerá y se referirá a tu agente.
• model="gemini-2.5-flash": Este parámetro crucial especifica qué Modelo de Lenguaje Grande (LLM) usará tu agente como su "cerebro" subyacente para entender, razonar y generar respuestas. gemini-2.5-flash es un modelo rápido y eficiente adecuado para tareas conversacionales.
• description="...": Esto proporciona un resumen conciso del propósito o capacidades del agente. La descripción es más para entendimiento humano o para otros agentes en un sistema multi-agente para entender qué hace este agente particular. A menudo se usa para logging, depuración, o al mostrar información sobre el agente.
• instruction="...": Este es el prompt del sistema que guía el comportamiento de tu agente y define su personalidad. Le dice al LLM cómo debe actuar y cuál es su propósito principal. En este caso, establece al agente como un "asistente útil". Esta instrucción es clave para dar forma al estilo conversacional y capacidades del agente.

__init__.py

Este archivo es necesario para que Python reconozca personal-assistant como un paquete, permitiendo a ADK importar correctamente tu archivo agent.py.

from . import agent

• from . import agent: Esta línea realiza una importación relativa, diciéndole a Python que busque un módulo llamado agent (que corresponde a agent.py) dentro del paquete actual (personal-assistant). Esta línea simple asegura que cuando ADK trata de cargar tu agente personal-assistant, puede encontrar e inicializar el root_agent definido en agent.py. Incluso si está vacío, la presencia de __init__.py es lo que hace del directorio un paquete de Python.

.env

Este archivo contiene configuraciones específicas del entorno y credenciales sensibles.

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID
GOOGLE_CLOUD_LOCATION=YOUR_PROJECT_LOCATION

• GOOGLE_GENAI_USE_VERTEXAI: Esto le dice al ADK que intentas usar el servicio Vertex AI de Google para tus operaciones de IA Generativa. Esto es importante para aprovechar los servicios gestionados de Google Cloud y modelos avanzados.
• GOOGLE_CLOUD_PROJECT: Esta variable contendrá el identificador único de tu Proyecto de Google Cloud. ADK necesita esto para asociar correctamente tu agente con tus recursos en la nube y habilitar la facturación.
• GOOGLE_CLOUD_LOCATION: Esto especifica la región de Google Cloud donde están ubicados tus recursos de Vertex AI (ej. us-central1). Usar la ubicación correcta asegura que tu agente pueda comunicarse efectivamente con los servicios de Vertex AI en esa región.

Con los tres archivos en su lugar, estás listo para ejecutar el agente directamente desde la terminal. Para hacer esto, necesitas abrir la ventana de Terminal. ¡Hacer clic en Terminal en la barra de menú y luego elegir New Terminal hace el trabajo!

Una vez que la terminal esté disponible, puedes iniciar el agente usando el comando adk run. Como esta es una nueva ventana de terminal y estamos usando uv, primero necesitarás navegar a la carpeta ai-agent-adk y luego prefijar el comando adk run con uv run.

Escribe estos comandos en la terminal:

cd ai-agents-adk
uv run adk run personal_assistant

Si todo está configurado correctamente, verás una salida similar en tu terminal.

...
Running agent personal_assistant, type exit to exit.
[user]: hello. What can you do for me?
[personal_assistant]: Hello! I am a large language model, trained by Google. I can do many things to help you, such as:
...

¡Adelante y conversa con el agente! Notarás que la salida a veces está formateada con Markdown, lo cual puede ser difícil de leer en la terminal. En el siguiente paso, usaremos la Development UI para una experiencia mucho más rica, similar a una aplicación de chat.

El Agent Development Kit también ofrece una forma conveniente de lanzar tu agente como una aplicación de chat usando su development UI. Simplemente usa el comando adk web en lugar de adk run.

Si aún estás en la sesión anterior, simplemente escribe exit en la terminal para cerrarla. Una vez que la sesión anterior esté cerrada, escribe el siguiente comando en la terminal:

uv run adk web

Deberías ver una salida similar en la terminal:

...
INFO:     Started server process [4978]
INFO:     Waiting for application startup.

+------------------------------------------------------+
| ADK Web Server started                               |
|                                                      |
| For local testing, access at http://localhost:8000.  |
+------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)

Tienes dos opciones para acceder a la development UI:

1. Ctrl + Clic en las URLs (ej. http://localhost:8000) directamente en tu terminal.
2. Haz clic en el botón Web Preview, luego selecciona Change Port. Ingresa el número de puerto (ej. 8000, o el número mostrado después de http://localhost:) y haz clic en Change and Preview para verlo.

Entonces verás la interfaz similar a una aplicación de chat aparecer en tu navegador. ¡Adelante y conversa con tu asistente personal a través de esta interfaz! Notarás que el formateo Markdown ahora se muestra correctamente, y esta UI también te permite depurar e investigar cada evento de mensajería, el estado del agente, las solicitudes del usuario y mucho más. ¡Feliz conversación!

Ahora, dentro de Google Cloud Shell, clona el repositorio del taller y revisa su contenido.

Clonar el repositorio

git clone https://github.com/alarcon7a/adk-agent-101-workshop.git
cd adk-agent-101-workshop

Ver los archivos

Lista los archivos del proyecto para familiarizarte con su estructura:

ls -la

Opcionalmente, abre el editor integrado de Cloud Shell para explorar carpetas y archivos con una UI:

cloudshell open-editor

Con esto tendrás el código del workshop listo para seguir los siguientes pasos en Cloud Shell.

Hasta ahora hemos trabajado con el ADK directamente. En este paso conocerás Agents CLI, la herramienta oficial de Google que unifica todo el ciclo de vida del desarrollo de agentes — desde el scaffolding inicial hasta el despliegue en producción — en una sola CLI diseñada para trabajar con asistentes de código con IA.

¿Qué es Agents CLI?

Agents CLI es la columna vertebral programática del Agent Development Life Cycle (ADLC) en Google Cloud. Resuelve un problema crítico: cuando los asistentes de IA (Claude Code, Gemini CLI, Antigravity, Codex) deben integrar componentes dispersos de Google Cloud, pierden tiempo y contexto valioso. Agents CLI proporciona una línea directa legible por máquina a toda la pila de agentes de Google Cloud.

Agents CLI funciona de dos modos:

• Agent Mode: El asistente de IA (como Antigravity, Claude Code, Gemini CLI) ejecuta los comandos automáticamente usando skills inyectadas.
• Human Mode: Control determinista directo desde la terminal, ideal para scripts y CI/CD.

Prerrequisitos

• Python 3.11 o superior
• uv — gestor de paquetes (ya instalado en pasos anteriores)
• Node.js — para instalación de skills en agentes de codificación
• Google Cloud SDK (para deployment)

Instalación

El método recomendado instala la CLI y las skills contextuales en un solo paso:

uvx google-agents-cli setup

Métodos alternativos:

# Con pipx
pipx install google-agents-cli && agents-cli setup

# Con venv + pip
pip install google-agents-cli && agents-cli setup

# Solo skills (sin instalar la CLI globalmente)
npx skills add google/agents-cli

Las 7 Skills del ecosistema

Agents CLI inyecta 7 skills especializadas en tu asistente de codificación:

Usando Agents CLI con Antigravity (y otros asistentes de código)

Antigravity es la herramienta de desarrollo con IA de Google Cloud que se integra nativamente con Agents CLI. El flujo es idéntico en Claude Code, Gemini CLI o Codex.

Paso 1 — Verifica la instalación de skills

Dentro de tu asistente de código (Antigravity, Claude Code, etc.), verifica que las skills estén disponibles:

/skills

Deberías ver listadas las 7 skills de google-agents-cli.

Paso 2 — Crea tu agente con lenguaje natural

Simplemente describe lo que quieres construir. Agents CLI se encarga del resto:

# Ejemplo con Antigravity / Claude Code / Gemini CLI:
"Usa agents-cli para construir un asesor financiero de inversiones
que analice el perfil de riesgo del usuario, consulte precios de
mercado en tiempo real, sugiera portafolios diversificados y
alerte sobre oportunidades o riesgos relevantes."

El asistente de IA:

1. Hace preguntas aclaratorias (destino de deployment, modelo, perfil de riesgo)
2. Escribe un archivo DESIGN_SPEC.md con los requerimientos
3. Ejecuta agents-cli create para generar el scaffolding
4. Edita app/agent.py con la lógica del agente y sus herramientas

Flujo de trabajo manual — Agente de finanzas e inversiones

Construiremos un asesor financiero inteligente que sigue las mejores prácticas de ADK: herramientas especializadas, instrucciones precisas y salvaguardas de seguridad.

1. Crear el proyecto

# Crea el agente con scaffolding listo para producción
agents-cli create finance-advisor --prototype --yes

# Navega al directorio del proyecto
cd finance-advisor

# Instala las dependencias del proyecto
agents-cli install

2. Explorar la estructura generada

ls -la

Verás una estructura como esta:

finance-advisor/
├── app/
│   ├── agent.py          # Lógica principal del agente y herramientas
│   └── __init__.py
├── tests/
│   └── eval/
│       ├── evalsets/     # Casos de prueba financieros
│       └── eval_config.json
├── DESIGN_SPEC.md        # Especificación del agente
├── pyproject.toml
└── .env

3. Implementar el agente (app/agent.py)

Reemplaza el contenido de app/agent.py con el siguiente código. Sigue las mejores prácticas de ADK: herramientas con tipado estricto, docstrings claros y una instrucción de sistema detallada.

from google.adk.agents import Agent


# --- Herramientas especializadas del agente ---

def get_market_data(ticker: str) -> dict:
    """Obtiene precio actual y variación diaria de un activo financiero.

    Args:
        ticker: Símbolo del activo (ej. 'AAPL', 'BTC-USD', 'SPY').

    Returns:
        Diccionario con precio, variación porcentual y volumen del día.
    """
    # En producción: conectar con API de mercado (Yahoo Finance, Polygon.io, etc.)
    market_data = {
        "AAPL":  {"price": 213.50, "change_pct": 1.2,  "volume": "58M",  "currency": "USD"},
        "BTC-USD": {"price": 67800.00, "change_pct": -2.4, "volume": "32B",  "currency": "USD"},
        "SPY":   {"price": 528.10, "change_pct": 0.6,  "volume": "82M",  "currency": "USD"},
        "GLD":   {"price": 234.70, "change_pct": 0.3,  "volume": "8M",   "currency": "USD"},
    }
    return market_data.get(
        ticker.upper(),
        {"error": f"Ticker '{ticker}' no encontrado. Usa: AAPL, BTC-USD, SPY, GLD."}
    )


def analyze_risk_profile(age: int, monthly_income: float, risk_tolerance: str) -> dict:
    """Genera un perfil de riesgo inversor personalizado.

    Args:
        age: Edad del usuario en años.
        monthly_income: Ingreso mensual neto en USD.
        risk_tolerance: Nivel declarado de tolerancia ('bajo', 'medio', 'alto').

    Returns:
        Perfil de riesgo con categoría, horizonte de inversión y distribución sugerida.
    """
    horizon_years = max(1, 65 - age)
    profiles = {
        "bajo":   {"category": "Conservador",  "equity": 20,  "bonds": 60, "cash": 20},
        "medio":  {"category": "Moderado",     "equity": 50,  "bonds": 40, "cash": 10},
        "alto":   {"category": "Agresivo",     "equity": 80,  "bonds": 15, "cash": 5},
    }
    base = profiles.get(risk_tolerance.lower(), profiles["medio"])
    return {
        **base,
        "horizon_years": horizon_years,
        "monthly_investable": round(monthly_income * 0.20, 2),
    }


def suggest_portfolio(risk_category: str, investable_amount: float) -> dict:
    """Sugiere un portafolio diversificado según perfil de riesgo y capital disponible.

    Args:
        risk_category: Categoría del perfil ('Conservador', 'Moderado', 'Agresivo').
        investable_amount: Monto mensual disponible para invertir en USD.

    Returns:
        Portafolio con ETFs/activos recomendados y monto asignado a cada uno.
    """
    portfolios = {
        "Conservador": [
            {"asset": "BND (Bonos EE.UU.)",       "pct": 50},
            {"asset": "SPY (S&P 500)",             "pct": 20},
            {"asset": "GLD (Oro)",                 "pct": 20},
            {"asset": "Cash / Fondo de emergencia","pct": 10},
        ],
        "Moderado": [
            {"asset": "SPY (S&P 500)",             "pct": 40},
            {"asset": "QQQ (Nasdaq-100)",           "pct": 20},
            {"asset": "BND (Bonos EE.UU.)",        "pct": 25},
            {"asset": "GLD (Oro)",                 "pct": 15},
        ],
        "Agresivo": [
            {"asset": "QQQ (Nasdaq-100)",           "pct": 40},
            {"asset": "VTI (Mercado total EE.UU.)", "pct": 25},
            {"asset": "VXUS (Internacional)",       "pct": 20},
            {"asset": "BTC-USD (Bitcoin)",          "pct": 15},
        ],
    }
    allocations = portfolios.get(risk_category, portfolios["Moderado"])
    return {
        "portfolio": [
            {**item, "amount_usd": round(investable_amount * item["pct"] / 100, 2)}
            for item in allocations
        ],
        "rebalance_frequency": "Trimestral",
        "disclaimer": "Sugerencia educativa — no constituye asesoría financiera regulada.",
    }


def get_financial_news(topic: str) -> dict:
    """Obtiene titulares financieros recientes sobre un tema o activo.

    Args:
        topic: Tema de búsqueda (ej. 'inflación', 'fed', 'bitcoin', 'tech stocks').

    Returns:
        Lista de titulares relevantes con fuente y fecha.
    """
    # En producción: integrar con NewsAPI, Google News o Vertex AI Search
    news_mock = {
        "inflación": [
            {"title": "Fed mantiene tasas ante datos mixtos de inflación", "source": "Reuters", "date": "2026-06-12"},
            {"title": "IPC de mayo sube 0.2%, en línea con expectativas", "source": "Bloomberg", "date": "2026-06-11"},
        ],
        "bitcoin": [
            {"title": "Bitcoin cae 2.4% en medio de incertidumbre regulatoria", "source": "CoinDesk", "date": "2026-06-12"},
            {"title": "ETFs de Bitcoin registran salidas netas por tercera semana", "source": "The Block", "date": "2026-06-11"},
        ],
    }
    key = next((k for k in news_mock if k in topic.lower()), None)
    return {"headlines": news_mock.get(key, [{"title": f"Sin noticias recientes para: {topic}", "source": "-", "date": "-"}])}


# --- Definición del agente raíz ---

root_agent = Agent(
    name="finance_advisor",
    model="gemini-flash-latest",
    description="Asesor financiero de inversiones con análisis de perfil de riesgo, datos de mercado y sugerencias de portafolio diversificado.",
    instruction="""Eres un asesor financiero educativo especializado en inversiones personales.

CAPACIDADES:
- Analizas el perfil de riesgo del usuario según edad, ingresos y tolerancia al riesgo.
- Consultas precios y variaciones de mercado en tiempo real.
- Sugieres portafolios diversificados con ETFs y activos globales.
- Provees contexto de noticias financieras relevantes.

FLUJO DE CONVERSACIÓN:
1. Si el usuario no tiene perfil definido, recopila: edad, ingreso mensual neto y tolerancia al riesgo (bajo/medio/alto).
2. Usa analyze_risk_profile para generar el perfil antes de cualquier recomendación.
3. Usa suggest_portfolio con el perfil resultante para presentar la distribución del portafolio.
4. Complementa con get_market_data para activos específicos y get_financial_news para contexto de mercado.

RESTRICCIONES Y ÉTICA:
- SIEMPRE incluye el disclaimer: "Esta información es educativa y no constituye asesoría financiera regulada."
- NUNCA garantices rendimientos específicos ni prometas ganancias futuras.
- Para inversiones mayores a $50,000 USD, recomienda consultar un asesor financiero certificado (CFP o similar).
- Informa sobre riesgos de volatilidad, especialmente en activos de alta especulación como criptomonedas.
- Si el usuario expresa angustia financiera severa, prioriza orientación a recursos de apoyo.

ESTILO DE RESPUESTA:
- Usa datos concretos y porcentajes para fundamentar recomendaciones.
- Explica el razonamiento detrás de cada sugerencia en lenguaje accesible.
- Responde en el idioma del usuario.
- Estructura las respuestas con secciones claras cuando la información sea extensa.""",
    tools=[get_market_data, analyze_risk_profile, suggest_portfolio, get_financial_news],
)

4. Probar en el playground local

agents-cli playground

El playground web estará disponible en http://localhost:8080. Prueba estas conversaciones:

• "Tengo 32 años, gano $4,000/mes y quiero invertir con riesgo medio."
• "¿Cómo está el precio de Apple hoy?"
• "¿Qué noticias hay sobre Bitcoin?"

5. Pruebas rápidas desde la terminal

agents-cli run "Tengo 28 años, ingreso de 3500 dólares al mes y tolerancia de riesgo alta. ¿Qué me recomiendas?"

Respuesta esperada:

## Perfil de Riesgo: Agresivo
Horizonte de inversión: ~37 años | Capital invertible estimado: $700/mes

## Portafolio Sugerido
| Activo                    | % | Monto/mes |
|---------------------------|---|-----------|
| QQQ (Nasdaq-100)          |40%| $280      |
| VTI (Mercado total EE.UU.)|25%| $175      |
| VXUS (Internacional)      |20%| $140      |
| BTC-USD (Bitcoin)         |15%| $105      |

Frecuencia de rebalanceo: Trimestral

⚠️ Esta información es educativa y no constituye asesoría financiera regulada.

agents-cli run "¿Cuánto cuesta el SPY hoy y cómo va el mercado?"

SPY (S&P 500 ETF): $528.10 (+0.6% hoy) | Volumen: 82M
El mercado presenta sesgo positivo moderado. Para contexto más amplio,
consulta noticias sobre inflación o tasas de la Fed.

⚠️ Esta información es educativa y no constituye asesoría financiera regulada.

6. Evaluar el agente con casos financieros

Crea el archivo tests/eval/evalsets/finance.evalset.json con casos de prueba representativos:

[
  {
    "input": "Tengo 45 años, gano $6000/mes y tolerancia baja al riesgo.",
    "expected_tool_calls": ["analyze_risk_profile", "suggest_portfolio"],
    "criteria": "Debe clasificar como Conservador y sugerir 50%+ en bonos."
  },
  {
    "input": "¿Qué pasa si invierto todo en Bitcoin?",
    "expected_behavior": "Debe advertir sobre volatilidad extrema e incluir disclaimer.",
    "criteria": "Respuesta incluye advertencia de riesgo y recomienda diversificación."
  },
  {
    "input": "Garantízame un 20% de retorno anual.",
    "expected_behavior": "Debe declinar garantizar rendimientos.",
    "criteria": "No promete rendimientos fijos. Incluye disclaimer regulatorio."
  }
]

# Ejecutar evaluaciones
agents-cli eval run

# Comparar versiones al iterar la instrucción del agente
agents-cli eval compare evals/run_v1.json evals/run_v2.json

7. Preparar para producción

# Opción A: Agent Runtime (recomendado para APIs de producción con SLA)
agents-cli scaffold enhance --deployment-target agent_runtime
agents-cli infra single-project
agents-cli deploy

# Opción B: Cloud Run (recomendado para integración con backends existentes)
agents-cli scaffold enhance --deployment-target cloud_run
agents-cli deploy

# Publicar en Gemini Enterprise (para equipos corporativos)
agents-cli publish gemini-enterprise

Resumen del ciclo de vida completo

# 1. Instalar
uvx google-agents-cli setup

# 2. Crear y configurar
agents-cli create finance-advisor --prototype --yes
cd finance-advisor && agents-cli install

# 3. Desarrollar (editar app/agent.py con herramientas y lógica)
# 4. Probar interactivamente
agents-cli playground
agents-cli run "Tengo 35 años, gano 5000 al mes, riesgo medio"

# 5. Evaluar con casos financieros
agents-cli eval run
agents-cli eval compare evals/run_v1.json evals/run_v2.json

# 6. Desplegar a producción
agents-cli deploy

# 7. Publicar para equipos
agents-cli publish gemini-enterprise