Saídas estruturadas

As "structured outputs" (saídas estruturadas) restringem as respostas do Claude para que sigam um schema específico, garantindo uma saída válida e analisável para processamento posterior. As saídas estruturadas oferecem dois recursos complementares:

• Saídas JSON (output_config.format): Obtenha a resposta do Claude em um formato JSON específico, por exemplo, para extrair dados de imagens ou texto, gerar relatórios estruturados ou formatar respostas de API. Esta página aborda as saídas JSON.
• Uso estrito de ferramentas (strict: true): Garanta a validação de schema nos nomes e entradas das ferramentas. Consulte Uso estrito de ferramentas.

Você pode usar esses recursos de forma independente ou juntos na mesma requisição.

Por que usar saídas estruturadas

Sem saídas estruturadas, o 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 devido a sintaxe JSON inválida
• Campos obrigatórios ausentes
• Tipos de dados inconsistentes
• Violações de schema que exigem tratamento de erros e novas tentativas

As saídas estruturadas garantem respostas em conformidade com o schema por meio de decodificação restrita:

• Sempre válidas: Sem mais erros de JSON.parse()
• Segurança de tipos: Tipos de campos e campos obrigatórios garantidos
• Confiáveis: Sem necessidade de novas tentativas por violações de schema

Como funciona

1. 1

   Defina seu schema

   Descreva a estrutura desejada como um schema JSON ou como um tipo na sua linguagem. O schema segue o JSON Schema, com algumas limitações.

2. 2

   Envie-o em output_config.format

   A requisição carrega o schema em output_config.format com type: "json_schema". Os helpers do SDK configuram isso para você.

3. 3

   Leia a resposta

   O Claude retorna um JSON válido que corresponde ao seu schema no bloco de conteúdo de texto da resposta. Os helpers do SDK o analisam para o seu tipo.

Uso

from pydantic import BaseModel
# ...


class ContactInfo(BaseModel):
    name: str
    email: str
    plan_interest: str
    demo_requested: bool


client = Anthropic()

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@example.com) is interested in our Enterprise plan "
                "and wants to schedule a demo for next Tuesday at 2pm."
            ),
        }
    ],
    output_format=ContactInfo,
)

print(response.parsed_output)

name='John Smith' email='john@example.com' plan_interest='Enterprise' demo_requested=True

Como funciona a transformação do SDK

A maioria dos helpers do SDK transforma schemas que usam recursos não suportados. As etapas da transformação:

1. Remover restrições não suportadas (por exemplo, minimum, maximum, minLength, maxLength)
2. Atualizar descrições adicionando cada restrição não suportada à descrição do campo (por exemplo, {minimum: 100})
3. Adicionar additionalProperties: false a todos os objetos
4. Filtrar formatos de string apenas para a lista suportada
5. Validar respostas em relação ao seu schema original e todas as suas restrições, se o helper validar respostas

O Claude recebe um schema simplificado, mas um helper que valida respostas ainda aplica todas as restrições no seu código.

Exemplo: Um campo com minimum: 100 se torna um inteiro simples no schema enviado, e o SDK adiciona {minimum: 100} à descrição do campo. Um helper que valida respostas ainda verifica a resposta em relação a minimum: 100.

Usando um schema JSON bruto

Para usar um schema JSON de um arquivo, de uma especificação OpenAPI ou de código que o constrói em tempo de execução, passe-o em output_config.format.

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": (
                "Extract the key information from this email: "
                "John Smith (john@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": {
                "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,
            },
        }
    },
)
text = next(block.text for block in response.content if block.type == "text")
contact = json.loads(text)
print(contact)

{'name': 'John Smith', 'email': 'john@example.com', 'plan_interest': 'Enterprise', 'demo_requested': True}

Casos de uso comuns

from pydantic import BaseModel


class Invoice(BaseModel):
    invoice_number: str
    date: str
    total_amount: float
    line_items: list[dict]
    customer_name: str


client = anthropic.Anthropic()
invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"

response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=4096,
    output_format=Invoice,
    messages=[
        {"role": "user", "content": f"Extract invoice data from: {invoice_text}"}
    ],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class Classification(BaseModel):
    category: str
    confidence: float
    tags: list[str]
    sentiment: str


feedback_text = "Great product, but the delivery was slow."
response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=Classification,
    messages=[{"role": "user", "content": f"Classify this feedback: {feedback_text}"}],
)

print(response.parsed_output)

from pydantic import BaseModel

client = Anthropic()


class APIResponse(BaseModel):
    status: str
    data: dict
    errors: list[dict] | None
    metadata: dict


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[{"role": "user", "content": "Process this request: ..."}],
)

