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. Hay dos características complementarias disponibles:

• Salidas JSON (output_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 inputs

Estas características se pueden usar de forma independiente o juntas en la misma solicitud.

Por qué usar salidas estructuradas

Sin salidas estructuradas, Claude puede generar respuestas JSON malformadas o inputs de herramientas inválidos que rompan tus aplicaciones. Incluso con un prompting cuidadoso, 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álido: No más errores de JSON.parse()
• Type safe: Tipos de campo garantizados y campos requeridos
• Confiable: No se necesitan reintentos 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 reportes estructurados
• Formatear respuestas de API

Inicio rápido

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: structured-outputs-2025-11-13" \
  -d '{
    "model": "claude-sonnet-4-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": {
      "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
      }
    }
  }'

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 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 de definición de esquema familiares 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 del SDK

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

1. Elimina restricciones no soportadas (por ejemplo, minimum, maximum, minLength, maxLength)
2. Actualiza descripciones con información de restricciones (por ejemplo, "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

Uso estricto de herramientas

El uso estricto de herramientas valida parámetros de herramientas, asegurando que Claude llame a tus funciones con argumentos correctamente tipados. Usa uso estricto de herramientas cuando necesites:

• Validar parámetros de herramientas
• Construir flujos de trabajo de agentes
• Asegurar llamadas de función type-safe
• Manejar herramientas complejas con propiedades anidadas

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

Construir sistemas de agentes confiables requiere conformidad de esquema garantizada. Sin modo estricto, Claude podría devolver tipos incompatibles ("2" en lugar de 2) o campos requeridos faltantes, rompiendo tus funciones y causando errores en tiempo de ejecución.

El uso estricto de herramientas garantiza parámetros type-safe:

• Las funciones reciben argumentos correctamente tipados cada vez
• No hay 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, la respuesta siempre contendrá passengers: 2.

Inicio rápido

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: structured-outputs-2025-11-13" \
  -d '{
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "What is the weather in San Francisco?"}
    ],
    "tools": [{
      "name": "get_weather",
      "description": "Get the current weather in a given location",
      "strict": true,
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string",
            "description": "The city and state, e.g. San Francisco, CA"
          },
          "unit": {
            "type": "string",
            "enum": ["celsius", "fahrenheit"]
          }
        },
        "required": ["location"],
        "additionalProperties": false
      }
    }]
  }'

Formato de respuesta: Bloques de uso de herramientas con inputs validados en response.content[x].input

{
  "type": "tool_use",
  "name": "get_weather",
  "input": {
    "location": "San Francisco, CA"
  }
}

Garantías:

• El input de la herramienta sigue estrictamente el input_schema
• El name de la herramienta siempre es válido (de herramientas proporcionadas o herramientas del servidor)

Cómo funciona

Casos de uso comunes

Usando ambas características juntas

Las salidas JSON y el uso estricto de herramientas resuelven diferentes problemas y se pueden usar juntas:

• Salidas JSON controlan el formato de respuesta de Claude (lo que Claude dice)
• Uso estricto de herramientas valida parámetros de herramientas (cómo Claude llama a tus funciones)

Cuando se combinan, Claude puede llamar a herramientas con parámetros garantizados 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.beta.messages.create(
    model="claude-sonnet-4-5",
    betas=["structured-outputs-2025-11-13"],
    max_tokens=1024,
    messages=[{"role": "user", "content": "Help me plan a trip to Paris for next month"}],
    # JSON outputs: structured response format
    output_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
        }
    }]
)

Consideraciones importantes

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

Las salidas estructuradas utilizan muestreo restringido con artefactos de gramática compilados. 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 prompt y costos de tokens

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

• Tu recuento de tokens de entrada será ligeramente mayor
• El prompt inyectado te cuesta tokens como cualquier otro prompt de sistema
• Cambiar el parámetro output_format invalidará cualquier caché de prompt 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 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 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:

"Too many recursive definitions in schema"

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

"Schema is too complex"

• 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.
• Prefilling de mensajes: Incompatible con salidas JSON