Google ADK OpenRouter: Usa Cualquier Modelo en tu Agente IA

El camino de Google ADK con OpenRouter es un cambio de una línea: envuelve el modelo en LiteLlm y deja todo lo demás igual. Si seguiste construye tu primer agente ADK con búsqueda Tavily y memoria y acabaste en Gemini, puedes apuntar el mismo agente a cualquiera de los 462 modelos de OpenRouter reescribiendo el parámetro model=. Las herramientas, la memoria de sesión y el Runner quedan intactos.

El Google Agent Development Kit (ADK) se ha movido desde aquel primer artículo. Python llegó a v1.0.0 GA en mayo de 2025, v2.0.0 GA en mayo de 2026 con flujo multi-agente y soporte de grafos, y v2.12.0 el 2026-10-13. Ahora hay variantes en TypeScript, Go, Java y Kotlin junto a Python, y el repo ronda las 21.9k estrellas en GitHub. Lo que no ha cambiado es la capa de modelo: los modelos de Google aceptan un string de modelo directo, todo lo demás pasa por clases wrapper como LiteLlm, que habla con LiteLLM y sus más de 100 proveedores. El patrón de intercambio de abajo funciona igual en 2.x.

La guía cubre un pin de seguridad a aplicar antes de instalar nada, cómo se tarifan el catálogo de OpenRouter y sus variantes :free/:batch, la configuración solo por entorno, pasos de verificación que cazan IDs de modelo muertos antes que tu agente, y los modos de fallo que conviene conocer. Una clave API, 462 modelos, pago por token desde unos $0.02 por 1M de tokens de entrada.

Seguridad LiteLLM: fija litellm>=1.84 antes de instalar

El 24 de marzo de 2026 se encontró código no autorizado en LiteLLM v1.82.7 y v1.82.8 publicadas en PyPI. Es un incidente de cadena de suministro, no un error de configuración. Si instalaste o actualizaste LiteLLM en esa ventana, ese código corrió en tu máquina con acceso a lo que hubiera en tu entorno. La documentación de ADK de Google ahora exige litellm>=1.84 y dice a los afectados que roten sus secretos.

Tres hábitos a adoptar antes de los pasos de instalación de más abajo:

Fuentes: la página de integración de LiteLLM de ADK y la actualización de seguridad de LiteLLM de marzo de 2026. Trata el pin como política permanente para este stack, no como arreglo puntual.

¿Qué es OpenRouter? Una clave API, 462 modelos

OpenRouter es un único endpoint compatible con OpenAI, https://openrouter.ai/api/v1, delante de un gran catálogo de modelos: 462 modelos en la API a octubre de 2026. Una sola clave API los paga a todos, por token. No malabareas con SDKs separados, páginas de facturación o auth específica de cada proveedor. La cifra se mueve, así que revisa la lista en vivo antes de comprometer un agente a un ID concreto.

LiteLLM es el puente. El wrapper LiteLlm de ADK habla con LiteLLM, y LiteLLM habla OpenRouter bajo el prefijo de proveedor openrouter/. Esa es toda la integración. Detalles en la siguiente sección.

Ventajas de OpenRouter para agentes Google ADK

Variantes de modelos gratis (:free) y batch (:batch)

Unos 15 modelos llevan el sufijo :free, por ejemplo meta-llama/llama-3.3-70b-instruct:free. No cuestan nada y están limitados en tasa, lo que los hace bien para curiosear la API y malos para cualquier cosa de la que dependas. También hay variantes :batch con descuento para cargas asíncronas donde la latencia no importa.

Cómo funciona LiteLlm en Google ADK

Cómo Google ADK enruta un modelo OpenRouter a través del wrapper LiteLlm

La capa de modelo de ADK es de doble camino, y la división es simple. Gemini y otros modelos de Google aceptan un string directo como gemini-2.5-flash, manejado por el cliente google-genai. Todo lo demás pasa por una clase wrapper. LiteLlm es el wrapper para proveedores compatibles con OpenAI, y OpenRouter es uno de ellos.

from google.adk.models.lite_llm import LiteLlm

model = LiteLlm(model="openrouter/openai/gpt-5.6-luna")

