Cómo tipar las respuestas de una LLM utilizando Zod y TypeScript

Saber cómo tipar las respuestas de una LLM con Zod + TypeScript aparece en las primeras líneas porque es lo que evita que un agente, workflow o microservicio se rompa en producción. El modelo devuelve JSON, a menudo; nunca con la forma exacta que esperabas. .parse() y z.infer<> no son trucos: son la defensa que convierte datos inciertos en contratos verificables.

Resumen rápido (lectores con prisa)

Qué: Usa Zod para validar y transformar respuestas de LLM en runtime.

Cuándo: Siempre que vayas a persistir datos o ejecutar acciones críticas basadas en la salida de una LLM.

Por qué importa: TypeScript no valida en runtime; sin validación, datos malformados pueden romper sistemas en producción.

Cómo funciona: Diseña el esquema Zod como fuente única, extrae tipos con z.infer<>, limpia la salida si es necesario y valida con .parse() o .safeParse().

Por qué JSON.parse() + as es una trampa (y qué rompe)

El patrón clásico:

const obj = JSON.parse(response) as MyType;

Es práctico. Es una mentira. TypeScript desaparece en runtime; as no valida nada. Los fallos típicos de LLMs:

Si confías en casts, esos problemas llegan a tu base de datos o a la lógica que ejecuta acciones. Validación en runtime es obligatoria.

El patrón sólido: esquema primero, prompt segundo

Este patrón convierte la salida estocástica de la LLM en una entrada controlada para tu sistema.

Ejemplo práctico mínimo

import { z } from 'zod';

const TaskSchema = z.object({
  title: z.string().min(5),
  priority: z.enum(['low','medium','high']),
  estimatedHours: z.number().positive().optional(),
});

type Task = z.infer;

Al pedir al modelo que devuelva JSON, serializa el esquema (o su forma) en el prompt para guiar la salida.

Limpieza defensiva y parse()

Los LLMs suelen añadir markdown. Limpia antes de parsear:

function cleanJson(raw: string) {
  return raw.replace(/```json\n?|\n?```/g, '').trim();
}

const parsed = JSON.parse(cleanJson(rawOutput));
const valid = TaskSchema.parse(parsed); // lanza ZodError si falla

Usa .parse() cuando quieras detener el flujo y tratar la anomalía como error severo (útil en endpoints HTTP que deben devolver 4xx/5xx claros).

.safeParse() y auto‑corrección de prompts

En agentes autónomos o workflows escalables (n8n, agentes con herramientas), es preferible no lanzar. .safeParse() devuelve { success, data?, error? } para manejar fallos:

const result = TaskSchema.safeParse(parsed);
if (!result.success) {
  // registrar, emitir métricas y reintentar con autocorrección
  const zodErrors = result.error.flatten();
  // reintentar: enviar a la LLM el error y pedir JSON corregido
}

Patrón de autocorrección: incluye los errores de Zod en un nuevo prompt — el LLM suele corregir la estructura en el siguiente intento.

Structured Outputs no elimina Zod

Structured Outputs de OpenAI ayuda a reducir errores de formato (Structured Outputs). Aun así:

Zod sigue siendo la última línea de defensa.

Operativa en producción: logging, reintentos y SLOs

Esto transforma un fallo LLM en un incidente manejable, no en una caída silenciosa.

Consejos prácticos y anti‑patrones

Conclusión técnica

Tipar las respuestas de una LLM con Zod + TypeScript no es una cuestión de estilo: es ingeniería de fiabilidad. .parse() y z.infer<> convierten la salida no determinista de una IA en datos verificables. Si construyes agentes, pipelines en n8n o features que actúan sobre sistemas críticos, aplicar este patrón es la diferencia entre sistemas que escalan y sistemas que requieren vigilancia humana constante. Implementa el esquema primero, valida siempre y deja que la LLM vuelva a intentarlo cuando falle — pero que falle donde tú lo controles.

Para equipos que implementan flujos autónomos y pipelines de IA, una práctica útil es centralizar patrones de validación y autocorrección; esto es exactamente el tipo de trabajo que se experimenta en Dominicode Labs, donde se documentan plantillas y prácticas para agentes y workflows.