Saídas estruturadas

Saídas estruturadas restringem as respostas do Claude a seguir um esquema específico, garantindo uma saída válida e analisável para processamento posterior. Dois recursos complementares estão disponíveis:

• Saídas JSON (output_format): Obtenha a resposta do Claude em um formato JSON específico
• Uso rigoroso de ferramentas (strict: true): Garanta validação de esquema em nomes de ferramentas e entradas

Esses recursos podem ser usados independentemente ou juntos na mesma solicitação.

Por que usar saídas estruturadas

Sem saídas estruturadas, Claude pode gerar respostas JSON malformadas ou entradas de ferramentas inválidas que quebram suas aplicações. Mesmo com prompts cuidadosos, você pode encontrar:

• Erros de análise de sintaxe JSON inválida
• Campos obrigatórios ausentes
• Tipos de dados inconsistentes
• Violações de esquema que exigem tratamento de erros e novas tentativas

Saídas estruturadas garantem respostas em conformidade com o esquema através de decodificação restrita:

• Sempre válido: Sem mais erros de JSON.parse()
• Seguro em tipo: Tipos de campo garantidos e campos obrigatórios
• Confiável: Sem necessidade de novas tentativas para violações de esquema

Saídas JSON

Saídas JSON controlam o formato de resposta do Claude, garantindo que Claude retorne JSON válido correspondente ao seu esquema. Use saídas JSON quando você precisar:

• Controlar o formato de resposta do Claude
• Extrair dados de imagens ou texto
• Gerar relatórios estruturados
• Formatar respostas de API

Início 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 resposta: JSON válido correspondente ao seu esquema em response.content[0].text

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

Como funciona

Trabalhando com saídas JSON em SDKs

Os SDKs Python e TypeScript fornecem auxiliares que facilitam o trabalho com saídas JSON, incluindo transformação de esquema, validação automática e integração com bibliotecas de esquema populares.

Usando Pydantic e Zod

Para desenvolvedores Python e TypeScript, você pode usar ferramentas familiares de definição de esquema como Pydantic e Zod em vez de escrever esquemas JSON brutos.

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

Python: client.beta.messages.parse() (Recomendado)

O método parse() transforma automaticamente seu modelo Pydantic, valida a resposta e retorna um atributo parsed_output.

Python: auxiliar transform_schema()

Para quando você precisa transformar manualmente esquemas antes de enviar, ou quando deseja modificar um esquema gerado por Pydantic. Diferentemente de client.beta.messages.parse(), que transforma esquemas fornecidos automaticamente, isso fornece o esquema transformado para que você possa personalizá-lo ainda mais.

Como funciona a transformação do SDK

Os SDKs Python e TypeScript transformam automaticamente esquemas com recursos não suportados:

1. Remova restrições não suportadas (por exemplo, minimum, maximum, minLength, maxLength)
2. Atualize descrições com informações de restrição (por exemplo, "Deve ser pelo menos 100"), quando a restrição não é diretamente suportada com saídas estruturadas
3. Adicione additionalProperties: false a todos os objetos
4. Filtre formatos de string para lista suportada apenas
5. Valide respostas contra seu esquema original (com todas as restrições)

Isso significa que Claude recebe um esquema simplificado, mas seu código ainda impõe todas as restrições através de validação.

Exemplo: Um campo Pydantic com minimum: 100 se torna um inteiro simples no esquema enviado, mas a descrição é atualizada para "Deve ser pelo menos 100", e o SDK valida a resposta contra a restrição original.

Casos de uso comuns

Uso rigoroso de ferramentas

Uso rigoroso de ferramentas valida parâmetros de ferramentas, garantindo que Claude chame suas funções com argumentos corretamente tipados. Use uso rigoroso de ferramentas quando você precisar:

• Validar parâmetros de ferramentas
• Construir fluxos de trabalho de agentes
• Garantir chamadas de função seguras em tipo
• Lidar com ferramentas complexas com propriedades aninhadas

Por que o uso rigoroso de ferramentas é importante para agentes

Construir sistemas de agentes confiáveis requer conformidade de esquema garantida. Sem modo rigoroso, Claude pode retornar tipos incompatíveis ("2" em vez de 2) ou campos obrigatórios ausentes, quebrando suas funções e causando erros em tempo de execução.

Uso rigoroso de ferramentas garante parâmetros seguros em tipo:

• Funções recebem argumentos corretamente tipados todas as vezes
• Sem necessidade de validar e tentar novamente chamadas de ferramentas
• Agentes prontos para produção que funcionam consistentemente em escala

Por exemplo, suponha que um sistema de reserva precise de passengers: int. Sem modo rigoroso, Claude pode fornecer passengers: "two" ou passengers: "2". Com strict: true, a resposta sempre conterá passengers: 2.

Início 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 resposta: Blocos de uso de ferramentas com entradas validadas em response.content[x].input

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

Garantias:

• A entrada da ferramenta segue rigorosamente o input_schema
• O nome da ferramenta é sempre válido (de ferramentas fornecidas ou ferramentas do servidor)

Como funciona

Casos de uso comuns

Usando ambos os recursos juntos

Saídas JSON e uso rigoroso de ferramentas resolvem problemas diferentes e podem ser usados juntos:

• Saídas JSON controlam o formato de resposta do Claude (o que Claude diz)
• Uso rigoroso de ferramentas valida parâmetros de ferramentas (como Claude chama suas funções)

Quando combinados, Claude pode chamar ferramentas com parâmetros garantidamente válidos E retornar respostas JSON estruturadas. Isso é útil para fluxos de trabalho de agentes onde você precisa de chamadas de ferramentas confiáveis e saídas finais estruturadas.

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
        }
    }]
)

Considerações importantes

Compilação de gramática e cache

Saídas estruturadas usam amostragem restrita com artefatos de gramática compilados. Isso introduz algumas características de desempenho a serem observadas:

• Latência da primeira solicitação: A primeira vez que você usa um esquema específico, haverá latência adicional enquanto a gramática é compilada
• Cache automático: Gramáticas compiladas são armazenadas em cache por 24 horas desde o último uso, tornando solicitações subsequentes muito mais rápidas
• Invalidação de cache: O cache é invalidado se você alterar:
  • A estrutura do esquema JSON
  • O conjunto de ferramentas em sua solicitação (ao usar saídas estruturadas e uso de ferramentas)
  • Alterar apenas campos name ou description não invalida o cache

Modificação de prompt e custos de token

Ao usar saídas estruturadas, Claude recebe automaticamente um prompt de sistema adicional explicando o formato de saída esperado. Isso significa:

• Sua contagem de token de entrada será ligeiramente maior
• O prompt injetado custa tokens como qualquer outro prompt de sistema
• Alterar o parâmetro output_format invalidará qualquer cache de prompt para esse thread de conversa

Limitações de JSON Schema

Saídas estruturadas suportam JSON Schema padrão com algumas limitações. Tanto saídas JSON quanto uso rigoroso de ferramentas compartilham essas limitações.

Saídas inválidas

Embora saídas estruturadas garantam conformidade de esquema na maioria dos casos, existem cenários onde a saída pode não corresponder ao seu esquema:

Recusas (stop_reason: "refusal")

Claude mantém suas propriedades de segurança e utilidade mesmo ao usar saídas estruturadas. Se Claude recusar uma solicitação por motivos de segurança:

• A resposta terá stop_reason: "refusal"
• Você receberá um código de status 200
• Você será cobrado pelos tokens gerados
• A saída pode não corresponder ao seu esquema porque a mensagem de recusa tem precedência sobre restrições de esquema

Limite de token atingido (stop_reason: "max_tokens")

Se a resposta for cortada devido ao atingimento do limite max_tokens:

• A resposta terá stop_reason: "max_tokens"
• A saída pode estar incompleta e não corresponder ao seu esquema
• Tente novamente com um valor max_tokens mais alto para obter a saída estruturada completa

Erros de validação de esquema

Se seu esquema usar recursos não suportados ou for muito complexo, você receberá um erro 400:

"Too many recursive definitions in schema"

• Causa: O esquema tem definições recursivas excessivas ou cíclicas
• Solução: Simplifique a estrutura do esquema, reduza a profundidade de aninhamento

"Schema is too complex"

• Causa: O esquema excede limites de complexidade
• Solução: Divida em esquemas menores, simplifique a estrutura ou reduza o número de ferramentas marcadas como strict: true

Para problemas persistentes com esquemas válidos, entre em contato com o suporte com sua definição de esquema.

Compatibilidade de recursos

Funciona com:

• Processamento em lote: Processe saídas estruturadas em escala com desconto de 50%
• Contagem de tokens: Conte tokens sem compilação
• Streaming: Transmita saídas estruturadas como respostas normais
• Uso combinado: Use saídas JSON (output_format) e uso rigoroso de ferramentas (strict: true) juntos na mesma solicitação

Incompatível com:

• Citações: Citações exigem intercalação de blocos de citação com texto, o que entra em conflito com restrições de esquema JSON rigoroso. Retorna erro 400 se citações habilitadas com output_format.
• Preenchimento de mensagem: Incompatível com saídas JSON