Category: TypeScript

El type system de TypeScript como documentación para tu agente de IA

Tiempo estimado de lectura: 4 min

El type system de TypeScript como documentación para tu agente de IA funciona mejor que mil parrafadas: le das al modelo un contrato, no una novela. Si quieres que Claude, GPT o cualquier agente genere código real y alineado con tu arquitectura, empieza por entregarle los tipos —no descripciones— y observa cómo las alucinaciones desaparecen.

¿Por qué? Porque un tipo es una restricción matemática. Un LLM con contexto tipado no puede inventar propiedades, estados o firmas que no existen.

Resumen rápido (lectores con prisa)

Qué: Usa el type system de TypeScript como contrato para agentes IA.

Cuándo: En APIs públicas, lógica crítica y workflows en producción.

Por qué importa: Reduce alucinaciones y errores de integración.

Cómo: Pega las interfaces, enums y tipos en el prompt y obliga al agente a cumplir firmas y uniones discriminadas.

Qué cambia en tu flujo de trabajo

Los modelos de lenguaje predicen tokens; no “entienden” tus necesidades de negocio. Cuando les ofreces solo lenguaje natural, abrazan convenciones comunes y rellenan huecos con suposiciones populares. Resultado: código que “parece” correcto pero falla en integrarse con tu stack.

Si en cambio inyectas las interfaces, enums y tipos de tu proyecto, reduces drásticamente el espacio de soluciones válidas. El agente no elige entre cien estructuras posibles: respeta la tuya.

No es teoría. Es práctica:

Fuentes prácticas: documentación oficial de TypeScript, guías de APIs y plataformas de agentes como OpenAI o Anthropic.

Ejemplo práctico: deja de explicar, pega el tipo

Imagina que quieres delegar la lógica de cambio de estado de pedidos.

Sin tipos: “Crea una función para actualizar el estado de un pedido”. El modelo inventa estados. Problema.

Con tipos reales:

type OrderStatus = 'pending' | 'confirmed' | 'dispatched' | 'delivered' | 'refunded';

interface Order {
  id: string;
  status: OrderStatus;
  customerId: string;
  updatedAt: string; // ISO UTC
}

type UpdateOrderStatusResult = 
  | { success: true; order: Order }
  | { success: false; error: 'ORDER_NOT_FOUND' | 'INVALID_TRANSITION' };

Pega esto en el prompt o en el contexto del agente (Cursor, GitHub Copilot, flujos custom via API) y pide: “Implementa updateOrderStatus que valide transiciones y devuelva UpdateOrderStatusResult”. Ahora el agente debe cumplir la firma. No habrá processing fantasmas ni retornos desordenados.

Reglas prácticas para construir el contexto tipado

1. Evita any como si fuera veneno

any es una puerta abierta a alucinaciones.

2. Prefiere uniones discriminadas sobre booleans dispersos

Las banderas (isLoading, isError) permiten estados imposibles; una unión no.

3. Añade JSDoc breve cuando la intención no sea obvia

Ejemplo: /** Fecha en UTC. No convertir a local. */

4. Expone las relaciones

Usa referencias: invoice.orderId: Order['id']. El agente lo interpreta como clave foránea.

5. Incluye los tipos de retorno claros (Result/Either)

Obliga a manejar errores, no a ignorarlos.

Herramientas que usan este enfoque

Herramientas que usan este enfoque: n8n para orquestación, GitHub Copilot y Cursor en editores. También puedes integrar directamente archivos .d.ts en el contexto de la llamada a la API.

¿Cuándo aplicar Type-Driven Development con agentes?

Úsalo cuando la consistencia importa: APIs públicas, lógica financiera, workflows críticos, transformaciones de datos y automations en producción. Evítalo solo en prototipos tempranos donde los modelos de datos cambian cada dos días.

No confundas disciplina con burocracia: diseñar tipos claros al principio acelera todo lo demás. Es una inversión que reduce revisiones manuales y bugs silenciosos.

Resultado esperado y próximos pasos

Si empiezas hoy, el cambio es tangible: menos iteraciones, menos PRs arreglando supuestos imposibles y, sobre todo, código que entra en tu base sin romper contratos. El tipo es el contrato. El agente es el implementador.

Haz esto ahora: copia el archivo de tipos relevante (o el fragmento clave) en el prompt de tu agente, pide una implementación concreta y compara el PR generado con lo que haría un desarrollador. Notarás dos cosas: consistencia y menos errores lógicos. Si trabajas con n8n, añade los tipos a los nodos o workflows para que los agentes que automatan tareas respeten tus contratos.

