Skip to main content

Structured output: cuando necesitás JSON, no prosa

Cuando la salida del modelo alimenta un sistema en vez de un humano, la forma es un contrato — y parsear prosa para sacarla es la apuesta frágil que se rompe en el primer input que no probaste. Los caminos confiables en orden de fuerza: Structured Outputs para cumplimiento de schema garantizado, tool calling para argumentos tipados, y un spec de formato preciso en el system prompt para flexibilidad. El prefill no es la técnica — no está soportado en los modelos Claude nuevos. Sea cual sea el camino, validá cada salida antes de usarla y tené un fallback determinista para cuando la validación falla.

Referencia·Actualizado 2026-06-03·Escrito por Lira · Editado por German Medina

La mayoría de lo que produce un modelo es para que lo lea un humano, y la prosa es la forma correcta para eso. Esta página es sobre el otro caso: cuando la salida alimenta un sistema — un parser, un Flow, una escritura a base de datos, el próximo paso de un pipeline — y ningún humano la ve. Ahí la forma no es una decisión de estilo; es un contrato. El sistema del otro lado espera exactamente estos campos, estos tipos, esta estructura, y se rompe con cualquier otra cosa. Cuando ese es el trabajo, no querés prosa de la que sacar la respuesta con un regex. Querés una forma confiable.

Esto es una referencia para conseguir esa forma de manera confiable. Es el pago de un hilo que abren dos gotchas de prompting — formato frágil y parseo de prosa (mirá prompting gotchas, gotchas 2 y 7) — y se construye directo sobre la disciplina de schema ya planteada para agentes en tools and actions; donde esa página cubre la mecánica de tool calling completa, esta la señala en vez de re-enseñarla.

El problema: la prosa no es un contrato

Un prompt que dice "respondé con los campos de abajo" y devuelve la forma correcta en diez corridas de prueba no está produciendo esa forma de manera confiable — la está produciendo hasta ahora. La generación libre es no determinista por naturaleza. En la corrida número once el modelo abre con un preámbulo amable, envuelve el JSON en un code fence, reordena los campos, o renombra uno, y el parser que asumió la forma exacta de la demo se traba en el primer input que no probaste. Lo endureciste con un regex; el modelo fraseó el siguiente apenas distinto y el regex lo erró. Esto es la capa intermedia frágil que nombra el gotcha 7: un parser hecho a mano peleando contra un blanco móvil, cuando la carga de producir una forma válida le corresponde al modelo y al contrato de la API.

El replanteo que lo arregla es dejar de tratar la forma de la salida como algo que esperás y empezar a tratarla como algo que especificás y hacés cumplir. Tres caminos hacen eso, en orden de qué tan fuerte es la garantía que dan. Son complementarios, no una escalera — elegís el que tenga la garantía que de verdad necesita el sistema de abajo.

Camino 1: Structured Outputs — cumplimiento de schema garantizado

Cuando necesitás JSON válido que se conforme a un schema y no podés tolerar la respuesta malformada ocasional, este es el camino hecho para eso. Structured Outputs es la feature de Claude para adherencia a schema garantizada: le pasás a la API un JSON Schema, y la respuesta queda restringida — vía constrained decoding — a conformarse a él. Sin preámbulo, sin fence, sin campo faltante, sin sorpresa de JSON.parse(). La garantía es el punto: la forma se hace cumplir en tiempo de generación, no se chequea después y se reintenta.

Está generalmente disponible en los modelos Claude actuales — Opus 4.8, 4.7, 4.6 y 4.5, Sonnet 4.6 y 4.5, y Haiku 4.5 — a través de la Claude API. (La feature salió primero detrás del beta header structured-outputs-2025-11-13; ese header todavía funciona por un período de transición, pero ya no es necesario ahora que la feature es GA.) La feature tiene dos mitades complementarias: un formato de salida JSON que restringe la respuesta entera a tu schema, y strict tool use (strict: true) que hace cumplir la misma validación de schema sobre los inputs de un tool. Andá a este camino cuando el sistema de abajo necesita una garantía dura — una escritura que no puede fallar con un campo malformado, un contrato que un parser nunca debería tener que defender.

Camino 2: tool calling para estructura — los argumentos tipados son la salida

También podés sacar estructura por la puerta de al lado. Definís un tool con un input schema tipado y dejás que el modelo lo "llame"; los argumentos que el modelo completa son tu structured output. No estás ejecutando una acción de verdad — estás usando la definición del tool como una forma que el modelo tiene que producir. Esta es la misma disciplina de schema que tools and actions plantea completa, usada para otro fin: ahí la llamada tipada es cómo un agente actúa; acá es cómo extraés una forma confiable.

La palanca que hace el mayor trabajo es la misma que esa página destaca: un schema tipado, y un enum en particular, hace que la salida inválida sea difícil de expresar. Para una tarea de clasificación — rutear este ticket a una de cuatro colas, etiquetar este mensaje con uno de un conjunto fijo de labels — un campo enum significa que el modelo no puede devolver una categoría que no existe. La restricción vive en el schema, no en una instrucción amable de la que el modelo puede derivar.

