Saídas estruturadas

As “structured outputs” (saídas estruturadas) restringem as respostas do Claude para seguir um esquema 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 esquema nos nomes e entradas das ferramentas. Consulte Uso estrito de ferramentas.

Você pode usar esses recursos de forma independente ou juntos na mesma solicitaçã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 esquema que exigem tratamento de erros e novas tentativas

As saídas estruturadas garantem respostas em conformidade com o esquema por meio de “constrained decoding” (decodificação restrita):

• Sempre válidas: Sem erros de análise de JSON
• Com segurança de tipos: Tipos de campo e campos obrigatórios garantidos
• Confiáveis: Nenhuma nova tentativa necessária devido a violações de esquema

Como funciona

1. 1

   Defina seu esquema

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

2. 2

   Envie-o em output_config.format

   A solicitação carrega o esquema em output_config.format com type: "json_schema". Os helpers do SDK definem isso para você.

3. 3

   Leia a resposta

   O Claude retorna JSON válido que corresponde ao seu esquema no bloco de conteúdo de texto da resposta. Os helpers do SDK o analisam e convertem no 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 esquemas 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 esquema original e todas as suas restrições, se o helper validar respostas

O Claude recebe um esquema 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 esquema 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 JSON schema bruto

Para usar um JSON schema 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 LineItem(BaseModel):
    description: str
    quantity: float
    unit_price: float


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


client = anthropic.Anthropic()
invoice_text = """
Invoice #12345
Date: 2024-01-15
Customer: Acme Corp
2 widgets at $150.00 each
1 setup fee at $200.00
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 Payload(BaseModel):
    message: str


class APIError(BaseModel):
    code: str
    detail: str


class Metadata(BaseModel):
    request_id: str


class APIResponse(BaseModel):
    status: str
    data: Payload
    errors: list[APIError] | None = None
    metadata: Metadata


response = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    output_format=APIResponse,
    messages=[
        {
            "role": "user",
            "content": "Write an API response: request req_2abc3def has an invalid email.",
        }
    ],
)

print(response.parsed_output)

Uso estrito de ferramentas

Para aplicar 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 juntos:

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

client = anthropic.Anthropic()

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áticas

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

• “Latency” (latência) da primeira solicitação: Na primeira vez que você usa um esquema específico, há uma latência adicional enquanto a gramática é compilada.
• Cache automático: As gramáticas compiladas ficam em cache por 24 horas a partir do último uso, tornando as solicitações subsequentes muito mais rápidas.
• Invalidação do cache: O cache é invalidado se você alterar a estrutura do JSON schema ou, ao usar saídas estruturadas e uso de ferramentas em conjunto, o conjunto de ferramentas na sua solicitação. 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 é um pouco maior.
• O prompt injetado custa tokens como qualquer outro prompt do sistema.
• Alterar o parâmetro output_config.format invalida 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.

Objetos com chaves arbitrárias

Liste cada chave de um objeto, seja em properties ou como um campo da classe ou do esquema que você passa para o SDK. Como additionalProperties deve ser false, o Claude só pode retornar as chaves que você listar.

A API aceita um objeto com properties vazio ou ausente, mas o Claude só pode retornar {} para ele. Um tipo map, dictionary ou record não lista nenhuma chave, então os SDKs Python e TypeScript o enviam como um objeto com properties vazio. Os SDKs Java e Ruby geram um erro em vez disso.

Se você não souber as chaves com antecedência, use um array em vez disso. Dê a cada item uma key e um value, como neste esquema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "key": { "type": "string" },
      "value": { "type": "string" }
    },
    "required": ["key", "value"],
    "additionalProperties": false
  }
}

Ordenação de propriedades

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

Por exemplo, dado este esquema:

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

A saída ordena as propriedades assim:

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

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 essa reordenação em conta na sua lógica de análise.

Saídas inválidas

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

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 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, pois a mensagem de recusa tem precedência sobre as restrições do esquema.

Uma propriedade que solicita o pensamento do modelo ou o 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 em blocos de pensamento.

Limite de tokens atingido (stop_reason: "max_tokens")

Se a resposta for cortada por ter atingido o limite de 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 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 dos valores de string enum e const: o Claude pode retornar um valor que difere do seu esquema apenas na capitalização, normalmente na primeira letra de uma palavra após um espaço. Por exemplo, dado este esquema:

{
  "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 diferem apenas na capitalização.

Limites de complexidade do esquema

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

Limites explícitos

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

Limites internos adicionais

Além dos limites explícitos da tabela anterior, há limites internos adicionais no tamanho da gramática compilada. Esses limites existem porque a complexidade do esquema não se reduz a uma única dimensão: recursos como parâmetros opcionais, tipos union, 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 esquemas excede o que pode ser compilado de forma eficiente, mesmo que cada limite individual da tabela anterior seja satisfeito. Como medida final, a API também aplica um tempo limite de compilação de 180 segundos. Esquemas 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 esquema

Se você estiver atingindo limites de complexidade, tente estas estratégias na ordem:

1. Marque apenas ferramentas críticas como estritas. Se você tiver muitas ferramentas, reserve o uso estrito de ferramentas para aquelas em que violações de esquema 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 praticamente 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 solicitações. Se você tiver muitas ferramentas estritas, considere dividi-las entre solicitações separadas ou subagentes.

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

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. Para usá-lo mesmo assim, adicione o cabeçalho beta structured-outputs-2025-11-13. Sem ele, a API retorna um erro 400.

No SDK Python (v1.0 e posteriores), um dicionário de esquema passado como output_format={...} gera um TypeError. Use output_config em vez disso. Um modelo Pydantic passado como output_format=Model para parse() ou stream() funciona sem alterações e sem cabeçalho beta, porque o SDK o envia como output_config. Consulte Usando um JSON schema bruto para o formato atualizado da API.

Compatibilidade de recursos

Funciona com:

• Processamento em lote: Processe saídas estruturadas em escala com 50 por cento 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 solicitação

Incompatível com:

• Citações: As citações exigem intercalar blocos de citação com texto, o que entra em conflito com as restrições estritas do JSON schema. A API retorna um erro 400 se as citações estiverem habilitadas com output_config.format. Para extrair dados estruturados com uma citação para cada valor, consulte Obter dados estruturados com citações.
• Pré-preenchimento de mensagens: O pré-preenchimento é incompatível com saídas JSON.

Disponibilidade

Prompts e respostas são processados com ZDR ao usar saídas estruturadas. No entanto, o próprio JSON schema é 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 JSON schema. A API compila JSON schemas em gramáticas que são armazenadas em cache separadamente do conteúdo das mensagens, e esses esquemas em cache não recebem as mesmas proteções de PHI que prompts e respostas. Não inclua PHI em nomes de propriedades do esquema, 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.

Próximos passos