Salidas estructuradas

Las “structured outputs” (salidas estructuradas) restringen las respuestas de Claude para que sigan un esquema específico, lo que garantiza una salida válida y analizable para el procesamiento posterior. Las salidas estructuradas ofrecen dos funciones complementarias:

• Salidas JSON (output_config.format): Obtén la respuesta de Claude en un formato JSON específico, por ejemplo, para extraer datos de imágenes o texto, generar informes estructurados o dar formato a respuestas de API. Esta página trata sobre las salidas JSON.
• Uso estricto de herramientas (strict: true): Garantiza la validación del esquema en los nombres y las entradas de las herramientas. Consulta Uso estricto de herramientas.

Puedes usar estas funciones de forma independiente o juntas en la misma solicitud.

Por qué usar salidas estructuradas

Sin salidas estructuradas, Claude puede generar respuestas JSON mal formadas o entradas de herramientas no válidas que rompen tus aplicaciones. Incluso con prompts cuidadosos, podrías encontrarte con:

• Errores de análisis por sintaxis JSON no válida
• Campos obligatorios faltantes
• Tipos de datos inconsistentes
• Infracciones del esquema que requieren manejo de errores y reintentos

Las salidas estructuradas garantizan respuestas que cumplen con el esquema mediante “constrained decoding” (decodificación restringida):

• Siempre válidas: Sin errores de análisis de JSON
• Con seguridad de tipos: Tipos de campo y campos obligatorios garantizados
• Confiables: No se necesitan reintentos por infracciones del esquema

Cómo funciona

1. 1

   Define tu esquema

   Describe la estructura que quieres como un esquema JSON o como un tipo en tu lenguaje. El esquema sigue JSON Schema, con algunas limitaciones.

2. 2

   Envíalo en output_config.format

   La solicitud incluye el esquema en output_config.format con type: "json_schema". Los helpers del SDK lo configuran por ti.

3. 3

   Lee la respuesta

   Claude devuelve JSON válido que coincide con tu esquema en el bloque de contenido de texto de la respuesta. Los helpers del SDK lo analizan y lo convierten en tu tipo.

Uso

from pydantic import BaseModel
# ...


class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

Cómo funciona la transformación del SDK

La mayoría de los helpers del SDK transforman los esquemas que usan funciones no compatibles. Los pasos de la transformación son:

1. Eliminar las restricciones no compatibles (por ejemplo, minimum, maximum, minLength, maxLength)
2. Actualizar las descripciones agregando cada restricción no compatible a la descripción del campo (por ejemplo, {minimum: 100})
3. Agregar additionalProperties: false a todos los objetos
4. Filtrar los formatos de cadena para dejar solo la lista compatible
5. Validar las respuestas contra tu esquema original y todas sus restricciones, si el helper valida las respuestas

Claude recibe un esquema simplificado, pero un helper que valida las respuestas sigue aplicando cada restricción en tu código.

Ejemplo: Un campo con minimum: 100 se convierte en un entero simple en el esquema enviado, y el SDK agrega {minimum: 100} a la descripción del campo. Un helper que valida las respuestas sigue comprobando la respuesta contra minimum: 100.

Uso de un esquema JSON sin procesar

Para usar un esquema JSON de un archivo, de una especificación OpenAPI o de código que lo construye en tiempo de ejecución, pásalo en output_config.format.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "name": {"type": "string"},
                    "email": {"type": "string"},
                    "plan_interest": {"type": "string"},
                    "demo_requested": {"type": "boolean"},
                },
                "required": ["name", "email", "plan_interest", "demo_requested"],
                "additionalProperties": False,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

Casos de uso comunes

from pydantic import BaseModel


class LineItem(BaseModel):
    description: str
    quantity: float
    unit_price: float


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[LineItem]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = """
Invoice #12345
Date: 2024-01-15
Customer: Acme Corp
2 widgets at $150.00 each
1 setup fee at $200.00
Total: $500.00
"""

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Payload(BaseModel):
    message: str


class APIError(BaseModel):
    code: str
    detail: str


class Metadata(BaseModel):
    request_id: str


class APIResponse(BaseModel):
    status: str
    data: Payload
    errors: list[APIError] | None = None
    metadata: Metadata


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[
        {
            "role": "user",
            "content": "Write an API response: request req_2abc3def has an invalid email.",
        }
    ],
)

print(response.parsed_output)

Uso estricto de herramientas

Para aplicar el cumplimiento de JSON Schema en las entradas de herramientas con “grammar-constrained sampling” (muestreo restringido por gramática), consulta Uso estricto de herramientas.

Uso de ambas funciones juntas

Las salidas JSON y el uso estricto de herramientas resuelven problemas diferentes y funcionan juntos:

• Las salidas JSON controlan el formato de respuesta de Claude (lo que Claude dice).
• El uso estricto de herramientas valida los parámetros de las herramientas (cómo Claude llama a tus funciones).

