Salidas estructuradas para los modelos de Anthropic Claude en Amazon Bedrock

Amazon Bedrock ahora admite salidas estructuradas para todos los modelos de Anthropic Claude, tanto en el endpoint bedrock-runtime como en bedrock-mantle, donde el modelo esté disponible.

Ya sea que llame a Claude a través de Boto3 y las API de bedrock-runtime o a través de la Messages API y el endpoint bedrock-mantle, ahora puede recibir respuestas JSON conformes al esquema que se ajustan a una estructura definida. Ya no necesita análisis personalizados, lógica de reintentos ni posprocesamiento.

Aplicaciones prácticas

Con las salidas estructuradas de Claude en Amazon Bedrock, puede automatizar tareas confiables y conformes al esquema en diversos sectores. Algunos ejemplos incluyen extraer cada campo requerido de informes financieros de resultados y documentos de cumplimiento, analizar notas clínicas para incorporarlas a Historias Clínicas Electrónicas (EHR) y enriquecer catálogos de productos con resultados consistentes y validados. También puede analizar contratos en busca de términos clave, partes y obligaciones, o impulsar el enrutamiento inteligente de tickets de soporte donde las intenciones, los sentimientos y las entidades siempre coincidan con el modelo de datos de su aplicación.

Qué cambia con las salidas estructuradas en Amazon Bedrock

Las salidas estructuradas utilizan decodificación restringida para aplicar su esquema JSON durante la generación de tokens, no después. El modelo no produce tokens que violarían su esquema. Esto cambia el formato de salida de probabilístico a determinista.

Ahora hay disponibles dos mecanismos complementarios en ambos endpoints de Amazon Bedrock:

Qué significa esto para usted

Cada respuesta es un JSON válido, por lo que ya no se encuentra con JSON.parse() errores ni excepciones de análisis. Las respuestas también son seguras en cuanto a tipos: los tipos de campos se aplican y los campos obligatorios siempre están presentes. Dado que las salidas siempre se ajustan a su esquema, no necesita reintentos para manejar violaciones del esquema, lo que hace que su integración sea más confiable. Las salidas estructuradas también restringen las respuestas únicamente a los campos que define su esquema, lo que reduce el conteo de tokens de salida y puede disminuir los costos de inferencia para cargas de trabajo de alto volumen. Estas propiedades hacen que las salidas estructuradas estén listas para producción, por lo que puede implementar a escala sin código adicional de validación de esquemas.

Modelos compatibles y disponibilidad

Las salidas estructuradas funcionan con inferencia por lotes, de modo que puede procesar grandes volúmenes de solicitudes de forma asíncrona mientras recibe salidas conformes al esquema. En el endpoint bedrock-runtime, también funciona con la inferencia entre Regiones, por lo que puede usarla en todas las Regiones de AWS sin configuración adicional. Si necesita respuestas en tiempo real, puede transmitir respuestas estructuradas como eventos tipados.

Cómo funciona

Cuando realiza una solicitud con un esquema JSON, esto es lo que sucede en segundo plano:

1. Validación del esquema – Amazon Bedrock valida su esquema JSON contra el subconjunto compatible de JSON Schema Draft 2020-12.
2. Compilación de la gramática – Para esquemas nuevos, Amazon Bedrock compila un artefacto de gramática (la primera solicitud puede tardar un poco más).
3. Almacenamiento en caché – Las gramáticas compiladas se almacenan en caché durante 24 horas, lo que hace que las solicitudes posteriores sean más rápidas.
4. Generación restringida – El modelo genera tokens que producen JSON válido que coincide con su esquema.

Consideraciones de rendimiento

Por razones de rendimiento, la primera solicitud con un esquema nuevo podría tardar más porque Amazon Bedrock compila un artefacto de gramática antes de que comience la generación. Después de esa compilación inicial, las solicitudes posteriores que usen el mismo esquema se ejecutan con una sobrecarga mínima porque la gramática compilada está almacenada en caché. Esta caché tiene el ámbito de su cuenta y dura 24 horas desde el primer acceso. Cambiar la estructura de su esquema JSON invalida la caché y activa una nueva compilación, mientras que cambiar solo los campos name o description deja intacta la gramática almacenada en caché.

Primeros pasos: salidas estructuradas con la API InvokeModel (bedrock-runtime)

La API InvokeModel toma el cuerpo de la solicitud nativo de Anthropic, por lo que el esquema va output_config.format como un objeto JSON en lugar de una cadena JSON. El siguiente ejemplo muestra cómo extraer los datos estructurados de prospectos de un correo electrónico de cliente usando boto3 con un modelo de Anthropic Claude:

Python

import boto3
import json

REGION = "us-east-1" # Choose your preferred region
bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)

# Define the JSON schema for structured output
schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "description": "Customer name"},
        "email": {"type": "string", "description": "Customer email address"},
        "plan_interest": {"type": "string", "description": "Product plan of interest"},
        "demo_requested": {"type": "boolean", "description": "Whether a demo was requested"}
    },
    "required": ["name", "email", "plan_interest", "demo_requested"],
    "additionalProperties": False
}