{
  "name": "classify_ticket",
  "description": "Classify ONE incoming support ticket. Return the queue it routes to and the urgency. Use exactly the allowed values; do not invent new ones.",
  "input_schema": {
    "type": "object",
    "properties": {
      "queue": {
        "type": "string",
        "enum": ["billing", "technical", "account", "other"],
        "description": "Which queue this ticket routes to."
      },
      "urgency": {
        "type": "string",
        "enum": ["low", "normal", "high"],
        "description": "How urgent the ticket is."
      },
      "summary": {
        "type": "string",
        "description": "A one-sentence summary of the ticket."
      }
    },
    "required": ["queue", "urgency", "summary"]
  }
}

Los campos enum no pueden volver como un valor que no listaste; required significa que ninguno vuelve faltante. Cuando pareás esto con strict tool use (la segunda mitad del camino 1), ese schema se hace cumplir, no se pide nomás — los dos caminos se encuentran ahí. Mirá tools and actions para la mecánica de tool calling completa, las reglas de tool seguro, y dónde encaja esto en un agente.

Camino 3: instrucciones de system prompt más un spec de formato preciso

Cuando necesitás una flexibilidad que un schema estricto no da — un documento con template, una forma XML, un formato que el camino de JSON Schema no expresa limpio — caés en instruir el formato con precisión en el system prompt. Este es el camino menos garantizado, así que la precisión es todo el trabajo: definí cada elemento que la salida tiene que contener, nombrá cada campo, mostrá la estructura exacta, y no dejes nada a discreción del modelo. "Respondé en JSON" no es un spec; un ejemplo trabajado de la forma exacta, cada campo etiquetado, con la regla de que nada va antes ni después, sí lo es. Cuanto más preciso clavás el formato, más se acerca la confiabilidad de este camino a la de los que se hacen cumplir — pero nunca alcanza una garantía, que es exactamente por qué este es el tercer camino, no el primero.

Acá también aterriza la disciplina de system prompts and instructions: un spec de formato es una restricción dura, así que se gana salience estructural — su propia sección, dicha una vez y con claridad — en vez de una oración enterrada a mitad de párrafo donde el modelo la sub-pondera.

La disciplina sea cual sea el camino: validá, después fallback

Ningún camino saca las dos reglas que hacen que el structured output sea seguro para depender de él, y se sostienen ya sea que usaste la feature garantizada o el spec de formato más suelto.

Validá cada salida antes de usarla. Validá la forma contra el schema de lo que el sistema de abajo de verdad requiere — los campos correctos, los tipos correctos, los valores en rango — antes de que un solo byte llegue a ese sistema. Incluso con una feature que garantiza conformidad de schema, la validación es donde la salida del modelo se encuentra con tus reglas de negocio, que el schema no codifica: un enum puede garantizar que un valor es una de cuatro colas sin garantizar que es la correcta para este ticket, y un campo string puede ser schema-válido y aun así estar vacío. Nunca confíes en la forma a ciegas; el chequeo es barato y la escritura mala que previene no lo es.

Tené un fallback determinista para cuando la validación falla. Esto es el principio 8 — la no determinación necesita un gate donde es de cara al cliente. Cuando la validación falla, decidí deliberadamente qué pasa: reintentar, rutear a un humano, devolver un default seguro y conocido, o frenar. Lo que nunca hacés es dejar que una falla del modelo se renderice como un blanco, un string de error, o un valor alucinado en el sistema de abajo. Un fallback determinista aburrido le gana a una respuesta equivocada emocionante todas las veces, y el camino de falla es algo que diseñás y probás, no algo que descubrís en producción la primera vez que el modelo devuelve una forma que no planeaste. Esto también es el principio 11 — trazalo: logueá la salida cruda, el resultado de la validación, y qué rama se disparó, así una falla de forma silenciosa es algo que podés repetir en vez de adivinar.

La disciplina, recapitulada

Cuando la salida alimenta un sistema, la forma es un contrato, y la manera confiable de honrar un contrato es hacerlo cumplir en vez de esperarlo. Andá a la garantía más fuerte que el trabajo permita — Structured Outputs para un schema duro, un schema de tool para argumentos tipados, un spec de formato preciso solo cuando necesitás una flexibilidad que el schema no puede dar — y nunca vayas al prefill, que los modelos nuevos ya no soportan. Después, en cada camino, validá la salida contra tus requisitos reales y tené un fallback determinista listo para cuando la validación falla. Acertá eso y un sistema de abajo puede depender de lo que el modelo le entrega. Erralo — confiá en la prosa, salteá la validación, no dejes fallback — y construiste un pipeline que corre limpio una semana y se rompe con seguridad un martes, sobre una salida que estaba casi bien.

Related

Reference: