Salidas estructuradas

Las "structured outputs" (salidas estructuradas) restringen las respuestas de Claude para que sigan un esquema específico, garantizando una salida válida y analizable para el procesamiento posterior. Las salidas estructuradas proporcionan dos funcionalidades complementarias:

• Salidas JSON (output_config.format): Obtén la respuesta de Claude en un formato JSON específico
• Uso estricto de herramientas (strict: true): Garantiza la validación del esquema en los nombres y entradas de las herramientas

Puedes usar estas funcionalidades 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 inválidas que rompan tus aplicaciones. Incluso con prompts cuidadosos, puedes encontrarte con:

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

Las salidas estructuradas garantizan respuestas que cumplen con el esquema mediante decodificación restringida:

• Siempre válidas: No más errores de JSON.parse()
• Seguridad de tipos: Tipos de campos y campos obligatorios garantizados
• Confiables: No se necesitan reintentos por violaciones del esquema



Salidas JSON

Las salidas JSON controlan el formato de respuesta de Claude, asegurando que Claude devuelva JSON válido que coincida con tu esquema. Usa salidas JSON cuando necesites:

• Controlar el formato de respuesta de Claude
• Extraer datos de imágenes o texto
• Generar informes estructurados
• Formatear respuestas de API



Inicio rápido

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    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_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,
            },
        }
    },
)
print(next(block.text for block in response.content if block.type == "text"))

Formato de respuesta: JSON válido que coincide con tu esquema en el bloque de contenido de texto de la respuesta

{
  "name": "John Smith",
  "email": "[email protected]",
  "plan_interest": "Enterprise",
  "demo_requested": true
}



Cómo funciona



Trabajar con salidas JSON en los SDKs

Los SDKs proporcionan utilidades que facilitan el trabajo con salidas JSON, incluyendo transformación de esquemas, validación automática e integración con bibliotecas de esquemas populares.



Usar definiciones de esquema nativas

En lugar de escribir esquemas JSON sin procesar, puedes usar herramientas de definición de esquemas familiares en tu lenguaje:

• Python: Modelos de Pydantic con client.messages.parse()
• TypeScript: Esquemas de Zod con zodOutputFormat() o literales de JSON Schema tipados con jsonSchemaOutputFormat()
• Java: Clases Java simples con derivación automática de esquemas mediante outputConfig(Class<T>)
• Ruby: Clases Anthropic::BaseModel con output_config: {format: Model}
• PHP: Clases que implementan StructuredOutputModel con outputConfig: ['format' => MyClass::class]
• C#: Clases C# simples con la sobrecarga genérica Create<T>(), que deriva el esquema automáticamente
• Go: Structs de Go reflejados en esquemas JSON automáticamente en la API beta, o esquemas JSON sin procesar mediante output_config
• CLI: Esquemas JSON sin procesar pasados mediante output_config

from pydantic import BaseModel
from anthropic import Anthropic


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


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5",
    max_tokens=1024,
    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

Cada SDK proporciona utilidades que facilitan el trabajo con salidas estructuradas. Consulta las páginas individuales de cada SDK para obtener todos los detalles.

from pydantic import BaseModel
# ...
class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
# ...
response = client.messages.parse(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Extract contact info: John Smith, [email protected], interested in the Pro plan",
        }
    ],
    output_format=ContactInfo,
)

# Accede directamente a la salida analizada
contact = response.parsed_output
print(contact.name, contact.email)

from anthropic import transform_schema
from pydantic import TypeAdapter
# ...

# Primero convierte el modelo de Pydantic a JSON schema, luego transfórmalo
schema = TypeAdapter(ContactInfo).json_schema()
schema = transform_schema(schema)
# Modifica el esquema si es necesario
schema["properties"]["custom_field"] = {"type": "string"}

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "..."}],
    output_config={
        "format": {"type": "json_schema", "schema": schema},
    },
)



Cómo funciona la transformación del SDK

Los SDKs de Python, TypeScript, Ruby y PHP transforman automáticamente esquemas con funcionalidades no compatibles. Los SDKs de C# y Go aplican las mismas transformaciones cuando el esquema se deriva de un tipo nativo (Create<T>() en C#; reflexión de struct o BetaJSONSchemaOutputFormat() en la API beta de Go). Los pasos de transformación:

1. Eliminar restricciones no compatibles (por ejemplo, minimum, maximum, minLength, maxLength)
2. Actualizar descripciones con información de restricciones (por ejemplo, "Must be at least 100"), cuando la restricción no es directamente compatible con salidas estructuradas
3. Agregar additionalProperties: false a todos los objetos
4. Filtrar formatos de cadena solo a la lista compatible
5. Validar respuestas contra tu esquema original (con todas las restricciones)

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

Ejemplo: Un campo de Pydantic con minimum: 100 se convierte en un entero simple en el esquema enviado, pero el SDK actualiza la descripción a "Must be at least 100" y valida la respuesta contra la restricción original.



Casos de uso comunes



Uso estricto de herramientas

Para aplicar el cumplimiento de JSON Schema en las entradas de herramientas con muestreo restringido por gramática, consulta Uso estricto de herramientas.



Usar ambas funcionalidades 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 herramientas con parámetros garantizados como válidos Y devolver respuestas JSON estructuradas. Esto es útil para flujos de trabajo agénticos donde necesitas tanto llamadas a herramientas confiables como salidas finales estructuradas.

response = client.messages.create(
    model="claude-opus-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 herramienta 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 de gramática y almacenamiento en caché

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

• Latencia de la primera solicitud: La primera vez que usas un esquema específico, hay 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 caché: La caché se invalida si cambias:
  • La estructura del esquema JSON
  • El conjunto de herramientas en tu solicitud (cuando usas tanto salidas estructuradas como uso de herramientas)
  • 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 indicación del sistema adicional que explica el formato de salida esperado. Esto significa:

• 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 invalidará 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.



Orden de propiedades

Al usar salidas estructuradas, las propiedades en los objetos mantienen su 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 ordenará las propiedades así:

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

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

{
  "name": "John Smith",
  "email": "[email protected]",
  "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 inválidas

Aunque las salidas estructuradas garantizan el cumplimiento del 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 tiene 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 porque el mensaje de rechazo tiene prioridad sobre las restricciones del esquema

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

Si la respuesta se corta debido a que se alcanzó el límite de max_tokens:

• La respuesta tiene 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

Mayúsculas en valores de enum

Las salidas estructuradas no garantizan el uso de mayúsculas en los valores de enum y const de tipo string: Claude puede devolver un valor que difiere de tu esquema solo en el uso de mayúsculas, típicamente 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 puede 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 aplica tanto a las salidas JSON como al uso estricto de herramientas. Compara los valores de enum sin distinguir mayúsculas de minúsculas, y evita valores de 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 proteger 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

Más allá de los límites explícitos en la tabla anterior, hay 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: funcionalidades como parámetros opcionales, tipos unión, objetos anidados y número de herramientas interactúan entre sí de maneras que pueden hacer que la gramática compilada sea desproporcionadamente grande.

Cuando se exceden 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 excede lo que se puede compilar eficientemente, incluso si cada límite individual en la tabla anterior se cumple. Como última medida de protección, la API también aplica un tiempo de espera de compilación de 180 segundos. Los esquemas que pasan todas las verificaciones explícitas pero producen gramáticas compiladas muy grandes pueden alcanzar este tiempo de espera.



Consejos para reducir la complejidad del esquema

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

1. Marca solo las herramientas críticas como estrictas. Si tienes muchas herramientas, resérvalo para herramientas donde las violaciones del esquema causen problemas reales, y confía en la adherencia natural de Claude para herramientas más simples.

2. Reduce los parámetros opcionales. Haz que los parámetros sean required cuando sea posible. Cada parámetro opcional aproximadamente duplica una porción 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 explícitamente.

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

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

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



Retención de datos

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é hasta 24 horas desde el último uso con fines de optimización. No se retienen datos de prompts ni respuestas más allá de la respuesta de la API.

Las salidas estructuradas son elegibles 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 nombres de propiedades del esquema, valores de enum, valores de const o expresiones regulares de pattern. La PHI solo debe aparecer en el contenido de los mensajes (prompts y respuestas), donde está protegida bajo las salvaguardas de HIPAA.

Para la elegibilidad de ZDR y HIPAA en todas las funcionalidades, consulta API y retención de datos.



Compatibilidad de funcionalidades

Funciona con:

• Procesamiento por lotes: Procesa salidas estructuradas a escala con un 50% de descuento
• Conteo de tokens: Cuenta tokens sin compilación
• Streaming: Transmite 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. Devuelve un error 400 si las citas están habilitadas con output_config.format.
• Prellenado de mensajes: Incompatible con salidas JSON



Próximos pasos