Google ADK para TypeScript

Los agentes de IA dejaron de ser un experimento. Ya están en producción en soporte al cliente, análisis de datos, automatización de procesos, y cada semana aparece un caso de uso nuevo. El problema es que construirlos con las APIs crudas de los LLMs no escala: terminás con prompts gigantes, lógica de orquestación mezclada con lógica de negocio, y un sistema casi imposible de testear.

Google ADK (Agent Development Kit) es la respuesta de Google a este problema. En este post arrancamos una serie de ocho partes donde vamos a aprender sobre ADK usando como ejemplo un asesor financiero personal completo con siete agentes especializados y veintinueve herramientas.

Qué es ADK

ADK es un framework open-source para construir sistemas de agentes de IA. La propuesta central es darte las herramientas para que puedas componer agentes complejos sin reinventar la rueda.

Los tres conceptos centrales son:

• Agent — La unidad que piensa y actúa. Tiene un modelo, instrucciones, y puede usar herramientas.
• Tool — La interfaz entre el agente y el mundo real. Una función tipada que el LLM puede invocar.
• Runner / Session — El motor que gestiona el ciclo de ejecución y el estado de la conversación.

La arquitectura básica se ve así:

Usuario → Runner → Agent → LLM
                     ↑
                   Tools (funciones TypeScript tipadas)

El LLM lee el schema de las herramientas disponibles, decide cuál invocar según el contexto, y el framework se encarga del ciclo de tool-call → resultado → siguiente paso.

Por qué ADK y no otra cosa

La pregunta válida es: ¿por qué no usar LangChain, LlamaIndex, o simplemente la API de Gemini directo?

API cruda: Funciona perfecto para casos simples. En cuanto necesitás múltiples herramientas, estado de conversación, y varios agentes coordinándose, la complejidad explota. Terminás escribiendo tu propio mini-framework.

LangChain/LangGraph: Maduro, tiene ecosistema. Pero si vas a usar Gemini de todas formas, ADK tiene integración nativa más ajustada, y la abstracción de LangChain a veces agrega capas que complican el debugging.

AutoGen (Microsoft): Orientado a flujos multi-agente conversacionales. Muy poderoso para casos donde los agentes "hablan entre sí", pero la curva de entrada es más alta.

ADK: Diseñado específicamente para el stack de Google (Gemini, Vertex AI, Cloud Run). Tiene soporte en diferentes lenguajes como golang, Python, Java y TypeScript. Modelo de herramientas simple y predecible. La DX es buena — tiene un servidor web de desarrollo incluido que te ahorra mucho tiempo.

Bajando un poco todo esto en una tabla:

Los herramientas que vas a usar el 90% del tiempo

LlmAgent

El bloque fundamental. Un agente tiene un modelo, un nombre, instrucciones, herramientas, y opcionalmente sub-agentes.

import { LlmAgent } from '@google/adk';

const agent = new LlmAgent({
  name: 'budget_agent',
  model: 'gemini-3-flash-preview',
  description: 'Analiza presupuestos y gastos mensuales',
  instruction: `Sos un experto en finanzas personales...`,
  tools: [analyzeBudgetTool, findSavingsOpportunitiesTool],
});

El campo description no es decorativo — es lo que el agente orquestador lee para decidir si delegar a este agente. Veremos mas de esto en los siguientes posts.

FunctionTool

La interfaz entre el agente y código real. Usás Zod para el schema (que ADK convierte automáticamente a JSON Schema para el LLM) y una función execute que hace el trabajo.

import { FunctionTool } from '@google/adk';
import { z } from 'zod';

const analyzeBudgetTool = new FunctionTool({
  name: 'analyze_budget',
  description:
    'Analiza ingresos y gastos. Retorna métricas y comparación con regla 50/30/20.',
  parameters: z.object({
    monthlyIncome: z.number().describe('Ingresos mensuales en USD'),
    expenses: z.array(
      z.object({
        category: z.string(),
        amount: z.number(),
      })
    ),
  }),
  execute: ({ monthlyIncome, expenses }) => {
    // lógica TypeScript normal. En este caso hardcoded a modod de ejemplo.
    return { savingsRate: '18.5%', verdict: 'On track' };
  },
});

El entrypoint: src/agent.ts

ADK espera un archivo que exporte el agente raíz como rootAgent. Esa convención es lo que el CLI y el servidor de desarrollo usan para arrancar.

// src/agent.ts
export const rootAgent = new LlmAgent({ ... });

El proyecto de ejemplo

A lo largo de esta serie vamos a armar un FinancialAdvisorAI, un asesor financiero personal completo construido con ADK. La arquitectura:

financial_advisor (orquestador raíz)
├── budget_savings_agent          → presupuesto, ahorro, fondo de emergencia
├── investment_research_agent     → screener de ETFs, análisis de mercado
├── portfolio_manager_agent       → análisis de cartera, rebalanceo
├── goal_planner_agent            → jubilación, compra de casa, FIRE
├── risk_assessment_agent         → perfil de riesgo, stress testing
├── stock_research_agent          → análisis fundamental, ratings de analistas
└── personal_investment_advisor   → plan personalizado, estrategia fiscal

Siete agentes, veintinueve herramientas, un sistema que en producción reemplazaría fácilmente la primera consulta con un asesor financiero.

Lo interesante desde el punto de vista de arquitectura: el orquestador no tiene ninguna herramienta propia. Su único trabajo es entender la intención del usuario y delegar al especialista correcto. El LLM hace el routing, vos lo guiás con instrucciones claras.

El modelo de ejecución

Cuando el usuario manda un mensaje, el ciclo es:

1. Runner recibe el mensaje y lo pasa al agente raíz
2. El LLM (Gemini 3 Flash Preview en nuestro caso) recibe el contexto: instrucciones del sistema + historial + schemas de herramientas disponibles
3. El LLM decide: responder directamente, invocar una herramienta, o delegar a un sub-agente
4. Si hay delegación, el sub-agente tiene su propio ciclo con sus propias herramientas
5. El resultado vuelve al orquestador que formula la respuesta final

Lo que ADK abstrae es todo el ciclo de tool-call parsing, invocación, manejo de errores, y gestión del estado de conversación entre turnos.

Lo que viene en la serie

El código completo del proyecto está en nbellocam/adk-financial-advisor. En cada post vamos a linkear al estado del repo en ese momento para que puedas seguirlo en contexto. El punto de partida de esta serie es el commit inicial con la estructura base del agente.