Saltar al contenido principal

Salida estructurada

Intermedio

Cuando la salida de Claude alimenta a otro software, necesitas una estructura fiable: JSON válido que coincida con una forma conocida, siempre. No te fíes de "responde en JSON" y esperes lo mejor; usa el soporte de salida estructurada de la plataforma.

La forma fiable​

Proporciona un esquema JSON para la salida y deja que la API/SDK lo imponga, luego parséalo en un objeto tipado (p. ej., Pydantic en Python, Zod en TypeScript). Los ayudantes de parseo del SDK te entregan un resultado tipado en lugar de una cadena que tengas que pasar por JSON.parse y validar tú mismo.

# Conceptual shape — see the official docs for the current API surface.
from pydantic import BaseModel

class Ticket(BaseModel):
    title: str
    priority: str   # "low" | "medium" | "high"
    tags: list[str]

# Request the model to return data conforming to Ticket's JSON schema,
# then parse the response into a Ticket instance.

¿Por qué no pedir JSON directamente en el prompt?​

Puedes pedir JSON en el prompt, y para casos simples funciona, pero puede desviarse: prosa extraviada, una coma final, un campo faltante. La salida impuesta por esquema elimina esa clase de error, lo que importa en cuanto un sistema posterior depende de ella.

Salida estructurada vs. uso de herramientas​

Ambas funciones entregan al modelo un JSON Schema, así que se parecen — y la gente elige la equivocada. La diferencia es de intención, no de mecanismo:

Salida estructuradaUso de herramientas
Qué quieresLa respuesta final, en una forma fijaQue el modelo invoque una capacidad (llamar a una función, obtener datos, realizar una acción)
Quién la consumeTu código, directamenteTu código ejecuta la herramienta y luego devuelve el resultado al modelo
Forma del turnoUna respuesta, listoUn bucle: el modelo pide, tú ejecutas, el modelo continúa
Uso típicoExtracción, clasificación, parseoAgentes, búsquedas en vivo, efectos secundarios

Una regla rápida:

Si el JSON es el entregable, usa salida estructurada. Si el JSON es el modelo pidiendo a tu código que haga algo, eso es uso de herramientas. Los agentes a menudo usan ambos: herramientas para actuar, salida estructurada para devolver un resultado final limpio.

Consejos​

  • Mantén los esquemas ajustados. Usa enums para opciones fijas; marca los campos obligatorios.
  • Describe los campos. Las descripciones de campos guían al modelo como minipromts.
  • Valida de todos modos en la frontera: el parseo defensivo es un seguro barato.
  • Para tareas de extracción, la salida estructurada + un esquema claro gana al formato libre siempre.

Siguiente​