Saídas estruturadas

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

Saídas JSON (output_config.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 e entradas de ferramentas

O parâmetro output_format foi movido para output_config.format. O parâmetro antigo output_format ainda funciona temporariamente, mas está descontinuado e será removido em uma versão futura da API. Atualize seu código para usar output_config: {format: {...}} em vez disso.

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

Saídas estruturadas estão geralmente disponíveis na Claude API e Amazon Bedrock para Claude Opus 4.6, Claude Sonnet 4.5, Claude Opus 4.5 e Claude Haiku 4.5. Saídas estruturadas permanecem em beta público no Microsoft Foundry.

Migrando da versão beta? O parâmetro output_format foi movido para output_config.format, e cabeçalhos beta não são mais necessários. O cabeçalho beta antigo (structured-outputs-2025-11-13) e o parâmetro output_format continuarão funcionando por um período de transição. Veja exemplos de código abaixo para a forma de API atualizada.

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

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

Sempre válido: Sem mais erros de JSON.parse()
Seguro de tipo: Tipos de campo garantidos e campos obrigatórios
Confiável: Nenhuma tentativa novamente necessária 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

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

Defina seu esquema JSON
Crie um esquema JSON que descreva a estrutura que você quer que Claude siga. O esquema usa o formato padrão JSON Schema com algumas limitações (veja limitações de JSON Schema).
Adicione o parâmetro output_config.format
Inclua o parâmetro output_config.format em sua solicitação de API com type: "json_schema" e sua definição de esquema.
Analise a resposta
A resposta do Claude será JSON válido correspondente ao seu esquema, retornado em response.content[0].text.

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.

Métodos auxiliares do SDK (como .parse() e integração Pydantic/Zod) ainda aceitam output_format como um parâmetro de conveniência. O SDK trata a tradução para output_config.format internamente. Os exemplos abaixo mostram a sintaxe auxiliar do SDK.

Usando Pydantic e Zod

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

Métodos específicos do SDK

Python: client.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 você quer modificar um esquema gerado por Pydantic. Diferentemente de client.messages.parse(), que transforma esquemas fornecidos automaticamente, isso lhe dá 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:

Remova restrições não suportadas (por exemplo, minimum, maximum, minLength, maxLength)
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
Adicione additionalProperties: false a todos os objetos
Filtre formatos de string para lista suportada apenas
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 de 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 de tipo:

Funções recebem argumentos corretamente tipados toda vez
Nenhuma 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

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 input segue estritamente o input_schema
O name da ferramenta é sempre válido (de ferramentas fornecidas ou ferramentas do servidor)

Como funciona

Defina seu esquema de ferramenta
Crie um esquema JSON para o input_schema de sua ferramenta. O esquema usa o formato padrão JSON Schema com algumas limitações (veja limitações de JSON Schema).
Adicione strict: true
Defina "strict": true como uma propriedade de nível superior em sua definição de ferramenta, ao lado de name, description e input_schema.
Manipule chamadas de ferramentas
Quando Claude usa a ferramenta, o campo input no bloco tool_use seguirá estritamente seu input_schema, e o name será sempre válido.

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.

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

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

Os SDKs Python e TypeScript podem transformar automaticamente esquemas com recursos não suportados removendo-os e adicionando restrições às descrições de campo. Veja métodos específicos do SDK para detalhes.

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_config.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_config.format.
Preenchimento de mensagem: Incompatível com saídas JSON

Escopo de gramática: Gramáticas se aplicam apenas à saída direta do Claude, não a chamadas de uso de ferramentas, resultados de ferramentas ou tags de pensamento (ao usar Extended Thinking). O estado da gramática é redefinido entre seções, permitindo que Claude pense livremente enquanto ainda produz saída estruturada na resposta final.

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" \
  -d '{
    "model": "claude-opus-4-6",
    "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
        }
      }
    }
  }'

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.messages.create(
    model="claude-opus-4-6",
    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": transform_schema(ContactInfo),
        }
    }
)

print(response.content[0].text)

# With .parse() - can pass Pydantic model directly
response = client.messages.parse(
    model="claude-opus-4-6",
    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)

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" \
  -d '{
    "model": "claude-opus-4-6",
    "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
      }
    }]
  }'

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Help me plan a trip to Paris for next month"}],
    # 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
        }
    }]
)

Por que usar saídas estruturadas

Saídas JSON

Início rápido

Como funciona

Trabalhando com saídas JSON em SDKs

Usando Pydantic e Zod

Métodos específicos do SDK

Exemplo de uso

Exemplo de uso

Como funciona a transformação do SDK

Casos de uso comuns

Extração de dados

Uso rigoroso de ferramentas

Por que o uso rigoroso de ferramentas é importante para agentes

Início rápido

Como funciona

Casos de uso comuns

Entradas de ferramentas validadas

Usando ambos os recursos juntos

Considerações importantes

Compilação de gramática e cache

Modificação de prompt e custos de token

Limitações de JSON Schema

Recursos suportados

Não suportado

Suporte a padrão (regex)

Saídas inválidas

Erros de validação de esquema

Compatibilidade de recursos

Classificação

Formatação de resposta de API

Fluxo de trabalho de agente com múltiplas ferramentas validadas