Cómo usar SDKs de AI tipados en TypeScript para reducir errores

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?