Cuando se combinan, Claude puede llamar a herramientas con parámetros garantizados como válidos Y devolver respuestas JSON estructuradas. Esto es útil para flujos de trabajo agénticos en los que necesitas tanto llamadas a herramientas confiables como salidas finales estructuradas.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # Salidas JSON: formato de respuesta estructurado
    output_config={
        "format": {
            "type": "json_schema",
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "next_steps": {"type": "array", "items": {"type": "string"}},
                },
                "required": ["summary", "next_steps"],
                "additionalProperties": False,
            },
        }
    },
    # Uso de herramientas estricto: parámetros de herramientas garantizados
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

Consideraciones importantes

Compilación y almacenamiento en caché de gramáticas

Las salidas estructuradas usan muestreo restringido con artefactos de gramática compilados. Esto introduce algunas características de rendimiento que debes tener en cuenta:

• Latencia de la primera solicitud: La primera vez que usas un esquema específico, hay “latency” (latencia) adicional mientras se compila la gramática.
• Almacenamiento en caché automático: Las gramáticas compiladas se almacenan en caché durante 24 horas desde el último uso, lo que hace que las solicitudes posteriores sean mucho más rápidas.
• Invalidación de la caché: La caché se invalida si cambias la estructura del esquema JSON o, al usar tanto salidas estructuradas como uso de herramientas, el conjunto de herramientas de tu solicitud. Cambiar solo los campos name o description no invalida la caché.

Modificación del prompt y costos de tokens

Al usar salidas estructuradas, Claude recibe automáticamente una “system prompt” (indicación del sistema) adicional que explica el formato de salida esperado. Esto significa que:

• Tu recuento de tokens de entrada es ligeramente mayor.
• El prompt inyectado te cuesta tokens como cualquier otra indicación del sistema.
• Cambiar el parámetro output_config.format invalida cualquier caché de prompts para ese hilo de conversación.

Limitaciones de JSON Schema

Las salidas estructuradas admiten JSON Schema estándar con algunas limitaciones. Tanto las salidas JSON como el uso estricto de herramientas comparten estas limitaciones.

Objetos con claves arbitrarias

Enumera cada clave de un objeto, ya sea en properties o como un campo de la clase o del esquema que pasas al SDK. Como additionalProperties debe ser false, Claude solo puede devolver las claves que enumeres.

La API acepta un objeto con properties vacío o ausente, pero Claude solo puede devolver {} para él. Un tipo map, diccionario o record no enumera ninguna clave, por lo que los SDK de Python y TypeScript lo envían como un objeto con properties vacío. Los SDK de Java y Ruby generan un error en su lugar.

Si no conoces las claves de antemano, usa un array en su lugar. Dale a cada elemento una key y un value, como en este esquema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "key": { "type": "string" },
      "value": { "type": "string" }
    },
    "required": ["key", "value"],
    "additionalProperties": false
  }
}

Orden de las propiedades

Al usar salidas estructuradas, las propiedades de los objetos mantienen el orden definido en tu esquema, con una advertencia importante: las propiedades obligatorias aparecen primero, seguidas de las propiedades opcionales.

Por ejemplo, dado este esquema:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

La salida ordena las propiedades así:

1. name (obligatoria, en el orden del esquema)
2. email (obligatoria, en el orden del esquema)
3. notes (opcional, en el orden del esquema)
4. age (opcional, en el orden del esquema)

Esto significa que la salida podría verse así:

{
  "name": "John Smith",
  "email": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Si el orden de las propiedades en la salida es importante para tu aplicación, marca todas las propiedades como obligatorias o ten en cuenta este reordenamiento en tu lógica de análisis.

Salidas no válidas

Aunque las salidas estructuradas garantizan el cumplimiento del esquema en la mayoría de los casos, hay escenarios en los que la salida podría no coincidir con tu esquema:

Rechazos (stop_reason: "refusal")

Claude mantiene sus propiedades de seguridad y utilidad incluso al usar salidas estructuradas. Si Claude rechaza una solicitud por motivos de seguridad:

• La respuesta tiene stop_reason: "refusal".
• Recibirás un código de estado 200.
• Se te facturarán los tokens generados.
• La salida podría no coincidir con tu esquema porque el mensaje de rechazo tiene prioridad sobre las restricciones del esquema.

Una propiedad que pida el pensamiento o el razonamiento paso a paso del modelo podría provocar un rechazo reasoning_extraction. En su lugar, pide una explicación breve. Consulta Mantén el razonamiento en los bloques de pensamiento.

Límite de tokens alcanzado (stop_reason: "max_tokens")

Si la respuesta se corta porque alcanzó el límite de max_tokens:

• La respuesta tiene stop_reason: "max_tokens".
• La salida podría estar incompleta y no coincidir con tu esquema.
• Vuelve a intentarlo con un valor de max_tokens más alto para obtener la salida estructurada completa.

Uso de mayúsculas en los valores enum

Las salidas estructuradas no garantizan el uso de mayúsculas en los valores de cadena enum y const: Claude podría devolver un valor que difiere de tu esquema solo en el uso de mayúsculas, normalmente en la primera letra de una palabra que sigue a un espacio. Por ejemplo, dado este esquema:

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

La salida podría contener "Conversation Topic 3" (“T” mayúscula) aunque ese valor exacto no esté en el enum. La respuesta se completa normalmente, sin error y sin un stop_reason especial. Esto se aplica tanto a las salidas JSON como al uso estricto de herramientas. Compara los valores enum sin distinguir entre mayúsculas y minúsculas, y evita valores enum que difieran solo en el uso de mayúsculas.

Límites de complejidad del esquema

Las salidas estructuradas funcionan compilando tus esquemas JSON en una gramática que restringe la salida de Claude. Los esquemas más complejos producen gramáticas más grandes que tardan más en compilarse. Para protegerse contra tiempos de compilación excesivos, la API aplica varios límites de complejidad.

Límites explícitos

Los siguientes límites se aplican a todas las solicitudes con output_config.format o strict: true:

Límites internos adicionales

Además de los límites explícitos de la tabla anterior, existen límites internos adicionales sobre el tamaño de la gramática compilada. Estos límites existen porque la complejidad del esquema no se reduce a una sola dimensión: funciones como los parámetros opcionales, los tipos unión, los objetos anidados y el número de herramientas interactúan entre sí de maneras que pueden hacer que la gramática compilada sea desproporcionadamente grande.

Cuando se superan estos límites, recibirás un error 400 con el mensaje “Schema is too complex for compilation.” Estos errores significan que la complejidad combinada de tus esquemas supera lo que se puede compilar de forma eficiente, incluso si se cumple cada límite individual de la tabla anterior. Como último recurso, la API también aplica un tiempo de espera de compilación de 180 segundos. Los esquemas que pasan todas las comprobaciones explícitas pero producen gramáticas compiladas muy grandes podrían alcanzar este tiempo de espera.

Consejos para reducir la complejidad del esquema

Si estás alcanzando los límites de complejidad, prueba estas estrategias en orden:

1. Marca como estrictas solo las herramientas críticas. Si tienes muchas herramientas, reserva el uso estricto de herramientas para aquellas en las que las infracciones del esquema causan problemas reales, y confía en la adherencia natural de Claude para las herramientas más simples.

2. Reduce los parámetros opcionales. Haz que los parámetros sean required siempre que sea posible. Cada parámetro opcional duplica aproximadamente una parte del espacio de estados de la gramática. Si un parámetro siempre tiene un valor predeterminado razonable, considera hacerlo obligatorio y que Claude proporcione ese valor predeterminado de forma explícita.

3. Simplifica las estructuras anidadas. Los objetos profundamente anidados con campos opcionales agravan la complejidad. Aplana las estructuras siempre que sea posible.

4. Divide en varias solicitudes. Si tienes muchas herramientas estrictas, considera dividirlas en solicitudes separadas o en subagentes.

Para problemas persistentes con esquemas válidos, contacta con soporte con la definición de tu esquema.

Migración desde la beta

El parámetro output_format se ha movido a output_config.format, y los encabezados beta ya no son necesarios. El parámetro output_format está obsoleto. Para usarlo de todos modos, agrega el encabezado beta structured-outputs-2025-11-13. Sin él, la API devuelve un error 400.

En el SDK de Python (v1.0 y posteriores), un diccionario de esquema pasado como output_format={...} genera un TypeError. Usa output_config en su lugar. Un modelo de Pydantic pasado como output_format=Model a parse() o stream() funciona sin cambios y sin encabezado beta, porque el SDK lo envía como output_config. Consulta Uso de un esquema JSON sin procesar para ver la forma actualizada de la API.

Compatibilidad de funciones

Funciona con:

• Procesamiento por lotes: Procesa salidas estructuradas a escala con un descuento del 50 por ciento
• Conteo de tokens: Cuenta tokens sin compilación
• Streaming: Haz streaming de salidas estructuradas como respuestas normales
• Uso combinado: Usa salidas JSON (output_config.format) y uso estricto de herramientas (strict: true) juntos en la misma solicitud

Incompatible con:

• Citas: Las citas requieren intercalar bloques de citas con texto, lo que entra en conflicto con las restricciones estrictas del esquema JSON. La API devuelve un error 400 si las citas están habilitadas con output_config.format. Para extraer datos estructurados con una cita para cada valor, consulta Obtener datos estructurados con citas.
• Prellenado de mensajes: El prellenado es incompatible con las salidas JSON.

Disponibilidad

Los prompts y las respuestas se procesan con ZDR al usar salidas estructuradas. Sin embargo, el esquema JSON en sí se almacena temporalmente en caché durante un máximo de 24 horas desde el último uso con fines de optimización. No se retienen datos de prompts ni de respuestas más allá de la respuesta de la API.

Las salidas estructuradas son aptas para HIPAA, pero no se debe incluir PHI en las definiciones de esquemas JSON. La API compila los esquemas JSON en gramáticas que se almacenan en caché por separado del contenido de los mensajes, y estos esquemas en caché no reciben las mismas protecciones de PHI que los prompts y las respuestas. No incluyas PHI en los nombres de propiedades del esquema, los valores enum, los valores const ni las expresiones regulares pattern. La PHI solo debe aparecer en el contenido de los mensajes (prompts y respuestas), donde está protegida por las salvaguardas de HIPAA.

Próximos pasos