Saltar al contenido principal

Salida estructurada

Intermedio
What you'll learn
  • Explicar por qué la salida impuesta por esquema gana al prompting de JSON con la esperanza de que salga bien
  • Proporcionar un JSON Schema y parsear la respuesta en un objeto tipado (Pydantic / Zod)
  • Distinguir la salida estructurada del uso de herramientas por su intención, no por su mecanismo
  • Aplicar los cuatro consejos para esquemas ajustados y fiables
  • Elegir la herramienta correcta con una regla práctica de una sola pregunta

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.

Esta lección te lleva desde por qué falla el "pide y reza" hasta cómo imponer un esquema y parsearlo en un objeto tipado, y cómo distinguir la salida estructurada del uso de herramientas cuando parecen idénticos. Trabájala de arriba abajo y luego ponte a prueba con el cuestionario que hay cerca del final.

La forma fiable​

Proporciona un JSON Schema 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.

Guided walkthrough1 of 3
  1. Modela la salida que necesitas como un JSON Schema: en Python mediante un BaseModel de Pydantic, en TypeScript mediante un esquema de Zod.
# 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.

¿Quieres una solicitud concreta para adaptar? Aquí tienes la forma de lo que entregas al modelo: reemplaza el modelo por tu propio esquema.

Pide una salida que cumpla el esquema

Return the data conforming to this JSON Schema:

{
"title": "string",
"priority": "low | medium | high",
"tags": ["string"]
}

Do not include any prose outside the JSON.

¿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.

Watch out
  • El JSON pedido por prompt funciona en demos y se rompe en producción: el fallo aparece solo cuando un sistema posterior lo parsea.
  • Tres desviaciones clásicas que vigilar: prosa extraviada alrededor del JSON, una coma final y un campo obligatorio faltante.

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​

Pro tip
  • 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.
Key takeaways
  • Entrega a la API/SDK un JSON Schema y parsea en un objeto tipado: no 'pidas y reces'.
  • Pedir JSON por prompt puede desviarse (prosa extraviada, coma final, campo faltante); la imposición de esquema elimina esa clase de error.
  • La salida estructurada y el uso de herramientas difieren por intención: el JSON ES la respuesta vs. el JSON solicita una acción.
  • Esquemas ajustados, campos descritos y validación en la frontera hacen fiables la extracción y la clasificación.

Fija los términos​

Pulsa Intro o Espacio para girar la tarjeta. Usa las flechas izquierda y derecha para moverte entre las tarjetas.Término mostrado.
1 / 5

Ponte a prueba

0/4
  1. ¿Cuál es la forma fiable de obtener JSON estructurado de Claude?
  2. ¿Por qué pedir JSON por prompt es arriesgado una vez que un sistema posterior depende de ello?
  3. ¿Qué distingue realmente la salida estructurada del uso de herramientas?
  4. ¿Cuál es un consejo sensato para diseñar esquemas?

Siguiente​