Category: AI

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

Tiempo estimado de lectura: 4 min

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.

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?