El constructor pasa sus argumentos con nombre directamente a litellm.completion(). Lo que LiteLLM acepta, LiteLlm lo acepta. Por eso el wrapper es fino y por eso el formato del string de modelo es el de LiteLLM, no el de ADK: openrouter/<vendor>/<model>, donde <vendor>/<model> es exactamente el ID de la API de modelos de OpenRouter. Para openai/gpt-5.6-luna el string completo es openrouter/openai/gpt-5.6-luna. Copia el ID de la respuesta de la API, no de posts de blogs, y la aritmética de prefijos se encarga sola.

Config solo por entorno: elimina api_key y api_base

LiteLLM lee OPENROUTER_API_KEY del entorno por su cuenta y usa por defecto la URL base https://openrouter.ai/api/v1. Pasar ambos como kwargs aún funciona, solo es ruido. Yo mantendría el string de modelo como único argumento y dejaría que el entorno haga el resto.

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm

root_agent = Agent(
    name="my_adk_agent_openrouter",
    model=LiteLlm(model="openrouter/openai/gpt-5.6-luna"),
    description="A helpful assistant using an OpenRouter model, with web search and memory.",
    instruction="Answer helpfully. Use tools when they are relevant.",
    tools=[adk_tavily_tool, remember_something],
)

import os

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm

root_agent = Agent(
    name="my_adk_agent_openrouter",
    model=LiteLlm(
        model="openrouter/openai/gpt-5.6-luna",
        api_key=os.getenv("OPENROUTER_API_KEY"),
        api_base="https://openrouter.ai/api/v1",
    ),
    description="A helpful assistant using an OpenRouter model, with web search and memory.",
    instruction="Answer helpfully. Use tools when they are relevant.",
    tools=[adk_tavily_tool, remember_something],
)

Un extra opcional: las cabeceras de atribución de OpenRouter. LiteLLM expone OR_SITE_URL y OR_APP_NAME como variables de entorno para que tu app aparezca en los rankings de OpenRouter. Los nombres de cabecera del lado de OpenRouter pasaron a HTTP-Referer y X-OpenRouter-*, así que confirma el mapeo en los docs de LiteLLM si la atribución te importa.

Usa strings nativos de Gemini para Gemini

El streaming se gestiona por ti. La clase LiteLlm y el Runner manejan el stream internamente y eliminan cualquier kwarg stream que pases, así que no construyas tu punto de llamada alrededor de él.

Tool calling y bloques thinking de Claude

LiteLLM reenvía las llamadas a funciones para los modelos que las soportan. Eso es lo que mantiene funcionando la herramienta de búsqueda Tavily y remember_something tras cambiar el modelo. Dos detalles que conviene saber:

• Desde ADK v1.28.0, LiteLlm conserva las firmas de thinking-block de Anthropic entre turnos cuando corres modelos Claude. Tienes la continuidad de razonamiento multi-turno sin código extra.
• ADK ahora repara JSON de tool-call malformado de modelos inestables (_parse_tool_call_arguments en lite_llm.py). No convierte un modelo débil en fuerte. Si tu agente produce llamadas rotas, elige un modelo con soporte sólido de function-calling en vez de culpar a ADK.

El tool calling es también por lo que protocolos como qué es MCP (Model Context Protocol) importan a medida que tu agente crece: la capacidad del modelo de emitir llamadas bien formadas es el cuello de botella, no tu código de herramientas.

Cambia tu agente ADK a un modelo OpenRouter (paso a paso)

El recorrido de abajo evoluciona el agente de la parte 1, con búsqueda Tavily y la herramienta remember_something, hacia un modelo OpenRouter. Cada paso tiene una línea de verificación. Úsala.

Prerequisitos

1. Consigue una clave API de OpenRouter y actualiza .env

Crea una clave en openrouter.ai/keys. Tiene pinta de sk-or-v1-.... Ponla en el .env de la raíz de tu proyecto:

# Nueva línea
OPENROUTER_API_KEY="sk-or-v1-PASTE_YOUR_KEY_HERE"

# Mantén lo que aún necesites
TAVILY_API_KEY="YOUR_TAVILY_API_KEY"
# GOOGLE_API_KEY="YOUR_GOOGLE_API_KEY"  # quítala si ya nada usa Gemini