No acaba aquí: diseña un checklist de tipos antes de delegar, prueba un par de endpoints y verás cómo el modelo deja de “inventar”. ¿Quieres un checklist listo para usar? Haz esto primero: pega tu index.d.ts en el prompt y pide al agente “Genera tests unitarios que verifiquen las transiciones permitidas”. Verás la diferencia al instante.

Si quieres profundizar con proyectos y experimentos, revisa también los recursos y experimentos de Dominicode Labs. Es un buen complemento para validar patrones de Type-Driven Development aplicados a agentes y workflows antes de llevarlos a producción.

FAQ

Typed AI SDKs: por qué usar el SDK de Anthropic o OpenAI en TypeScript y no JavaScript puro

Tiempo estimado de lectura: 3 min

• TypeScript tipado reduce errores silenciosos: convierte fallos indetectables en errores visibles en desarrollo.
• Zod aporta validación en runtime: evita confiar en casts y valida la forma real de respuestas del modelo.
• Patrón “esquema primero, prompt segundo”: serializa el esquema en el prompt y valida antes de persistir.

Typed AI SDKs: por qué usar el SDK de Anthropic o OpenAI en TypeScript y no JavaScript puro — si vas a poner LLMs en producción, esa decisión cambia el perfil de riesgo de tu sistema. TypeScript no arregla la aleatoriedad del modelo, pero convierte fallos indetectables en errores visibles mientras desarrollas. Eso es todo; y es suficiente.

Resumen rápido (lectores con prisa)

Un SDK tipado (OpenAI o Anthropic) + validación runtime (Zod) convierte errores silenciosos en errores detectables durante desarrollo. Diseña el esquema primero, serialízalo en el prompt, parsea y valida la respuesta antes de usarla.

Introducción

Cuando integras un LLM en un flujo de trabajo (agentes, pipelines n8n, microservicios de extracción) no luchas contra la IA: luchas contra su impredecibilidad. JavaScript puro acepta promesas rotas y propiedades ausentes hasta que explotjan en producción. Un SDK tipado (OpenAI o Anthropic) empuja la mayoría de esos errores al compilador.

Fuentes prácticas:

• TypeScript docs
• OpenAI SDK
• Anthropic
• Zod
• n8n

Errores en compile time, no en producción

– Modelos como valores literales: los SDK tipados exponen uniones de strings para modelos. Intentar model: 'gpt-5' fallará en el editor, no en prod.

– Parámetros obligatorios: el compilador te obliga a rellenar lo que la API realmente necesita.

– Propiedades opcionales: TS fuerza comprobaciones (?., if) antes de operar con datos potencialmente nulos.

Resultado: menos hotfixes nocturnos. Detectas que algo está mal cuando escribes, no cuando lo usan clientes.

Autocompletado real: productividad que importa

IntelliSense deja de ser un lujo y pasa a ser documentación viva. Parámetros como temperature, response_format o function_call aparecen en el editor con sus tipos exactos. En equipos, esto reduce discusiones sobre “¿qué forma tenía ese objeto?” y evita JSON mal formado en llamadas a herramientas.

La trampa del casting y por qué Zod es obligatorio

TypeScript desaparece en runtime. Hacer const x = JSON.parse(s) as MyType es mentirle al compilador. Si el modelo devuelve "age":"veinticinco" habrás metido basura en tu flujo.

Zod ofrece validación en tiempo de ejecución y genera el tipo TypeScript desde el esquema. Patrones recomendados:

Patrones recomendados

• Definir el esquema Zod como fuente única de verdad.
• Incluir el esquema (o un resumen) en el prompt para guiar al LLM.
• Parsear y validar la respuesta con Zod antes de usarla.

Ejemplo práctico (OpenAI/Anthropic + Zod):

import { z } from 'zod';
import OpenAI from 'openai'; // o Anthropic desde '@anthropic-ai/sdk'

const UserProfileSchema = z.object({
  fullName: z.string(),
  age: z.number().int().positive(),
  email: z.string().email(),
  tags: z.array(z.string()).max(5),
});

type UserProfile = z.infer<typeof UserProfileSchema>;

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

async function extractUserProfile(text: string): Promise<UserProfile> {
  const resp = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [
      { role: 'system', content: `Devuelve solo JSON válido que cumpla este esquema: ${JSON.stringify(UserProfileSchema.shape)}` },
      { role: 'user', content: text },
    ],
    // response_format o similar según SDK
  });

  const raw = resp.choices?.[0]?.message?.content;
  if (!raw) throw new Error('Respuesta vacía del modelo');

  // Validación runtime: si falla, aquí lo capturas y reintentas o lo registras
  const parsed = UserProfileSchema.parse(JSON.parse(raw));
  return parsed;
}