print(response.parsed_output)

Uso estrito de ferramentas

Para impor a conformidade com JSON Schema nas entradas de ferramentas com amostragem restrita por gramática, consulte Uso estrito de ferramentas.

Usando ambos os recursos juntos

As saídas JSON e o uso estrito de ferramentas resolvem problemas diferentes e funcionam em conjunto:

• As saídas JSON controlam o formato de resposta do Claude (o que o Claude diz)
• O uso estrito de ferramentas valida os parâmetros das ferramentas (como o Claude chama suas funções)

Quando combinados, o Claude pode chamar ferramentas com parâmetros garantidamente válidos E retornar respostas JSON estruturadas. Isso é útil para fluxos de trabalho agênticos em que você precisa tanto de chamadas de ferramentas confiáveis quanto de saídas finais estruturadas.

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[
        {
            "role": "user",
            "content": "Help me plan a trip to Paris departing May 15, 2026",
        }
    ],
    # Saídas JSON: formato de resposta estruturado
    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,
            },
        }
    },
    # Uso de ferramentas estrito: parâmetros de ferramenta garantidos
    tools=[
        {
            "name": "search_flights",
            "strict": True,
            "input_schema": {
                "type": "object",
                "properties": {
                    "destination": {"type": "string"},
                    "date": {"type": "string", "format": "date"},
                },
                "required": ["destination", "date"],
                "additionalProperties": False,
            },
        }
    ],
)

print(response)

Considerações importantes

Compilação e cache de gramática

As saídas estruturadas usam amostragem restrita com artefatos de gramática compilados. Isso introduz algumas características de desempenho que você deve conhecer:

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

Modificação do prompt e custos de tokens

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

• Sua contagem de tokens de entrada é ligeiramente maior
• O prompt injetado custa tokens como qualquer outro prompt do sistema
• Alterar o parâmetro output_config.format invalidará qualquer cache de prompt para aquela thread de conversa

Limitações do JSON Schema

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

Ordenação de propriedades

Ao usar saídas estruturadas, as propriedades nos objetos mantêm a ordenação definida no seu schema, com uma ressalva importante: as propriedades obrigatórias aparecem primeiro, seguidas pelas propriedades opcionais.

Por exemplo, dado este schema:

{
  "type": "object",
  "properties": {
    "notes": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "age": { "type": "integer" }
  },
  "required": ["name", "email"],
  "additionalProperties": false
}

A saída ordenará as propriedades como:

1. name (obrigatória, na ordem do schema)
2. email (obrigatória, na ordem do schema)
3. notes (opcional, na ordem do schema)
4. age (opcional, na ordem do schema)

Isso significa que a saída pode ter esta aparência:

{
  "name": "John Smith",
  "email": "john@example.com",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Se a ordem das propriedades na saída for importante para sua aplicação, marque todas as propriedades como obrigatórias ou leve em conta essa reordenação na sua lógica de análise.

Saídas inválidas

Embora as saídas estruturadas garantam a conformidade com o schema na maioria dos casos, há cenários em que a saída pode não corresponder ao seu schema:

Recusas (stop_reason: "refusal")

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

• A resposta tem 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 schema porque a mensagem de recusa tem precedência sobre as restrições do schema

Uma propriedade que solicita o pensamento do modelo ou um raciocínio passo a passo pode levar a uma recusa reasoning_extraction. Em vez disso, peça uma explicação curta. Consulte Mantenha o raciocínio nos blocos de pensamento.

Limite de tokens atingido (stop_reason: "max_tokens")

Se a resposta for cortada por atingir o limite de max_tokens:

• A resposta tem stop_reason: "max_tokens"
• A saída pode estar incompleta e não corresponder ao seu schema
• Tente novamente com um valor de max_tokens maior para obter a saída estruturada completa

Capitalização de valores enum

As saídas estruturadas não garantem a capitalização de valores enum e const de string: o Claude pode retornar um valor que difere do seu schema apenas na capitalização, normalmente na primeira letra de uma palavra após um espaço. Por exemplo, dado este schema:

{
  "type": "string",
  "enum": ["Conversation Topic 1", "Conversation Topic 2", "Conversation topic 3"]
}

A saída pode conter "Conversation Topic 3" ("T" maiúsculo) mesmo que esse valor exato não esteja no enum. A resposta é concluída normalmente, sem erro e sem stop_reason especial. Isso se aplica tanto às saídas JSON quanto ao uso estrito de ferramentas. Compare valores enum sem diferenciar maiúsculas de minúsculas e evite valores enum que difiram apenas na capitalização.

Limites de complexidade de schema

As saídas estruturadas funcionam compilando seus schemas JSON em uma gramática que restringe a saída do Claude. Schemas mais complexos produzem gramáticas maiores que levam mais tempo para compilar. Para proteger contra tempos de compilação excessivos, a API impõe vários limites de complexidade.

Limites explícitos

Os seguintes limites se aplicam a todas as requisições com output_config.format ou strict: true:

Limites internos adicionais

Além dos limites explícitos na tabela anterior, existem limites internos adicionais sobre o tamanho da gramática compilada. Esses limites existem porque a complexidade do schema não se reduz a uma única dimensão: recursos como parâmetros opcionais, tipos união, objetos aninhados e número de ferramentas interagem entre si de maneiras que podem tornar a gramática compilada desproporcionalmente grande.

Quando esses limites são excedidos, você receberá um erro 400 com a mensagem "Schema is too complex for compilation." Esses erros significam que a complexidade combinada dos seus schemas excede o que pode ser compilado de forma eficiente, mesmo que cada limite individual na tabela anterior seja satisfeito. Como medida final de contenção, a API também impõe um tempo limite de compilação de 180 segundos. Schemas que passam em todas as verificações explícitas, mas produzem gramáticas compiladas muito grandes, podem atingir esse tempo limite.

Dicas para reduzir a complexidade do schema

Se você estiver atingindo os limites de complexidade, experimente estas estratégias em ordem:

1. Marque apenas as ferramentas críticas como estritas. Se você tiver muitas ferramentas, reserve isso para ferramentas em que violações de schema causam problemas reais e confie na aderência natural do Claude para ferramentas mais simples.

2. Reduza os parâmetros opcionais. Torne os parâmetros required sempre que possível. Cada parâmetro opcional aproximadamente dobra uma parte do espaço de estados da gramática. Se um parâmetro sempre tem um padrão razoável, considere torná-lo obrigatório e fazer com que o Claude forneça esse padrão explicitamente.

3. Simplifique estruturas aninhadas. Objetos profundamente aninhados com campos opcionais aumentam a complexidade. Achate as estruturas sempre que possível.

4. Divida em várias requisições. Se você tiver muitas ferramentas estritas, considere dividi-las em requisições separadas ou subagentes.

Para problemas persistentes com schemas válidos, entre em contato com o suporte com a definição do seu schema.

Migrando do beta

O parâmetro output_format foi movido para output_config.format, e os cabeçalhos beta não são mais necessários. O parâmetro output_format está descontinuado e será removido no futuro. Para usá-lo mesmo assim, adicione o cabeçalho beta structured-outputs-2025-11-13. Sem ele, a API retorna um erro 400.

O SDK Python (v1.0 e posteriores) não aceita output_format={...} em client.beta.messages.create() ou count_tokens() e gera um TypeError. Use output_config em vez disso. Consulte Usando um schema JSON bruto para o formato atualizado da API.

Retenção de dados

Os prompts e as respostas são processados com ZDR ao usar saídas estruturadas. No entanto, o schema JSON em si é temporariamente armazenado em cache por até 24 horas desde o último uso para fins de otimização. Nenhum dado de prompt ou resposta é retido além da resposta da API.

As saídas estruturadas são elegíveis para HIPAA, mas PHI não deve ser incluída nas definições de schema JSON. A API compila schemas JSON em gramáticas que são armazenadas em cache separadamente do conteúdo das mensagens, e esses schemas em cache não recebem as mesmas proteções de PHI que os prompts e as respostas. Não inclua PHI em nomes de propriedades do schema, valores enum, valores const ou expressões regulares pattern. PHI deve aparecer apenas no conteúdo das mensagens (prompts e respostas), onde é protegida pelas salvaguardas da HIPAA.

Para elegibilidade de ZDR e HIPAA em todos os recursos, consulte API e retenção de dados.

Compatibilidade de recursos

Funciona com:

• Processamento em lote: Processe saídas estruturadas em escala com 50% de desconto
• Contagem de tokens: Conte tokens sem compilação
• Streaming: Faça streaming de saídas estruturadas como respostas normais
• Uso combinado: Use saídas JSON (output_config.format) e uso estrito de ferramentas (strict: true) juntos na mesma requisição

Incompatível com:

• Citações: As citações exigem intercalar blocos de citação com texto, o que conflita com as restrições estritas de schema JSON. Retorna erro 400 se as citações estiverem habilitadas com output_config.format.
• Preenchimento prévio de mensagens: Incompatível com saídas JSON

Próximos passos

Compatibility