Verifica:

curl -s https://openrouter.ai/api/v1/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

Una salida sana es un objeto JSON con la etiqueta de tu clave y los créditos restantes. Si obtienes 401, la clave está mal, falta, o no está cargada en tu shell.

2. Instala LiteLLM con uv (versión fijada)

uv add "litellm>=1.84"

Esa restricción es deliberada. LiteLLM 1.82.7/1.82.8 fueron las releases comprometidas del incidente de marzo de 2026, y los docs de ADK ahora exigen >=1.84. La última versión actual es 1.105.1 a octubre de 2026. Commitea uv.lock en el mismo cambio. Si uv aún es nuevo en tu flujo, Primeros pasos con uv para proyectos Python cubre la configuración del proyecto y lockfiles.

Verifica:

uv tree | grep litellm

Quieres una versión igual o superior a 1.84. Cualquier cosa menor, para y reejecuta el add con el pin.

3. Actualiza el código del agente con LiteLlm

Reemplazo directo de la definición de root_agent de la parte 1:

from google.adk.agents import Agent
from google.adk.models.lite_llm import LiteLlm

root_agent = Agent(
    name="my_adk_agent_openrouter",
    model=LiteLlm(
        model="openrouter/openai/gpt-5.6-luna",
        # No hacen falta api_key/api_base: LiteLLM lee OPENROUTER_API_KEY del
        # entorno y usa por defecto la URL base
        # https://openrouter.ai/api/v1
    ),
    description="A helpful assistant using an OpenRouter model, with web search and memory.",
    instruction="""You are a friendly and helpful assistant.
1. For anything needing up-to-date info, use the 'TavilySearchResults' tool.
2. To remember something, use the 'remember_something' tool.
3. Use session state memories when relevant.
4. Otherwise answer directly.""",
    tools=[adk_tavily_tool, remember_something],
)

Qué cambió y qué no:

• El parámetro model ahora es una instancia de LiteLlm en vez de un string Gemini directo como "gemini-2.5-flash".
• El string de dentro es openrouter/<vendor>/<model>. Vendor y model vienen directos de la API de modelos de OpenRouter, así que openai/gpt-5.6-luna se convierte en openrouter/openai/gpt-5.6-luna. Un prefijo, sin duplicar.
• tools, instruction, Runner y InMemorySessionService quedan intactos. Ese es el punto del wrapper.

Verifica: primero una comprobación a nivel de sintaxis.

uv run python -c "from agent_module.agent import root_agent; print(root_agent.model)"

Ajusta agent_module.agent a tu ruta de módulo real. Quieres ver el objeto LiteLlm impreso, no un ImportError.

4. Ejecuta el agente con adk web

adk web

o ejecuta tu script directamente:

uv run python -m agent_module.agent

Verifica: el agente responde y se dispara una llamada a herramienta. Pregunta “¿cuáles son las últimas noticias sobre la EU AI Act?” y observa la dev UI o el terminal. Si solo obtienes una respuesta de texto sin invocación de Tavily, el modelo no está llamando herramientas. Mira resolución de problemas abajo.

Fallos comunes al ejecutar: puerto 8000 ya en uso significa que un adk web viejo sigue corriendo; mátalo y reintenta. Las claves que faltan suelen significar que arrancaste el comando fuera de la raíz del proyecto y el .env nunca se cargó.

Verifica que el modelo OpenRouter funciona antes de celebrar

Los IDs de modelo rotan semanalmente. Los errores de tecleo y los IDs retirados devuelven 404, y es mucho más rápido cazarlo en curl que dentro del stack trace de ADK. Corre estas cuatro comprobaciones en orden.

1. La clave es válida y puedes ver créditos:

curl -s https://openrouter.ai/api/v1/key \
  -H "Authorization: Bearer $OPENROUTER_API_KEY"

2. El ID del modelo existe:

curl -s https://openrouter.ai/api/v1/models | jq -r '.data[].id' | grep gpt-5.6-luna

Salida vacía significa que el ID está mal o el modelo ya no está. Elige otro de la lista completa.

3. Una completion barata de extremo a extremo:

curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"openai/gpt-5.6-luna","messages":[{"role":"user","content":"say ok"}],"max_tokens":10}'

