Los desarrolladores ahora pueden garantizar que el JSON que devuelve un LLM se ajuste a una forma predefinida al integrar esquemas de Zod en el Vercel AI SDK o en la API de tool-use de Anthropic, eliminando los errores de ejecución (runtime crashes) que ocurren cuando un modelo añade un campo inesperado.

La necesidad de una protección concreta se hizo evidente en enero, cuando un clasificador lanzado a producción comenzó a devolver una segunda clave “explanation” tras tres semanas de funcionamiento impecable. El código esperaba un único campo, por lo que la clave adicional provocó una excepción, sin necesidad de un único despliegue de código. El incidente ilustra un problema más amplio: la mayoría de los tutoriales se detienen en JSON.parse(response), asumiendo que el modelo obedecerá el esquema del prompt. En realidad, los LLM suelen desviarse: cambian las mayúsculas/minúsculas, añaden campos o envuelven la salida en bloques de markdown, lo que provoca una corrupción silenciosa de los datos o fallos directos.

Por qué el parsing de JSON puro es inseguro

Los LLM están entrenados para ser útiles, no obedientes. Un prompt que solicita

{ "category": "string" }

no vincula al modelo a esa estructura exacta. Incluso un prompt bien redactado puede ser anulado por las heurísticas internas del modelo, especialmente cuando un ajuste de temperatura fomenta la creatividad o cuando una instrucción posterior lo incita a dar más detalles. El resultado es un flujo de texto que parece JSON pero que se desvía lo suficiente como para romper los parsers que esperan una forma estricta.

Cuando tal discrepancia llega al código de producción, el coste es inmediato: una excepción lanzada, una solicitud fallida y, potencialmente, una cascada de errores en los procesos posteriores. En servicios de gran escala, esos minutos de inactividad se traducen en pérdida de ingresos y en la erosión de la confianza del usuario.

Zod + Vercel AI SDK: una red de seguridad de tres pasos

Zod es un validador de esquemas centrado en TypeScript que puede describir la forma exacta de los datos que un modelo debe emitir. Combinado con el ayudante Output.object del Vercel AI SDK, la validación ocurre automáticamente después de que el modelo genera su respuesta.

  1. Definir el esquema – escribir un objeto Zod que refleje el JSON deseado. Para un clasificador sencillo, podría ser z.object({ category: z.string() }); para un extractor de facturas complejo, el esquema puede anidar objetos, arrays y uniones discriminadas (discriminated unions).
  2. Pasarlo al SDK – envolver el esquema con Output.object(schema). El SDK inyecta un prompt que indica al modelo que genere un bloque JSON que coincida con el esquema y analiza el resultado con el safeParse de Zod.
  3. Gestionar fallos – safeParse devuelve un objeto de resultado en lugar de lanzar una excepción. Si el análisis falla, se devuelve el error al modelo y se reintenta. Se puede instruir al modelo para que corrija la salida basándose en el mensaje de validación exacto, convirtiendo la mayoría de los casos límite en un bucle de autorreparación.

Dado que el SDK realiza el prompting, el parsing y la lógica de reintento en un solo lugar, los desarrolladores sustituyen un puñado de manipulaciones de cadenas ad-hoc por una única llamada verificada por tipos (type-checked).

Uso de herramientas de Anthropic: forzar la salida estructurada

Al trabajar directamente con la API de Anthropic, se puede lograr la misma garantía mediante el “uso de herramientas” (tool use). Una herramienta se define como una función cuyo esquema de entrada se expresa en JSON Schema; el modelo de Anthropic solo llamará a la herramienta si puede satisfacer el esquema. Al establecer tool_choice en "any" (o un nombre de herramienta específico), se obliga al modelo a devolver un bloque estructurado en lugar de texto libre.

El flujo de trabajo refleja el enfoque de Vercel:

  • Escribir un esquema Zod.
  • Convertirlo en un payload de JSON Schema para la definición de la herramienta.
  • Incluir la herramienta en la solicitud y requerir que el modelo la invoque.
  • Analizar la respuesta de la herramienta con zod.safeParse.

Si el modelo sigue produciendo datos malformados, se aplica el mismo patrón de reintento con retroalimentación.

Cuando la validación sigue fallando

Incluso con la aplicación de esquemas, ocurren discrepancias ocasionales. Los motivos incluyen:

  • Alucinación del modelo: el modelo puede generar una cadena que parece JSON pero contiene errores de sintaxis.
  • Fuga de prompts (prompt leakage): los turnos de conversación anteriores pueden filtrar instrucciones de formato que anulen la solicitud del esquema.
  • Diferencias de versión: los lanzamientos de modelos más nuevos a veces cambian la forma en que interpretan las llamadas a herramientas.

La mitigación recomendada es un bucle de reintento ligero. Ante un fallo de análisis, el código envía un prompt de seguimiento como: “Tu última salida no era un JSON válido. Contenía... Por favor, devuelve solo los campos definidos en el esquema”. Debido a que el error de validación es explícito, el modelo puede corregirse a sí mismo sin intervención humana.

Consideraciones de rendimiento y coste

Añadir la validación de Zod introduce una sobrecarga de CPU insignificante: la operación safeParse se ejecuta en microsegundos para cargas útiles típicas. La latencia de red no cambia; el viaje de ida y vuelta adicional para un reintento solo ocurre en el caso poco común de un fallo. En la práctica, el coste de evitar una sola excepción supera con creces el aumento marginal en el tiempo de la solicitud.

Contraargumento: ¿es excesiva la aplicación de esquemas?

Algunos desarrolladores argumentan que los esquemas estrictos limitan la flexibilidad del modelo, especialmente cuando nuevos campos podrían proporcionar un contexto valioso. El equilibrio reside entre la seguridad y la apertura. En servicios de misión crítica —procesamiento de pagos, verificación de identidad, informes de cumplimiento— la previsibilidad gana. En prototipos exploratorios, un enfoque más flexible puede ser aceptable, pero incluso allí una guardia mínima (por ejemplo, z.object({}).passthrough()) puede detectar errores de análisis catastróficos sin descartar extensiones útiles.

Qué observar a continuación

  • Evolución del SDK: La hoja de ruta del AI SDK de Vercel incluye políticas de reintento integradas y un reporte de errores más completo, lo que agilizará aún más el ciclo de reparación.
  • Estandarización de herramientas: A medida que más proveedores adopten convenciones de uso de herramientas, podrían surgir validadores de esquemas multiplataforma, reduciendo la necesidad de adaptadores específicos para cada proveedor.
  • Patrones de la comunidad: Las librerías de código abierto están empezando a agrupar esquemas de Zod con plantillas de prompts, convirtiendo el flujo de trabajo “schema-first” en un activo reutilizable.

Conclusión

Al tratar un esquema de Zod como un contrato que el modelo no puede romper, los desarrolladores pasan de trucos frágiles de JSON.parse a un pipeline determinista donde los campos inesperados provocan un fallo de validación controlado, no un error en producción. La combinación del ayudante Output.object de Vercel y el mecanismo de uso de herramientas de Anthropic convierte a los LLM de generadores de texto impredecibles en proveedores de datos fiables, permitiendo que los equipos se centren en la lógica de negocio en lugar de en una depuración interminable de casos límite.