Construye un agente de IA en TypeScript: stack mínimo para 2026
DominicodeEl stack mínimo para un agente de IA en TypeScript en 2026
Tiempo estimado de lectura: 4 min
Ideas clave
- Anthropic SDK + Zod + tsx + dotenv es la combinación práctica para agentes en producción: observabilidad, tipado y control.
- Zod como frontera: declara schemas de herramientas, valida args y convierte a JSON Schema para pasar al modelo.
- Bucle explícito: orquesta tool-calls en un único proceso, limita iteraciones y registra cada uso.
- No es minimalismo estético: es técnica operativa para que el equipo pueda depurar y reparar a cualquier hora.
- Escala solo cuando métricas y requisitos lo exijan: añade memoria, orquestadores o trazas distribuidas según necesidad.
Tabla de contenidos
- Introducción
- Resumen rápido (lectores con prisa)
- tsx + dotenv — entorno y secretos
- Anthropic SDK — motor cognitivo directo
- Zod — contrato entre texto probabilístico y tipos
- Por qué este stack vence en producción (ejemplos técnicos)
- El patrón de implementación: el loop explícito
- Validación práctica y contratos: ejemplo de herramientas
- Qué no cubre este stack y cuándo añadir componentes
- Reglas operativas antes de desplegar
- Conclusión práctica
- Dominicode Labs
- FAQ
El stack mínimo propuesto es una combinación práctica y limitada de dependencias enfocadas a reducir superficie de fallo, mantener trazabilidad y controlar consumo de tokens: Anthropic SDK para el motor, Zod para contratos, tsx para ejecución TypeScript rápida y dotenv para gestionar secretos.
Resumen rápido (lectores con prisa)
Stack: Anthropic SDK + Zod + tsx + dotenv. Usa Zod para declarar y validar schemas de herramientas, convierte Zod a JSON Schema para pasárselo al modelo y orquesta tool-calls en un bucle explícito. Añade PostgreSQL+pgvector, orquestadores o trazas solo cuando lo exijan métricas y requisitos.
tsx + dotenv — entorno y secretos
tsx te permite ejecutar TypeScript directamente en Node sin compilar manualmente. En desarrollo y CI rápidos esto reduce ciclos de retroalimentación.
dotenv mantiene las claves fuera del repo: ANTHROPIC_API_KEY, DATABASE_URL, etc. Ambos son higiene operativa, no glamour.
Anthropic SDK — motor cognitivo directo
Usa el SDK oficial: Anthropic SDK. Evita enrutadores genéricos que suavizan diferencias entre modelos y esconden comportamientos de tool-calling. Anthropic devuelve explícitamente cuándo el modelo quiere invocar una herramienta; tú ejecutas la función y devuelves el resultado, con control total del flujo.
Zod — contrato entre texto probabilístico y tipos
Zod es la frontera. Define los schemas de herramientas y valida los argumentos que el modelo genera. Convierte Zod a JSON Schema con zod-to-json-schema para declarar las herramientas al modelo. Resultado: menor tasa de alucinaciones en tool_use y errores tipo detectables y manejables.
Por qué este stack vence en producción (ejemplos técnicos)
1) Trazabilidad total
Cuando el modelo pide usar una herramienta, el SDK devuelve nombre + args. Antes de ejecutar, haces schema.safeParse(args). Si falla, capturas el error, lo loggeas y agregas ese fallo al historial que reenvías al modelo. No hay retries automáticos “mágicos” que oculten la causa.
2) Menor latencia y coste
Un único proceso que orquesta tool-calls evita encadenados innecesarios. Si cada handoff fuera otra llamada LLM, multiplicas tokens y TTFT. Con un loop explícito controlas el número máximo de iteraciones y evitas bucles de cortesía.
3) Menos superficie de bugs
Las capas extra (framework + adaptadores) introducen incompatibilidades y reintentos implícitos. Tener cuatro dependencias estables reduce puntos de falla.
El patrón de implementación: el loop explícito
Escribes un bucle claro. Pseudodiagrama:
- Inicializar cliente Anthropic con la API key desde dotenv.
- Preparar mensajes (system + user + tool_history).
- Llamar a client.messages.create(…) con tool definitions derivadas de Zod.
- Si respuesta es texto → devolver.
- Si respuesta es tool_use → validar con Zod; si válido ejecutar función; añadir resultado al historial; repetir.
Ese flujo se implementa en 30–80 líneas y es 100% controlable. No es necesario heredar de clases ni integrar callbacks crípticos.
Validación práctica y contratos: ejemplo de herramientas
Define una tool con Zod:
- ticketId: z.string().regex(/^[A-Z]+-\d+$/) - includeComments: z.boolean().default(false)
Convierte esto a JSON Schema y pásalo a Anthropic. Cuando el LLM devuelva args, safeParse te dice inmediatamente si se puede ejecutar. Si no, devuelves el error al modelo como contexto y le pides corrección. Ese patrón reduce las llamadas inválidas y mejora la seguridad.
Qué no cubre este stack y cuándo añadir componentes
- Memoria de largo plazo: integra PostgreSQL + pgvector si necesitas retrieval persistente.
- Flujos empresariales largos (days/weeks): añade un orquestador (n8n o LangGraph) para persistencia de estado y control de aprobaciones humanas.
- Observabilidad distribuida: añade OpenTelemetry o similar si tu cluster requiere trazas correlacionadas a escala.
Empieza simple; añade estas piezas solo con datos que demuestren necesidad.
Reglas operativas antes de desplegar
- Nunca expongas una herramienta sin Zod schema.
- Registra cada tool_use y su validación. Logs estructurados; no texto plano.
- Limita iteraciones del loop por petición (por ejemplo, max 5 reintentos).
- Implementa el patrón Result (ok/error) en todas las funciones ejecutadas por el agente.
Conclusión práctica
El stack mínimo para un agente de IA en TypeScript en 2026 devuelve poder al equipo de ingeniería: trazabilidad, tipos y control operativo. Para la mayoría de agentes productivos —consultas a APIs, limpieza de datos, consultas SQL parametrizadas— esta pila es suficiente y más fiable que una montaña de frameworks. Escala solo cuando las métricas (latencia, coste por token, fallos en producción) y los requisitos (memoria, durabilidad) lo exijan. Así evitas añadir complejidad por moda y mantienes un sistema que puedas entender, auditar y mejorar.
Dominicode Labs
Para quienes construyen agentes y workflows, una referencia útil y complementaria sobre prácticas operativas y plantillas de integración está disponible en Dominicode Labs. Considera consultarlo como continuación lógica al patrón de loop explícito y validación con Zod.
FAQ
- ¿Por qué usar Anthropic SDK en vez de adaptadores genéricos?
- ¿Cuál es el papel exacto de Zod en este stack?
- ¿Necesito tsx en producción?
- ¿Cómo reducir costes de tokens con este patrón?
- ¿Cuándo añadir базы de datos y vectores (pgvector)?
- ¿Qué límites de seguridad operativa aplicar al expositor de herramientas?
¿Por qué usar Anthropic SDK en vez de adaptadores genéricos?
Porque el SDK oficial expone el comportamiento nativo del modelo (por ejemplo, tool_use) sin abstracciones que oculten diferencias entre modelos. Esto permite un control más preciso sobre cuándo y cómo ejecutar herramientas.
¿Cuál es el papel exacto de Zod en este stack?
Zod define los schemas de las herramientas y valida los argumentos generados por el modelo. Convertir esos schemas a JSON Schema permite declararlos al modelo y reducir llamadas inválidas y alucinaciones en tool_use.
¿Necesito tsx en producción?
tsx facilita ciclos de desarrollo y CI al evitar compilación manual. En producción puedes seguir usándolo o compilar, según tu pipeline; la recomendación es usarlo para reducir fricción durante desarrollo y pruebas.
¿Cómo reducir costes de tokens con este patrón?
Orquesta tool-calls en un único proceso, limita iteraciones del loop y evita encadenar llamadas LLM por cada handoff. Controlar explícitamente el número de iteraciones reduce tokens enviados y latencia.
¿Cuándo añadir bases de datos y vectores (pgvector)?
Añade PostgreSQL + pgvector cuando necesites retrieval persistente y la memoria a corto plazo del agente no sea suficiente para tus casos de uso.
¿Qué límites de seguridad operativa aplicar al expositor de herramientas?
Nunca expongas una herramienta sin schema Zod, registra cada tool_use con logs estructurados, limita reintentos y aplica validaciones estrictas (Result ok/error) en todas las funciones ejecutadas por el agente.