Quieres una completion corta de vuelta. 401 es auth, 404 es ID de modelo, 429 es rate limit o sin créditos.

4. Prueba de humo de tool-call a través de adk web: haz una pregunta que fuerce Tavily y confirma que aparece la invocación de herramienta, no solo la respuesta.

Eligiendo un modelo OpenRouter: precios y soporte de herramientas

Los precios de abajo se sacaron de la API de OpenRouter en octubre de 2026. Se mueven, a veces semanalmente. Revísalos antes de presupuestar en torno a ellos.

Notas sobre la tabla: z-ai/glm-5.3 está disponible a través de OpenRouter, o directo desde GLM 5.3 en Z.ai si prefieres saltarte el gateway. Para la fila de moonshotai/kimi-k3, el artículo más viejo Kimi K2 en 2026 y qué usar ahora cubre cómo evolucionó esa familia. Y si el precio sub-$1/M-token es todo el juego para ti, la lista de los modelos de IA más baratos por debajo de $1 por millón de tokens profundiza más que una tabla.

Antes de comprometer un agente a un modelo, comprueba explícitamente el soporte de function-calling:

curl -s https://openrouter.ai/api/v1/models \
  | jq '.data[] | select(.id=="openai/gpt-5.6-luna") | .supported_parameters'

La salida debe contener tools. Un modelo sin ello responderá preguntas e ignorará silenciosamente tus funciones, lo que parece un bug de ADK y no lo es.

Para opciones open-weight que aguantan en cargas de agentes, mira las mejores alternativas de LLMs open source a Claude y GPT.

Resolución de errores de Google ADK OpenRouter

Control de costes y failover de modelos

Pon un límite de crédito duro en cada clave de OpenRouter al crearla. El dashboard de actividad y el endpoint /api/v1/key muestran el gasto, y ambos tardan segundos en comprobarse. Para trabajo asíncrono, las variantes :batch descuentan los mismos modelos cuando la latencia es irrelevante.

Orden de magnitud de coste: un agente personal ligero en deepseek/deepseek-v4.1-flash cae en el rango de céntimos a unos pocos dólares al mes a uso de hobby. Un flujo pesado con anthropic/claude-sonnet-5.5 es en el que hay que poner límite, porque $10/1M de tokens de salida suma rápido cuando un agente itera sobre llamadas a herramientas.

En Python hoy, el failover es trabajo de LiteLLM, no de ADK. Pasa fallbacks a la llamada de completion y obtienes una cadena definida de primario a secundario en vez de un agente muerto cuando el primer modelo devuelve 429:

from litellm import completion

resp = completion(
    model="openrouter/openai/gpt-5.6-luna",
    messages=[{"role": "user", "content": "say ok"}],
    fallbacks=[
        {"model": "openrouter/deepseek/deepseek-v4.1-flash"},
        {"model": "openrouter/anthropic/claude-sonnet-5.5"},
    ],
)

La propia respuesta de ADK al enrutado por petición es RoutedLlm/RoutedAgent, que elige un modelo y hace failover en caso de error. Eso es solo TypeScript y experimental ahora mismo, así que en Python el router de LiteLLM y los fallbacks son el valor predeterminado fiable y aburrido.

Si también vives en Claude Code, Codex o Gemini CLI, Agent Router para enrutado multi-modelo te da el mismo patrón de cualquier-modelo para agentes de codificación.

Conclusión

El intercambio es una línea: LiteLlm(model="openrouter/<vendor>/<model>"). Mantén el pin (litellm>=1.84), mantén tu lockfile, y corre las cuatro comprobaciones de verificación antes de confiar en cualquier ID de modelo nuevo para ti. Las herramientas y la memoria de sesión nunca cambian, que es lo que hace barata la rotación de modelos.

Siguiente en la serie: el equipo de investigación multi-agente ADK con Tavily y Crawl4AI, donde varios agentes reparten el trabajo de investigación en vez de hacerlo todo uno.

La misma idea de cualquier-modelo aparece en otros sitios: cómo conectar cualquier modelo a la app Codex lo cubre para herramientas de codificación. Y si quieres otro framework de agentes Python con el que comparar ADK, primeros pasos con agentes Agno es un buen desvío.