Salidas estructuradas

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

• 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 de herramientas y sus entradas

Estas características pueden usarse 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 no válidas que rompen tus aplicaciones. Incluso con un prompting cuidadoso, puedes encontrarte con:

• Errores de análisis por sintaxis JSON no vá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: No más errores de JSON.parse()
• Seguras en tipos: Tipos de campo y campos requeridos garantizados
• Confiables: No se necesitan reintentos por 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

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

Uso de definiciones de esquemas nativas

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

• Python: modelos Pydantic con client.messages.parse()
• TypeScript: esquemas Zod con zodOutputFormat()
• Java: clases Java simples con derivación automática de esquemas mediante outputFormat(Class<T>)
• Ruby: clases Anthropic::BaseModel con output_config: {format: Model}
• C#, Go, PHP: esquemas JSON sin procesar pasados mediante output_config

Métodos específicos del SDK

Cada SDK proporciona ayudantes que facilitan el trabajo con salidas estructuradas. Consulta las páginas individuales del SDK para obtener detalles completos.

Cómo funciona la transformación del SDK

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

1. Eliminar restricciones no admitidas (por ejemplo, minimum, maximum, minLength, maxLength)
2. Actualizar descripciones con información de restricciones (por ejemplo, "Debe ser al menos 100"), cuando la restricción no es directamente compatible con las salidas estructuradas
3. Agregar additionalProperties: false a todos los objetos
4. Filtrar formatos de cadena solo a la lista admitida
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 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 los parámetros de las herramientas, asegurando que Claude llame a tus funciones con argumentos correctamente tipados. Usa el uso estricto de herramientas cuando necesites:

• Validar parámetros de herramientas
• Construir flujos de trabajo agénticos
• Garantizar llamadas a funciones con tipos seguros
• Manejar herramientas complejas con propiedades anidadas

Por qué el uso estricto de herramientas importa para los agentes

Construir sistemas agénticos confiables requiere conformidad garantizada con el esquema. Sin el 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 con tipos seguros:

• Las funciones reciben argumentos correctamente tipados en todo momento
• No es necesario validar y reintentar llamadas a herramientas
• Agentes listos para producción que funcionan de manera consistente a escala

Por ejemplo, supongamos que un sistema de reservas necesita passengers: int. Sin el modo estricto, Claude podría proporcionar passengers: "two" o passengers: "2". Con strict: true, la respuesta siempre contendrá passengers: 2.

Inicio rápido

Formato de respuesta: Bloques de uso de herramientas con entradas validadas 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 las herramientas proporcionadas o herramientas del servidor)

Cómo funciona

Casos de uso comunes

Usar ambas funciones juntas

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

• Salidas JSON controlan el formato de respuesta de Claude (lo que Claude dice)
• Uso estricto de herramientas valida los parámetros de las herramientas (cómo Claude llama a sus 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 donde necesita tanto llamadas de herramientas confiables como salidas finales estructuradas.

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 que debe tener en cuenta:

• Latencia en la primera solicitud: La primera vez que usa 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, lo que hace que las solicitudes posteriores sean mucho más rápidas
• Invalidación del caché: El caché se invalida si cambia:
  • La estructura del esquema JSON
  • El conjunto de herramientas en su solicitud (cuando usa tanto salidas estructuradas como uso de herramientas)
  • Cambiar solo los campos name o description no invalida el caché

Modificación de prompts y costos de tokens

Al usar salidas estructuradas, Claude recibe automáticamente un prompt de sistema adicional que explica el formato de salida esperado. Esto significa:

• Su recuento de tokens de entrada será ligeramente mayor
• El prompt inyectado le cuesta tokens como cualquier otro prompt de sistema
• Cambiar el parámetro output_config.format invalidará cualquier caché de prompts para ese hilo de conversación

Limitaciones del esquema JSON

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

Ordenamiento de propiedades

Al usar salidas estructuradas, las propiedades en los objetos mantienen su orden definido en su esquema, con una advertencia importante: las propiedades requeridas 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 como:

1. name (requerido, en el orden del esquema)
2. email (requerido, 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": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Si el orden de las propiedades en la salida es importante para su aplicación, asegúrese de que todas las propiedades estén marcadas como requeridas, o tenga en cuenta este reordenamiento en su lógica de análisis.

Salidas no válidas

Si bien las salidas estructuradas garantizan el cumplimiento del esquema en la mayoría de los casos, hay escenarios en los que la salida puede no coincidir con su 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á un código de estado 200
• Se le facturarán los tokens generados
• La salida puede no coincidir con su 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 interrumpe 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 su esquema
• Reintente con un valor de max_tokens más alto para obtener la salida estructurada completa

Límites de complejidad del esquema

Las salidas estructuradas funcionan compilando sus 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, 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: características como parámetros opcionales, tipos de 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 superan estos límites, recibirá un error 400 con el mensaje "Schema is too complex for compilation." Estos errores significan que la complejidad combinada de sus esquemas supera lo que se puede compilar eficientemente, incluso si cada límite individual anterior se cumple. Como medida de ú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á alcanzando los límites de complejidad, pruebe estas estrategias en orden:

1. Marque solo las herramientas críticas como estrictas. Si tiene muchas herramientas, resérvelo para las herramientas donde las violaciones del esquema causan problemas reales, y confíe en la adherencia natural de Claude para las herramientas más simples.

2. Reduzca los parámetros opcionales. Haga que los parámetros sean required donde 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, considere hacerlo requerido y que Claude proporcione ese valor predeterminado explícitamente.

3. Simplifique las estructuras anidadas. Los objetos profundamente anidados con campos opcionales aumentan la complejidad. Aplane las estructuras donde sea posible.

4. Divida en múltiples solicitudes. Si tiene muchas herramientas estrictas, considere dividirlas en solicitudes separadas o sub-agentes.

Para problemas persistentes con esquemas válidos, contacte al soporte con la definición de su esquema.

Retención de datos

Los prompts y las 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 con fines de optimización. No se retienen datos de prompts o respuestas más allá de la respuesta de la API.

Para la elegibilidad de ZDR en todas las funciones, consulte API y Retención de Datos.

Compatibilidad de funciones

Funciona con:

• Procesamiento por lotes: Procese salidas estructuradas a escala con un 50% de descuento
• Conteo de tokens: Cuente tokens sin compilación
• Streaming: Transmita salidas estructuradas como respuestas normales
• Uso combinado: Use 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