Salidas estructuradas

Las salidas estructuradas restringen las respuestas de Claude para seguir un esquema específico, asegurando una salida válida y analizable para el procesamiento posterior. Las salidas estructuradas proporcionan dos características 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 validación de esquema en nombres de herramientas e entradas

Puedes usar estas características de forma independiente o juntas en la misma solicitud.

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

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-4-7",
    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(response.content[0].text)

Formato de respuesta: JSON válido que coincide con tu esquema en response.content[0].text

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

Cómo funciona

Trabajar con salidas JSON en SDKs

Los SDKs proporcionan ayudantes 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, puede usar herramientas de definición de esquema familiares en su idioma:

• 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 esquema a través de outputConfig(Class<T>)
• Ruby: Clases Anthropic::BaseModel con output_config: {format: Model}
• PHP: Clases que implementan StructuredOutputModel con outputConfig: ['format' => MyClass::class]
• CLI, C#, Go: Esquemas JSON sin procesar pasados a través de 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-4-7",
    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 ayudantes que facilitan el trabajo con salidas estructuradas. Consulte las páginas individuales del SDK para obtener detalles completos.

Cómo funciona la transformación del SDK

Los SDKs de Python, TypeScript, Ruby y PHP transforman automáticamente esquemas con características no admitidas:

1. Eliminar restricciones no admitidas (por ejemplo, minimum, maximum, minLength, maxLength)
2. Actualizar descripciones con información de restricción (por ejemplo, "Debe ser al menos 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 a la lista admitida solo
5. Validar respuestas contra su esquema original (con todas las restricciones)

Esto significa que Claude recibe un esquema simplificado, pero su código aún aplica todas las restricciones a través de validación.

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

Casos de uso comunes

Uso estricto de herramientas

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

Usar ambas características juntas

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

• Salidas JSON controlan el formato de respuesta de Claude (qué dice Claude)
• Uso estricto de herramientas valida los parámetros de 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 de agentes donde necesitas tanto llamadas de herramientas confiables como salidas finales estructuradas.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # JSON outputs: structured response format
    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,
            },
        }
    },
    # Strict tool use: guaranteed tool parameters
    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 utilizan muestreo restringido con artefactos de gramática compilada. Esto introduce algunas características de rendimiento de las que debes ser consciente:

• Latencia de primera solicitud: La primera vez que uses 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é: 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 los campos name o description no invalida el caché

Modificación de indicaciones y costos de tokens

Cuando usas salidas estructuradas, Claude recibe automáticamente un indicador de sistema adicional que explica el formato de salida esperado. Esto significa:

• Tu recuento de tokens de entrada es ligeramente superior
• El indicador inyectado te cuesta tokens como cualquier otro indicador de sistema
• Cambiar el parámetro output_config.format invalidará cualquier caché de indicaciones para ese hilo de conversación

Limitaciones de esquema JSON

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

Orden de propiedades

Cuando usas salidas estructuradas, las propiedades en objetos mantienen su orden definido desde tu esquema, con una salvedad importante: las propiedades requeridas aparecen primero, seguidas por 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 como:

1. name (requerido, en orden de esquema)
2. email (requerido, en orden de esquema)
3. notes (opcional, en orden de esquema)
4. age (opcional, en orden de 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 propiedades en la salida es importante para tu aplicación, marca todas las propiedades como requeridas o ten en cuenta este reordenamiento en tu lógica de análisis.

Salidas inválidas

Aunque las salidas estructuradas garantizan cumplimiento 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 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 de esquema

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

Límites de complejidad de 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

Más allá de los límites explícitos anteriores, hay límites internos adicionales en 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: características como parámetros opcionales, tipos de unión, objetos anidados y número de herramientas interactúan entre sí de formas 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 anterior se satisface. Como último recurso, 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, intenta estas estrategias en orden:

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

2. Reduce parámetros opcionales. Haz que los parámetros sean required donde sea posible. Cada parámetro opcional aproximadamente duplica una porción del espacio de estado de la gramática. Si un parámetro siempre tiene un valor predeterminado razonable, considera hacerlo requerido y tener a Claude proporcionar ese valor predeterminado explícitamente.

3. Simplifica estructuras anidadas. Los objetos profundamente anidados con campos opcionales componen la complejidad. Aplana estructuras donde sea posible.

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

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

Retención de datos

Los indicadores y respuestas se procesan con ZDR cuando se usan salidas estructuradas. Sin embargo, el esquema JSON en sí se almacena temporalmente en caché durante hasta 24 horas desde el último uso para fines de optimización. No se retienen datos de indicadores o respuestas más allá de la respuesta de la API.

Las salidas estructuradas son elegibles para HIPAA, pero PHI no debe incluirse en definiciones de esquema JSON. La API compila esquemas JSON en gramáticas que se almacenan en caché separadamente del contenido del mensaje, y estos esquemas almacenados en caché no reciben las mismas protecciones de PHI que los indicadores y respuestas. No incluyas PHI en nombres de propiedades de esquema, valores de enum, valores de const o expresiones regulares de pattern. PHI debe aparecer solo en contenido de mensaje (indicadores y respuestas), donde está protegido bajo salvaguardas de HIPAA.

Para elegibilidad de ZDR e HIPAA en todas las características, consulta Retención de API y datos.

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_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 restricciones de esquema JSON estricto. Devuelve error 400 si las citas están habilitadas con output_config.format.
• Rellenado de mensajes: Incompatible con salidas JSON