Saídas estruturadas

As 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. As saídas estruturadas fornecem dois recursos complementares:

• 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

Você pode usar esses recursos independentemente ou juntos na mesma solicitação.

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

As saídas estruturadas garantem respostas em conformidade com o 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

As 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

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 de definição de esquema familiares em sua linguagem:

• Python: Modelos Pydantic com client.messages.parse()
• TypeScript: Esquemas Zod com zodOutputFormat() ou literais JSON Schema digitados com jsonSchemaOutputFormat()
• Java: Classes Java simples com derivação automática de esquema via outputConfig(Class<T>)
• Ruby: Classes Anthropic::BaseModel com output_config: {format: Model}
• PHP: Classes implementando StructuredOutputModel com outputConfig: ['format' => MyClass::class]
• CLI, C#, : Esquemas JSON brutos passados via

Métodos específicos do SDK

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

Como funciona a transformação do SDK

Os SDKs Python, TypeScript, Ruby e PHP 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 para lista suportada apenas
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 impõe 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 o SDK atualiza a descrição para "Deve ser pelo menos 100" e valida a resposta contra a restrição original.

Casos de uso comuns

Uso rigoroso de ferramentas

Para impor conformidade com JSON Schema em entradas de ferramentas com amostragem restrita por gramática, consulte Uso rigoroso de ferramentas.

Usando ambos os recursos juntos

Saídas JSON e uso rigoroso de ferramentas resolvem problemas diferentes e funcionam 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 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, há 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 as 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 juntos)
  • 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 é 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 do 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.

Ordenação de propriedades

Ao usar saídas estruturadas, as propriedades em objetos mantêm sua ordenação definida do 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, em ordem de esquema)
2. email (obrigatório, em ordem de esquema)
3. notes (opcional, em ordem de esquema)
4. age (opcional, em ordem de esquema)

Isso significa que a saída pode parecer:

{
  "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, marque todas as propriedades como obrigatórias ou leve em conta essa reordenação em sua lógica de análise.

Saídas inválidas

Embora saídas estruturadas garantam conformidade com 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 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 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 tem stop_reason: "max_tokens"
• A saída pode estar incompleta e não corresponder ao seu esquema
• Tente novamente com um valor max_tokens maior para obter a saída estruturada completa

Limites de complexidade de esquema

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 solicitações com output_config.format ou strict: true:

Limites internos adicionais

Além dos limites explícitos acima, existem 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 de união, objetos aninhados e número de ferramentas interagem uns com os outros 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 um último recurso, 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 este tempo limite.

Dicas para reduzir a complexidade do esquema

Se você está atingindo limites de complexidade, tente essas estratégias em ordem:

1. Marque apenas ferramentas críticas como rigorosas. Se você tiver muitas ferramentas, reserve 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 quando possível. Cada parâmetro opcional aproximadamente dobra uma porção do espaço de estado da gramática. Se um parâmetro sempre tem um padrão razoável, considere torná-lo obrigatório e ter Claude fornecer esse padrão explicitamente.

3. Simplifique estruturas aninhadas. Objetos profundamente aninhados com campos opcionais compõem a complexidade. Achate estruturas quando possível.

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

Para problemas persistentes com esquemas válidos, entre em contato com o suporte com sua definição de esquema.

Retenção de dados

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

Saídas estruturadas são elegíveis para HIPAA, mas PHI não deve ser incluído em definições de esquema JSON. A API compila esquemas JSON em gramáticas que são armazenadas em cache separadamente do conteúdo da mensagem, e essas gramáticas armazenadas em cache não recebem as mesmas proteções de PHI que prompts e respostas. Não inclua PHI em nomes de propriedades de esquema, valores enum, valores const ou expressões regulares pattern. PHI deve aparecer apenas no conteúdo da mensagem (prompts e respostas), onde é protegido sob salvaguardas 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 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 rigorosas de esquema JSON. Retorna erro 400 se citações habilitadas com output_config.format.
• Preenchimento de mensagem: Incompatível com saídas JSON