Si usas Anthropic, adapta la llamada al cliente: la idea es la misma: pedir JSON estructurado y validar con Zod.

Patrones que escalan: esquema primero, prompt segundo

1. Diseña el esquema Zod.
2. Infiere tipos TypeScript con z.infer.
3. Serializa el esquema (o una versión legible) en el prompt.
4. Valida la respuesta antes de persistir o procesar.

Este patrón convierte al LLM en una fuente estocástica que vive dentro de un perímetro controlado. No reduces la tasa de “alucinaciones”, pero transformas una alucinación en un error tratable y reproducible.

Cuándo aplicar este enfoque

– Sistemas críticos: facturación, reconciliaciones, autorizaciones.

– Workflows orquestados en n8n donde agentes ejecutan cambios de estado.

– Microservicios que procesan datos externos y alimentan otras partes del sistema.

Evítalo solo en prototipos desechables donde la velocidad de exploración sea prioritaria frente a la robustez.

Conclusión

Usar Typed AI SDKs de Anthropic o OpenAI en TypeScript y validarlos con Zod no es postureo técnico: es una estrategia de mitigación de riesgo. Cambias errores silenciosos por fallos detectables en desarrollo, mejoras la DX y pones una barrera defensiva entre la naturaleza impredecible del LLM y la integridad de tus datos. Implementa el patrón “esquema primero, prompt segundo” y tu siguiente incidente nocturno será opcional, no inevitable.

Para trabajos relacionados con automatización, agentes y workflows en entornos de producción puedes explorar más prácticas y experimentos en Dominicode Labs. Se integra como una continuación lógica de los patrones descritos y recursos para orquestación y pruebas.

FAQ

• ¿Por qué TypeScript ayuda con SDKs de LLM?
• ¿No es suficiente validar con ifs y typeof?
• ¿Zod reemplaza a TypeScript?
• ¿Cómo incluyo el esquema en el prompt?
• ¿Este patrón funciona con Anthropic?
• ¿Cuándo no aplicar este enfoque?

Error handling en agentes de IA: TypeScript te obliga a hacerlo bien

Tiempo estimado de lectura: 3 min

Ideas clave

• Evita try/catch genéricos: ocultan la causa raíz y llevan a reintentos inútiles o a falsos positivos.
• Usa Result<T, E>: convierte errores en valores tipados que el orquestador y el LLM pueden razonar.
• Forzar exhaustividad con never: el compilador impide desplegar manejadores incompletos.
• Persistir errores en memoria: guarda fallos estructurados en la memoria episódica para decisiones posteriores.
• Instrumenta y prueba: telemetría, tests y SLAs para garantizar conducta operativa.

Tabla de contenidos

• Introducción
• Resumen rápido (lectores con prisa)
• Por qué los try/catch genéricos matan tus agentes
• Result<T, E>: convertir errores en datos con contrato
• never y exhaustive checks: el compilador como guardarraíl
• Integración práctica con memoria y orquestación
• Operacional: telemetría, tests y SLAs
• Cierre operativo
• Dominicode Labs
• FAQ

Introducción

Error handling en agentes de IA: TypeScript te obliga a hacerlo bien. Dilo alto. Si tu agente llama herramientas, escribe datos o encadena flujos, el modo en que tratas los fallos decide si tendrás un sistema autocorrectivo o un monstruo que consume tokens y rompe tablas.

Los try/catch genéricos son la forma más rápida de cegar a un agente. TypeScript, usado con disciplina, no te da magia: te da garantías. Garantías que convierten excepciones impredecibles en valores tipados que el agente puede razonar, registrar y recuperar.

Resumen rápido (lectores con prisa)

Qué: Trata errores como valores con Result<T,E> en lugar de throw.

Cuándo: Siempre que tu agente llame herramientas, escriba en DB o coordine flujos.

Por qué importa: Evita reintentos ciegos, reduce tokens gastados y hace al agente reparable.

Cómo funciona: Devuelve {ok: true|false} con error tipado y usa checks exhaustivos con never para obligar a manejar nuevos casos.

Por qué los try/catch genéricos matan tus agentes

Un humano reintenta después de un HTTP 500. Un agente no. Cuando un LLM recibe solo “Error executing tool”, pierde la causa raíz. ¿Duplicado en la DB? ¿Timeout? ¿Bad payload? Sin esa información, el agente hará una de dos cosas útiles para nadie: reintentar la misma acción hasta agotar tu presupuesto o “alucinar” que la acción fue exitosa para seguir el flujo.

En sistemas agénticos cada fallo es una señal. Ocultarla con un mensaje opaco equivale a apagar los sensores del coche mientras conduces rápido.

Result<T, E>: convertir errores en datos con contrato

