Cómo crear tu primer agente con Google ADK usando Firebase Genkit

Qué es Google ADK (Genkit) y por qué usarlo

Firebase Genkit actúa como un “Agent Development Kit” real: estructura agentes como Flows tipados, soporta tool calling, ofrece trazabilidad (traces) y facilita deploy serverless en Firebase/Cloud Run. No es un playground: es ingeniería.

Beneficios clave

• Flows tipados (Zod) para entradas/salidas.
• Tools como interfaces a APIs o DBs.
• Trace UI para tokens, latencias y llamadas a herramientas.
• Deploy automático a Firebase Functions/Cloud Run.

Requisitos rápidos

• Node.js 20+
• Firebase CLI: npm i -g firebase-tools y firebase login
• Proyecto Google Cloud con facturación habilitada para Vertex AI (si usas Gemini)
• Opcional: Docker para ejecutar dev UI local

Referencias: Vertex AI, Genkit repo.

Paso 1 — Inicializa el scaffold (2–5 minutos)

Crea el proyecto y usa el inicializador de genkit:

mkdir mi-agente-genkit
cd mi-agente-genkit
npx genkit init

El asistente te pedirá TypeScript y proveedor de modelo (Vertex AI / Gemini). Genera estructura con src/ y genkit.config.ts. Guarda las claves de API en variables de entorno, nunca en el repo.

Paso 2 — Define el Flow: contrato y handler

En Genkit un agente es un Flow: entrada validada, salida validada, handler con lógica y llamadas a herramientas. Usa Zod para evitar parsing frágil.

Ejemplo mínimo

import { genkit } from '@genkit-ai/core';
import { z } from 'zod';
import { gemini15Flash } from '@genkit-ai/googleai';

const sdk = genkit({ /* config */ });

const In = z.object({ code: z.string(), language: z.enum(['typescript','python','go']) });
const Out = z.object({ suggestion: z.string(), risk: z.enum(['LOW','MEDIUM','HIGH']) });

export const codeRefactorAgent = sdk.defineFlow(
  { name: 'codeRefactor', inputSchema: In, outputSchema: Out },
  async (input) => {
    const prompt = `Actúa como Staff Engineer... analiza este código...`;
    const resp = await sdk.generate({
      model: gemini15Flash,
      prompt,
      output: { format: 'json', schema: Out }
    });
    return resp.output(); // validado por schema
  }
);

Puntos técnicos

Usa output: { format: 'json', schema } para minimizar hallucinations estructurales; valida todo en entrada; añade timeouts/try‑catch.

Paso 3 — Añade Tools (llamadas externas controladas)

Tools son funciones que el LLM puede invocar para consultar docs, bases de datos o sistemas internos.

Ejemplo de tool para buscar en npm registry

const npmSearch = sdk.defineTool({
  name: 'npmSearch',
  inputSchema: z.object({ q: z.string() }),
  outputSchema: z.object({ name: z.string(), version: z.string(), desc: z.string() }),
  call: async ({ q }) => {
    const r = await fetch(`https://registry.npmjs.org/-/v1/search?text=${q}`);
    const json = await r.json();
    return json.objects[0].package;
  }
});

El modelo decide cuándo invocar la tool; Genkit ejecuta la función y retorna el resultado al LLM. Esto mantiene seguridad y auditabilidad.

Paso 4 — Dev UI y pruebas automáticas

Dev UI

Levanta la UI local: npx genkit start. En localhost:4000:

• Ejecuta flows con JSON.
• Inspecciona traces: prompt final, tool calls, tokens y latencia.
• Guarda artifacts (diffs, screenshots) para auditoría.

Pruebas automáticas

Integra tests unitarios: mockea respuestas de tools y valida que el Flow cumple output schema. Automatiza en CI.

Paso 5 — Deploy y orquestación

Exporta el Flow como función HTTP y despliega

1. firebase init functions
2. Importa y exporta el Flow en functions/src/index.ts.
3. firebase deploy --only functions

Orquestación empresarial

Para orquestación empresarial conecta el endpoint a n8n o un workflow manager: n8n → HTTP Request → parse → branch por riesgo.

Limitaciones y criterios para migrar

Usa Genkit cuando:

• Necesitas trazabilidad, tests y tool calling.
• Quieres despliegue serverless rápido.

Migra a código tradicional si

• La lógica es intensiva en CPU/GPU (procesamiento batch).
• Tienes requisitos de latencia estrictos o compliance que impiden servicios cloud gestionados.
• Coste por token/despliegue supera reescribir servicio en microservicios.

Métrica práctica: si tu agente supera 5–10k invocaciones/mes o la fricción en coste/latencia aumenta, planifica migración.

Buenas prácticas operativas

• Principio de menor privilegio para tools y claves.
• Versiona prompts como código y mantén changelogs.
• Define SLAs y monitorea latencia, tasa de errores y ratio de respuestas estructuradas válidas.
• Implementa fallback humano para casos de riesgo alto.

Conclusión

Saber cómo crear tu primer agente con Google ADK (Genkit) significa pensar en agentes como software: flujos tipados, herramientas controladas, pruebas y trazabilidad. Genkit transforma experimentos en sistemas desplegables y auditables; úsalo para prototipos robustos y como base técnica antes de escalar. Recursos y docs: Genkit, Vertex AI, repo.

Dominicode Labs

Si trabajas en automatización, agentes o workflows y buscas recursos prácticos y experimentos aplicados, revisa Dominicode Labs. Es una continuación lógica para prototipos técnicos y pruebas de integración.