# Make a request with structured outputs via the InvokeModel API
# (reusing the schema defined for the Converse example)
response = bedrock_runtime.invoke_model(
    modelId="global.anthropic.claude-sonnet-5-5",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 512,
        "messages": [
            {"role": "user", "content": (
                "Paulo Santos (paulo@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            )}
        ],
        "output_config": {"format": {"type": "json_schema", "schema": schema}}
    })
)

body = json.loads(response["body"].read())

# Check the stop reason before parsing
if body["stop_reason"] == "end_turn":
    result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
    print(json.dumps(json.loads(result_text), indent=2))
elif body["stop_reason"] == "max_tokens":
    print("Response truncated: increase max_tokens and retry.")

JSON

{
    "name": "Paulo Santos",
    "email": "paulo@example.com",
    "plan_interest": "Enterprise",
    "demo_requested": true
}

La respuesta se ajusta a su esquema. No se requiere validación adicional.

Para más ejemplos de uso de la API, incluida la API de Messages, consulte el cuaderno de ejemplo.

Uso estricto de herramientas para flujos de trabajo agénticos

Amazon Bedrock Mantle está diseñado para aplicaciones agénticas con herramientas del lado del servidor, inferencia en segundo plano y conversaciones con estado. Con el uso estricto de herramientas en el punto de conexión bedrock-mantle, ahora puede garantizar que los parámetros de las herramientas coincidan exactamente con su esquema de entrada. El siguiente ejemplo muestra cómo definir una herramienta con aplicación estricta del esquema:

Import json
from anthropic import AnthropicBedrockMantle

# Reusing the client created in the Messages API example
client = AnthropicBedrockMantle(aws_region="us-east-1")

message = client.messages.create(
    model="anthropic.claude-sonnet-5",
    max_tokens=512,
    messages=[{"role": "user", "content": "What's the weather like in San Francisco?"}],
    tools=[
        {
            "name": "get_weather",
            "description": "Get the current weather for a specified 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"],
                        "description": "Temperature unit"
                    }
                },
                "required": ["location", "unit"],
                "additionalProperties": False
            }
        }
    ]
)

#Tool inputs conform to the schema
for block in message.content:
    if block.type == "tool_use":
        print(f"Tool: {block.name}")
        print(f"Input: {json.dumps(block.input, indent=2)}")

Establecer strict: true restringe la entrada de la herramienta del modelo para que coincida exactamente con su esquema. El campo location siempre es una cadena, y el campo unit siempre es celsius o fahrenheit. El modelo no puede agregar campos fuera de su esquema, por lo que la entrada de la herramienta contiene solo lo que su esquema especifica.

Esto es especialmente valioso para los casos de uso agénticos en Amazon Bedrock Mantle, donde los modelos orquestan flujos de trabajo de varios pasos con herramientas del lado del servidor como la búsqueda web y el intérprete de código.

Principales casos de uso para las salidas estructuradas de Claude

Las salidas estructuradas reducen la complejidad del manejo de errores principalmente en tres patrones comunes:

• Extracción de datos: Extraiga campos de facturas, contratos, correos electrónicos y transcripciones a JSON que siempre coincida con su esquema, listo para cargar en bases de datos o sistemas de gestión de relaciones con clientes (CRM).
• Llamadas confiables a herramientas de agente: Valide los argumentos de las herramientas contra sus esquemas en el momento de la generación, para que los flujos de trabajo de agentes de varios pasos se ejecuten sin fallos por entrada malformada.
• Clasificación a escala: Clasifique tickets, prospectos o contenidos por intención, prioridad y sentimiento para enrutamiento, moderación y evaluación.

Claude Haiku 5.5 maneja de manera confiable cargas de trabajo rápidas y repetitivas, como resúmenes, compactaciones, consultas a bases de datos y solicitudes de clasificación. El siguiente ejemplo muestra cómo clasificar y enrutar datos entrantes usando la API Invoke y Haiku 5.5:

import boto3
import json

REGION = "us-east-1" # Choose your preferred region
bedrock_runtime = boto3.client(service_name="bedrock-runtime", region_name=REGION)

# Classification schema: enums restrict output to a fixed set of labels
schema = {
    "type": "object",
    "properties": {
        "category": {
            "type": "string",
            "enum": ["billing", "technical", "account", "sales", "other"],
            "description": "Primary ticket category"
        },
        "priority": {
            "type": "string",
            "enum": ["low", "medium", "high", "urgent"],
            "description": "Urgency based on business impact"
        },
        "sentiment": {
            "type": "string",
            "enum": ["positive", "neutral", "negative"],
            "description": "Customer sentiment"
        },
        "escalate": {"type": "boolean", "description": "Whether a human should review immediately"},
        "reason": {"type": "string", "description": "One-sentence justification for the classification"}
    },
    "required": ["category", "priority", "sentiment", "escalate", "reason"],
    "additionalProperties": False
}

ticket = (
    "Our production API calls have been failing with 500 errors since this morning. "
    "We're losing orders every minute. This is the second outage this month!"
)

# Make a request with structured outputs via the InvokeModel API
response = bedrock_runtime.invoke_model(
    modelId="global.anthropic.claude-haiku-5-5",
    body=json.dumps({
        "anthropic_version": "bedrock-2023-05-31",
        "max_tokens": 512,
        "system": "You are a support ticket classifier. Classify the ticket accurately.",
        "messages": [
            {"role": "user", "content": f"Classify this support ticket:\n\n{ticket}"}
        ],
        "output_config": {"format": {"type": "json_schema", "schema": schema}}
    })
)

body = json.loads(response["body"].read())

# Check the stop reason before parsing
if body["stop_reason"] == "end_turn":
    result_text = next(b["text"] for b in body["content"] if b["type"] == "text")
    result = json.loads(result_text)
    print(json.dumps(result, indent=2))
    # Route the ticket based on the guaranteed-valid labels
    if result["escalate"]:
        print(f"Escalating to on-call: {result['category']} / {result['priority']}")
elif body["stop_reason"] == "max_tokens":
    print("Response truncated: increase max_tokens and retry.")

Requisitos y mejores prácticas

Para usar las salidas estructuradas de manera efectiva en Amazon Bedrock, siga estas pautas:

1. Establezca additionalProperties: false en todos los objetos: Esto es necesario para que las salidas estructuradas funcionen. Sin ello, su esquema no será aceptado.
2. Use nombres de campos y descripciones descriptivos: Los modelos usan los nombres y descripciones de las propiedades para entender qué datos extraer. Nombres claros como customer_email superan a los nombres genéricos como field1.
3. Use enum para valores restringidos: Cuando un campo tiene un conjunto limitado de valores válidos, use enum para restringir las opciones.
4. Empiece con lo básico y luego añada complejidad: Comience con los campos mínimos requeridos y añada complejidad de forma incremental. Los esquemas básicos se compilan más rápido, son más fáciles de depurar y mantienen el payload de su solicitud ligero, porque el esquema cuenta para el tamaño del payload de la API Converse.
5. Reutilice esquemas para beneficiarse del almacenamiento en caché: Estructure su aplicación para reutilizar esquemas entre solicitudes. La caché de gramática de 24 horas mejora el rendimiento en consultas repetidas.
6. Compruebe el motivo de detención en cada respuesta: Dos escenarios pueden producir respuestas no conformes: los rechazos (cuando el modelo declina por razones de seguridad) y los límites de tokens (cuando se max_tokens alcanza antes de completarse). Maneje ambos casos en su código.
7. Pruebe con datos realistas antes de la implementación: Valide sus esquemas con entradas representativas de producción. Los casos límite en datos reales suelen revelar problemas de diseño del esquema.

Para prácticas recomendadas adicionales y recomendaciones de diseño de esquemas, consulte Structured outputs en la Amazon Bedrock User Guide.

Características de JSON Schema admitidas

1. Todos los tipos básicos: object, array, string, integer, number, boolean, null.
2. enum (solo cadenas, números, booleanos o nulos).
3. const, anyOf, allOf (con limitaciones).
4. $ref, $def, y definitions (solo referencias internas).
5. Formatos de cadena: date-time, time, date, duration, email, hostname, uri, ipv4, ipv6, uuid.
6. Array minItems (solo los valores 0 y 1).

No compatible

Estas palabras clave son aceptadas por la API, pero no se aplican durante la generación. Una solicitud que las incluya devuelve una respuesta exitosa, y el modelo todavía puede devolver valores que las violen. Valide estas restricciones en su aplicación en lugar de confiar en el esquema para aplicarlas.

1. Esquemas recursivos.
2. Externas $ref referencias.
3. Restricciones numéricas (minimum, maximum, multipleOf).
4. Restricciones de cadena (minLength, maxLength).
5. additionalProperties configurado con cualquier valor distinto de false.

Conclusión

Las salidas estructuradas para los modelos Anthropic Claude en Amazon Bedrock proporcionan la fiabilidad que requieren las aplicaciones de IA de producción. Está disponible ahora tanto en los endpoints bedrock-runtime como bedrock-mantle. Al combinar el formato de salida JSON Schema y el uso estricto de herramientas, puede construir canalizaciones de datos que no necesitan validación adicional. También puede crear flujos de trabajo agénticos fiables y aplicaciones de IA de producción sin lógica de análisis personalizada ni reintentos.

Las salidas estructuradas para Claude en Amazon Bedrock ya están disponibles de forma general. Para obtener más información, consulte la documentación de Amazon Bedrock y explore nuestro cuaderno de ejemplo.

¿Qué flujos de trabajo de su organización podrían mejorar con JSON validado y conforme a esquemas? Comparta sus comentarios y preguntas en los comentarios.

Sobre los autores