La respuesta práctica es sencilla: deja de tirar (throw) y empieza a devolver. El patrón Result<T, E> transforma errores en valores discriminados que obligan al consumidor a lidiar con ellos.

type Result<T, E> =
  | { ok: true; value: T }
  | { ok: false; error: E };

Ejemplo de herramienta:

async function createUser(email: string): Promise<Result<User, 'DUPLICATE_EMAIL' | 'DB_TIMEOUT' | 'INVALID_SCHEMA'>> {
  // nunca throw; siempre retorna ok: true | ok: false
}

¿Qué cambia? Ahora el orquestador recibe información accionable. Si ok: false y error === ‘DUPLICATE_EMAIL’, inyectas esa razón en la memoria episódica y el LLM pregunta por otro email en vez de repetir la misma INSERT. Transformas ruido en contexto.

Documentación útil sobre Result (concepto inspirado en Rust): Documentación útil sobre Result (concepto inspirado en Rust)

never y exhaustive checks: el compilador como guardarraíl

Pasa esto en equipos: alguien añade un nuevo error y olvida manejarlo. Resultado: el agente se comporta de forma impredecible en producción. Aquí entra el patrón de comprobación exhaustiva con never.

Define tus errores como unión discriminada:

type AgentError =
  | { type: 'DatabaseError'; code: number }
  | { type: 'AuthError'; reason: string }
  | { type: 'ValidationError'; issues: string[] };

Y formatea para el LLM con un switch que fuerza exhaustividad:

function formatErrorForLLM(error: AgentError): string {
  switch (error.type) {
    case 'DatabaseError': return `DB failure (${error.code}). No retry.`;
    case 'AuthError': return `Auth failed: ${error.reason}. Re-auth required.`;
    case 'ValidationError': return `Invalid: ${error.issues.join(', ')}. Fix and retry.`;
    default:
      const _exhaustive: never = error;
      return _exhaustive;
  }
}

Si alguien añade { type: 'RateLimit' } a AgentError y no actualiza este switch, TypeScript fallará en compilación. Lee sobre exhaustiveness checks: Lee sobre exhaustiveness checks

Eso no es paranoia: es disciplina. Tu CI/CD no permitirá desplegar un agente que no explica cada fallo.

Integración práctica con memoria y orquestación

Errores tipados deben viajar junto con resultados hacia la memoria episódica. Diseño minimalista:

• La tool retorna Result.
• El orquestador persiste tanto éxitos como fallos en la memoria episódica (Redis) y semántica (vector DB si aplica).
• El prompt incluye el fallo estructurado antes de la siguiente llamada al LLM.
• El LLM decide la acción (retry con modificación, pedir datos al usuario, escalar).

Además: valida entradas con Zod/JSON Schema antes de llamar a la tool. Un buen schema reduce la superficie de errores y hace que los fallos restantes sean reales y manejables.

Operacional: telemetría, tests y SLAs

No sirve con tipos si no lo verificas. Tienes que medir:

• Retries por tipo de error (P50/P95).
• Frecuencia de errores no mapeados (build-breakers).
• Tokens gastados en reintentos.
• Casos escalados a humano.

Incluye tests que simulen fallos de DB, timeouts y errores de validación. Tu pipeline debe romper si un nuevo error llega a producción sin un handler en el switch exhaustivo.

Cierre operativo

El try/catch genérico es cómodo. También es la razón por la que tu agente se convierte en una caja negra con facturas altas y datos rotos. Convertir errores en valores tipados (Result<T,E>) y forzar comprobaciones exhaustivas con never no es estilo: es seguridad operativa.

Aplica esto ya, instrumenta telemetría y haz que tu build falle si alguien olvida un caso de error. En el próximo artículo mostraremos cómo serializar esos errores en memoria episódica y usar feedback estructurado para que el agente aprenda a autocorregirse sin intervención humana.

Dominicode Labs

Para equipos que diseñan agentes y pipelines de orquestación, es útil contar con recursos y experimentos que muestren patrones de integración entre memoria episódica y errores tipados. Continúa explorando técnicas y prototipos en Dominicode Labs para ver implementaciones prácticas y ejemplos aplicados a agentes y workflows.

FAQ

• ¿Por qué no debo usar try/catch genéricos en agentes?
• ¿Qué es Result<T,E> y cómo cambia la arquitectura?
• ¿Cómo obliga TypeScript a manejar nuevos errores?
• ¿Dónde guardo los errores para que el agente los use?
• ¿Qué métricas debo instrumentar primero?
• ¿Cómo debo testear los manejadores de error?
• ¿Qué herramientas de validación recomiendan antes de llamar a una tool?