Salida estructurada (Structured Outputs)

La salida estructurada (structured outputs) es una capacidad de la API de Claude que garantiza que la respuesta del modelo cumpla un JSON Schema que tú defines: campos obligatorios, tipos y enumeraciones. No es una petición amable en el prompt, sino una restricción aplicada durante la generación, de modo que el resultado siempre se puede parsear y validar contra el esquema.

Cómo funciona

Se basa en decodificación restringida (constrained decoding). La API compila tu esquema en una gramática y, en cada paso de generación, solo permite los tokens que mantienen el texto dentro de esa gramática. Si el esquema exige un campo precio numérico, el modelo no puede escribir una cadena ni olvidarse de la clave.

En Claude se presenta de dos formas complementarias:

• Salidas JSON: pasas un esquema en la petición y la respuesta de texto del modelo es directamente un JSON conforme.
• Strict tool use: marcas una herramienta con strict: true y los argumentos que Claude genera al llamarla respetan exactamente su input_schema.

Anthropic la lanzó en beta a finales de 2025 para modelos concretos de la familia Claude 4.x. El nombre exacto del parámetro, la cabecera beta y los modelos compatibles han ido cambiando, así que conviene revisar la documentación vigente antes de implementarla.

Por qué importa

Antes, conseguir JSON fiable exigía trucos: instrucciones insistentes en el system prompt, prefill con {, o forzar una herramienta ficticia con tool_choice. Funcionaba casi siempre, y ese "casi" obligaba a escribir validadores, bucles de reintento y manejo de errores de parseo.

Con salida estructurada:

• Eliminas los fallos de json.loads por comas sobrantes, comillas sin cerrar o texto introductorio tipo "Aquí tienes el JSON".
• Los agentes que encadenan herramientas no se rompen por un argumento mal tipado.
• Puedes conectar la respuesta directamente a una base de datos, un formulario o un modelo Pydantic o Zod.

Si vas a construir aplicaciones sobre la API de Claude que extraen datos o alimentan otros sistemas, es de las primeras funciones que conviene dominar.

Ejemplo: extracción de datos de una factura

esquema = {
  "type": "object",
  "properties": {
    "proveedor": {"type": "string"},
    "total": {"type": "number"},
    "moneda": {"type": "string", "enum": ["EUR", "USD", "MXN"]}
  },
  "required": ["proveedor", "total", "moneda"],
  "additionalProperties": false
}
# Se envía junto al mensaje en el parámetro de formato
# de salida que indique la documentación actual.

La respuesta llegará siempre con esas tres claves, con total numérico y moneda dentro de los valores permitidos. Lo que el esquema no garantiza es que el total extraído sea el correcto: eso sigue dependiendo de la calidad del modelo y del documento.

Errores comunes

• Confundir formato con veracidad. Un JSON perfecto puede contener un dato inventado. La salida estructurada elimina errores de sintaxis, no alucinaciones.
• Usar cualquier JSON Schema. No se admiten todas las características del estándar; algunas restricciones avanzadas o esquemas recursivos pueden no estar soportados. Consulta la lista de limitaciones.
• Ignorar la latencia inicial. La primera petición con un esquema nuevo tarda algo más porque la gramática se compila; después se reutiliza durante un tiempo.
• Esquemas demasiado rígidos. Si obligas a rellenar un campo que el documento no contiene, el modelo lo rellenará igualmente. Permite null o campos opcionales cuando el dato pueda faltar.
• Combinarla sin comprobar compatibilidades. Algunas funciones, como el prefill de la respuesta, pueden no ser compatibles con el modo estructurado.