Pular para o conteúdo principal

Saída Estruturada

Intermediário
What you'll learn
  • Explicar por que a saída imposta por schema supera pedir JSON no prompt e torcer
  • Fornecer um JSON Schema e fazer o parsing da resposta para um objeto tipado (Pydantic / Zod)
  • Diferenciar saída estruturada de uso de ferramentas pela intenção, não pelo mecanismo
  • Aplicar as quatro dicas para schemas enxutos e confiáveis
  • Escolher a ferramenta certa com uma regra prática de uma pergunta só

Quando a saída do Claude alimenta outro software, você precisa de estrutura confiável — JSON válido correspondendo a um formato conhecido, todas as vezes. Não confie em "responda em JSON" e torça; use o suporte a saída estruturada da plataforma.

Esta lição leva você do por que o prompt-e-reza falha ao como impor um schema e fazer o parsing dele para um objeto tipado — e como diferenciar saída estruturada de uso de ferramentas quando parecem idênticos. Percorra-a de cima a baixo e depois teste-se com o quiz perto do final.

O jeito confiável​

Forneça um JSON Schema para a saída e deixe a API/SDK impô-lo, depois faça o parsing para um objeto tipado (por exemplo, Pydantic em Python, Zod em TypeScript). Os auxiliares de parsing do SDK entregam um resultado tipado em vez de uma string que você mesmo teria que analisar com JSON.parse e validar.

Guided walkthrough1 of 3
  1. Modele a saída de que você precisa como um JSON Schema — em Python via um Pydantic BaseModel, em TypeScript via um schema Zod.
# Conceptual shape — see the official docs for the current API surface.
from pydantic import BaseModel

class Ticket(BaseModel):
    title: str
    priority: str   # "low" | "medium" | "high"
    tags: list[str]

# Request the model to return data conforming to Ticket's JSON schema,
# then parse the response into a Ticket instance.

Quer uma requisição concreta para adaptar? Aqui está o formato do que você entrega ao modelo — substitua o modelo pelo seu próprio schema.

Peça saída em conformidade com o schema

Return the data conforming to this JSON Schema:

{
"title": "string",
"priority": "low | medium | high",
"tags": ["string"]
}

Do not include any prose outside the JSON.

Por que não simplesmente pedir JSON no prompt?​

Você pode pedir JSON no prompt, e para casos simples funciona — mas pode desviar: prosa solta, uma vírgula sobrando, um campo faltando. A saída imposta por schema elimina essa classe de bug, o que importa no exato momento em que um sistema downstream depende dela.

Watch out
  • JSON pedido no prompt funciona em demos e quebra em produção: a falha só aparece quando um sistema downstream faz o parsing dele.
  • Três desvios clássicos para ficar de olho: prosa solta ao redor do JSON, uma vírgula sobrando e um campo obrigatório faltando.

Saída estruturada vs. uso de ferramentas​

Ambos os recursos entregam ao modelo um JSON Schema, então parecem iguais — e as pessoas escolhem o errado. A diferença está na intenção, não no mecanismo:

Saída estruturadaUso de ferramentas
O que você querA resposta final, em um formato fixoQue o modelo invoque uma capacidade (chame uma função, busque dados, execute uma ação)
Quem consomeSeu código, diretamenteSeu código executa a ferramenta e depois devolve o resultado ao modelo
Formato do turnoUma resposta, prontoUm laço: o modelo pede, você executa, o modelo continua
Uso típicoExtração, classificação, parsingAgentes, consultas ao vivo, efeitos colaterais

Uma regra prática rápida:

Se o JSON é o entregável, use saída estruturada. Se o JSON é o modelo pedindo ao seu código para fazer algo, isso é uso de ferramentas. Agentes frequentemente usam ambos: ferramentas para agir, saída estruturada para retornar um resultado final limpo.

Dicas​

Pro tip
  • Mantenha os schemas enxutos — use enums para escolhas fixas; marque os campos obrigatórios.
  • Descreva os campos — descrições de campos guiam o modelo como mini-prompts.
  • Valide mesmo assim na fronteira — parsing defensivo é um seguro barato.
  • Para tarefas de extração, saída estruturada + um schema claro supera o formato livre todas as vezes.
Key takeaways
  • Entregue à API/SDK um JSON Schema e faça o parsing para um objeto tipado — não fique no prompt-e-reza.
  • Pedir JSON no prompt pode desviar (prosa solta, vírgula sobrando, campo faltando); impor o schema elimina essa classe de bug.
  • Saída estruturada vs. uso de ferramentas diferem pela intenção: o JSON É a resposta vs. o JSON solicita uma ação.
  • Schemas enxutos, campos descritos e validação na fronteira tornam a extração e a classificação confiáveis.

Fixe os termos​

Pressione Enter ou Espaço para virar o cartão. Use as setas esquerda e direita para navegar entre os cartões.Termo exibido.
1 / 5

Teste-se

0/4
  1. Qual é o jeito confiável de obter JSON estruturado do Claude?
  2. Por que pedir JSON no prompt é arriscado quando um sistema downstream depende dele?
  3. O que realmente distingue saída estruturada de uso de ferramentas?
  4. Qual é um conselho sólido para projetar schemas?

Próximo​