Saídas estruturadas

As saídas estruturadas restringem as respostas do Claude a seguir um esquema específico, garantindo saídas válidas e analisáveis para processamento posterior. Use saídas JSON (output_format) para respostas de dados estruturados, ou uso rigoroso de ferramentas (strict: true) para validação de esquema garantida em nomes e entradas de ferramentas.

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

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

• Sempre válidas: Sem mais erros de JSON.parse()
• Seguras em tipo: Tipos de campo garantidos e campos obrigatórios
• Confiáveis: Sem necessidade de novas tentativas para violações de esquema
• Dois modos: JSON para tarefas como extração de dados, e ferramentas rigorosas para situações como ferramentas complexas e fluxos de trabalho com agentes

Início rápido

Quando usar saídas JSON vs uso rigoroso de ferramentas

Escolha o modo certo para seu caso de uso:

Por que o uso rigoroso de ferramentas é importante para agentes

Construir sistemas com agentes confiáveis requer conformidade de esquema garantida. Parâmetros de ferramentas inválidos quebram suas funções e fluxos de trabalho. Claude pode retornar tipos incompatíveis ("2" em vez de 2) ou campos ausentes, causando erros em tempo de execução.

O uso rigoroso de ferramentas garante parâmetros seguros em tipo:

• As funções recebem argumentos corretamente tipados todas as vezes
• Sem necessidade de validar e repetir 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, você tem garantia de passengers: 2.

Como funcionam as saídas estruturadas

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 de definição de esquema familiares 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 você quer 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 aplica todas as restrições através da 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

Considerações importantes

Compilação de gramática e cache

As saídas estruturadas usam amostragem restrita com artefatos de gramática compilada. 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 tokens 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

As 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 as 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 razões 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 (a recusa tem precedência)

Limite de token atingido (stop_reason: "max_tokens")

Se a resposta for cortada devido ao atingimento do 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 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:

"Muitas definições recursivas no esquema"

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

"Esquema é muito complexo"

• 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 rigorosas de esquema JSON. Retorna erro 400 se citações habilitadas com output_format.
• Preenchimento de mensagem: Incompatível com saídas JSON