Salidas estructuradas

Las salidas estructuradas restringen las respuestas de Claude para seguir un esquema específico, garantizando una salida válida y analizable para el procesamiento posterior. Usa salidas JSON (output_format) para respuestas de datos estructurados, o uso estricto de herramientas (strict: true) para validación de esquema garantizada en nombres de herramientas e entradas.

Por qué usar salidas estructuradas

Sin salidas estructuradas, Claude puede generar respuestas JSON malformadas o entradas de herramientas inválidas que rompan tus aplicaciones. Incluso con indicaciones cuidadosas, puedes encontrar:

• Errores de análisis de sintaxis JSON inválida
• Campos requeridos faltantes
• Tipos de datos inconsistentes
• Violaciones de esquema que requieren manejo de errores y reintentos

Las salidas estructuradas garantizan respuestas conformes al esquema mediante decodificación restringida:

• Siempre válidas: Sin más errores de JSON.parse()
• Seguras de tipo: Tipos de campo garantizados y campos requeridos
• Confiables: Sin reintentos necesarios para violaciones de esquema
• Dos modos: JSON para tareas como extracción de datos, y herramientas estrictas para situaciones como herramientas complejas y flujos de trabajo de agentes

Inicio rápido

Cuándo usar salidas JSON vs uso estricto de herramientas

Elige el modo correcto para tu caso de uso:

Por qué el uso estricto de herramientas es importante para agentes

Construir sistemas de agentes confiables requiere conformidad de esquema garantizada. Los parámetros de herramientas inválidos rompen tus funciones y flujos de trabajo. Claude podría devolver tipos incompatibles ("2" en lugar de 2) o campos faltantes, causando errores en tiempo de ejecución.

El uso estricto de herramientas garantiza parámetros seguros de tipo:

• Las funciones reciben argumentos correctamente tipados cada vez
• Sin necesidad de validar y reintentar llamadas de herramientas
• Agentes listos para producción que funcionan consistentemente a escala

Por ejemplo, supongamos que un sistema de reservas necesita passengers: int. Sin modo estricto, Claude podría proporcionar passengers: "two" o passengers: "2". Con strict: true, se garantiza passengers: 2.

Cómo funcionan las salidas estructuradas

Trabajar con salidas JSON en SDKs

Los SDKs de Python y TypeScript proporcionan ayudantes que facilitan trabajar con salidas JSON, incluyendo transformación de esquema, validación automática e integración con bibliotecas de esquema populares.

Usando Pydantic y Zod

Para desarrolladores de Python y TypeScript, puedes usar herramientas familiares de definición de esquema como Pydantic y Zod en lugar de escribir esquemas JSON sin procesar.

from pydantic import BaseModel
from anthropic import Anthropic, transform_schema

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

client = Anthropic()

# With .create() - requires transform_schema()
response = client.beta.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format={
        "type": "json_schema",
        "schema": transform_schema(ContactInfo),
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.beta.messages.parse(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    betas=["structured-outputs-2025-11-13"],
    messages=[
        {
            "role": "user",
            "content": "Extract the key information from this email: John Smith ([email protected]) is interested in our Enterprise plan and wants to schedule a demo for next Tuesday at 2pm."
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

Métodos específicos del SDK

Python: client.beta.messages.parse() (Recomendado)

El método parse() transforma automáticamente tu modelo Pydantic, valida la respuesta y devuelve un atributo parsed_output.

Python: ayudante transform_schema()

Para cuando necesites transformar manualmente esquemas antes de enviar, o cuando quieras modificar un esquema generado por Pydantic. A diferencia de client.beta.messages.parse(), que transforma esquemas proporcionados automáticamente, esto te da el esquema transformado para que puedas personalizarlo aún más.

Cómo funciona la transformación de SDK

Ambos SDKs de Python y TypeScript transforman automáticamente esquemas con características no soportadas:

1. Elimina restricciones no soportadas (p. ej., minimum, maximum, minLength, maxLength)
2. Actualiza descripciones con información de restricciones (p. ej., "Debe ser al menos 100"), cuando la restricción no es directamente soportada con salidas estructuradas
3. Añade additionalProperties: false a todos los objetos
4. Filtra formatos de cadena a lista soportada solo
5. Valida respuestas contra tu esquema original (con todas las restricciones)

Esto significa que Claude recibe un esquema simplificado, pero tu código aún refuerza todas las restricciones mediante validación.

Ejemplo: Un campo Pydantic con minimum: 100 se convierte en un entero simple en el esquema enviado, pero la descripción se actualiza a "Debe ser al menos 100", y el SDK valida la respuesta contra la restricción original.

Casos de uso comunes

Consideraciones importantes

Compilación de gramática y almacenamiento en caché

Las salidas estructuradas utilizan muestreo restringido con artefactos de gramática compilada. Esto introduce algunas características de rendimiento a tener en cuenta:

• Latencia de primera solicitud: La primera vez que uses un esquema específico, habrá 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, haciendo que las solicitudes posteriores sean mucho más rápidas
• Invalidación de caché: El caché se invalida si cambias:
  • La estructura del esquema JSON
  • El conjunto de herramientas en tu solicitud (cuando se usan tanto salidas estructuradas como uso de herramientas)
  • Cambiar solo campos name o description no invalida el caché

Modificación de indicación y costos de tokens

Cuando usas salidas estructuradas, Claude recibe automáticamente una indicación de sistema adicional explicando el formato de salida esperado. Esto significa:

• Tu recuento de tokens de entrada será ligeramente mayor
• La indicación inyectada te cuesta tokens como cualquier otra indicación de sistema
• Cambiar el parámetro output_format invalidará cualquier caché de indicación para ese hilo de conversación

Limitaciones de JSON Schema

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

Salidas inválidas

Aunque las salidas estructuradas garantizan conformidad de esquema en la mayoría de los casos, hay escenarios donde la salida puede no coincidir con tu esquema:

Rechazos (stop_reason: "refusal")

Claude mantiene sus propiedades de seguridad y utilidad incluso cuando usa salidas estructuradas. Si Claude rechaza una solicitud por razones de seguridad:

• La respuesta tendrá stop_reason: "refusal"
• Recibirás un código de estado 200
• Se te facturarán los tokens generados
• La salida puede no coincidir con tu esquema (el rechazo tiene prioridad)

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

Si la respuesta se corta debido a alcanzar el límite de max_tokens:

• La respuesta tendrá stop_reason: "max_tokens"
• La salida puede estar incompleta y no coincidir con tu esquema
• Reintenta con un valor de max_tokens más alto para obtener la salida estructurada completa

Errores de validación de esquema

Si tu esquema usa características no soportadas o es demasiado complejo, recibirás un error 400:

"Demasiadas definiciones recursivas en el esquema"

• Causa: El esquema tiene definiciones recursivas excesivas o cíclicas
• Solución: Simplifica la estructura del esquema, reduce la profundidad de anidamiento

"El esquema es demasiado complejo"

• Causa: El esquema excede los límites de complejidad
• Solución: Divide en esquemas más pequeños, simplifica la estructura, o reduce el número de herramientas marcadas como strict: true

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

Compatibilidad de características

Funciona con:

• Procesamiento por lotes: Procesa salidas estructuradas a escala con descuento del 50%
• Conteo de tokens: Cuenta tokens sin compilación
• Streaming: Transmite salidas estructuradas como respuestas normales
• Uso combinado: Usa salidas JSON (output_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 restricciones de esquema JSON estricto. Devuelve error 400 si las citas están habilitadas con output_format.
• Prefijado de mensaje: Incompatible con salidas JSON