Saídas estruturadas

As saídas estruturadas restringem as respostas do Claude para seguir um esquema específico, garantindo saídas válidas e analisáveis 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 estrito de ferramentas (strict: true): Garanta validação de esquema em nomes de ferramentas e entradas

Esses recursos podem ser usados 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 por 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 decodificação restrita:

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

Saídas JSON

As saídas JSON controlam o formato de resposta do Claude, garantindo que ele retorne JSON válido correspondente ao seu esquema. Use saídas JSON quando 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" \
  -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
        }
      }
    }
  }'

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 nos SDKs

Os SDKs 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 definições de esquema nativas

Em vez de escrever esquemas JSON brutos, você pode usar ferramentas familiares de definição de esquema em sua linguagem:

• Python: modelos Pydantic com client.messages.parse()
• TypeScript: esquemas Zod com zodOutputFormat()
• Java: classes Java simples com derivação automática de esquema via outputFormat(Class<T>)
• Ruby: classes Anthropic::BaseModel com output_config: {format: Model}
• C#, Go, PHP: esquemas JSON brutos passados via output_config

from pydantic import BaseModel
from anthropic import Anthropic


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


client = Anthropic()

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)

Métodos específicos de cada SDK

Cada SDK fornece auxiliares que facilitam o trabalho com saídas estruturadas. Consulte as páginas individuais de cada SDK para detalhes completos.

Como funciona a transformação do SDK

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

1. Remover restrições não suportadas (por exemplo, minimum, maximum, minLength, maxLength)
2. Atualizar 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. Adicionar additionalProperties: false a todos os objetos
4. Filtrar formatos de string apenas para a lista suportada
5. Validar 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 por meio de validação.

Exemplo: Um campo Pydantic com minimum: 100 torna-se 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 estrito de ferramentas

O uso estrito de ferramentas valida os parâmetros das ferramentas, garantindo que Claude chame suas funções com argumentos corretamente tipados. Use o uso estrito de ferramentas quando precisar:

• Validar parâmetros de ferramentas
• Construir fluxos de trabalho agênticos
• Garantir chamadas de função com segurança de tipos
• Lidar com ferramentas complexas com propriedades aninhadas

Por que o uso estrito de ferramentas é importante para agentes

Construir sistemas agênticos confiáveis requer conformidade garantida com o esquema. Sem o modo estrito, 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.

O uso estrito de ferramentas garante parâmetros com segurança de tipos:

• As funções recebem argumentos corretamente tipados sempre
• Não há 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 reservas precise de passengers: int. Sem o modo estrito, 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" \
  -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
      }
    }]
  }'

Formato de resposta: Blocos de uso de ferramenta com entradas validadas em response.content[x].input

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

Garantias:

• O input da ferramenta segue estritamente o input_schema
• O name da ferramenta é sempre válido (das ferramentas fornecidas ou ferramentas do servidor)

Como funciona

Casos de uso comuns

Usando ambas as funcionalidades juntas

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

• Saídas JSON controlam o formato de resposta do Claude (o que o Claude diz)
• 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 onde você precisa tanto de chamadas de ferramentas confiáveis quanto de saídas finais estruturadas.

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

Considerações importantes

Compilação de gramática e cache

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

• Latência na primeira requisição: Na primeira vez que você usa um esquema específico, haverá 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 de cache: O cache é invalidado se você alterar:
  • A estrutura do esquema JSON
  • O conjunto de ferramentas em 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 de prompt e custos de tokens

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

• 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_config.format invalidará qualquer cache de prompt para aquele thread de conversa

Limitações do JSON Schema

As saídas estruturadas suportam 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 em objetos mantêm sua 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 ordenará as propriedades como:

1. name (obrigatório, na ordem do esquema)
2. email (obrigatório, 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 parecer com:

{
  "name": "John Smith",
  "email": "[email protected]",
  "notes": "Interested in enterprise plan",
  "age": 35
}

Se a ordem das propriedades na saída for importante para sua aplicação, certifique-se de que todas as propriedades estejam marcadas como obrigatórias, ou leve em conta essa reordenação em 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 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 porque a mensagem de recusa tem precedência sobre as restrições do esquema

Limite de tokens atingido (stop_reason: "max_tokens")

Se a resposta for interrompida por atingir 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 maior de max_tokens para obter a saída estruturada completa

Limites de complexidade do esquema

As saídas estruturadas funcionam compilando seus esquemas JSON 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 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 acima, 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: funcionalidades como parâmetros opcionais, tipos de 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 de seus esquemas excede o que pode ser compilado eficientemente, mesmo que cada limite individual acima seja satisfeito. Como última medida de segurança, a API também impõe 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 em ordem:

1. Marque apenas ferramentas críticas como estritamente. Se você tiver muitas ferramentas, reserve-o para ferramentas onde violações de esquema causam problemas reais, e confie na aderência natural do Claude para ferramentas mais simples.

2. Reduza parâmetros opcionais. Torne os parâmetros required onde 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 onde possível.

4. Divida em múltiplas requisições. Se você tiver muitas ferramentas estritamente, considere dividi-las em requisições separadas ou sub-agentes.

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

Retenção de dados

Prompts e respostas são processados com ZDR ao usar saídas estruturadas. No entanto, o próprio esquema JSON é 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.

Para elegibilidade de ZDR em todas as funcionalidades, consulte API e Retenção de Dados.

Compatibilidade de funcionalidades

Funciona com:

• Processamento em lote: Processe saídas estruturadas em escala com 50% de desconto
• 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 estrito de ferramentas (strict: true) juntos na mesma requisição

Incompatível com:

• Citações: As citações requerem intercalação de blocos de citação com texto, o que conflita com restrições estritas de esquema JSON. Retorna erro 400 se as citações estiverem habilitadas com output_config.format.
• Preenchimento de mensagem: Incompatível com saídas JSON