Domínio 4 — Prompt Engineering & Structured Output · Lição 4 de 7

Structured outputs: output_config, tool_use e strict

Objetivos de aprendizagem

• Usar output_config={"format": ...} e client.messages.parse() como caminho atual para JSON garantido (task statement 4.3).
• Usar tool use com JSON schema como padrão clássico de extração estruturada.
• Explicar o que strict: true garante (sintaxe/schema) e o que NÃO garante (semântica).
• Diferenciar tool_choice: auto, any e forçado — e a restrição em modelos mais novos.
• Projetar schemas com campos opcionais/nullable e enums com "other" + detail e "unclear" para evitar fabricação.
• Saber por que o prefill de assistente é um padrão obsoleto que retorna erro 400 nos modelos atuais.

O caminho atual: output_config.format

Nos modelos atuais, a forma direta de obter JSON sintaticamente válido e aderente a um schema é o parâmetro output_config com um format do tipo json_schema. A API garante que o bloco de texto da resposta contém JSON válido conforme o schema — sem cercas de markdown, sem prosa em volta, sem vírgula sobrando.

import json
import anthropic

client = anthropic.Anthropic()

INVOICE_SCHEMA = {
    "type": "json_schema",
    "schema": {
        "type": "object",
        "properties": {
            "supplier": {"type": "string"},
            "total": {"type": ["number", "null"]},
            "due_date": {"type": ["string", "null"]},
            "category": {
                "type": "string",
                "enum": ["servicos", "produtos", "impostos", "unclear", "other"],
            },
            "category_detail": {"type": ["string", "null"]},
        },
        "required": ["supplier", "total", "due_date", "category", "category_detail"],
        "additionalProperties": False,
    },
}

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    output_config={"format": INVOICE_SCHEMA},
    messages=[{
        "role": "user",
        "content": "Extraia: 'NF 5501 - Consultoria Delta - R$ 8.900,00 - venc. 15/12/2026'",
    }],
)

text = next(b.text for b in response.content if b.type == "text")
data = json.loads(text)  # JSON garantidamente válido e aderente ao schema
print(data["supplier"], data["total"])

No SDK Python, o helper client.messages.parse() faz o mesmo com um modelo Pydantic e já devolve a instância validada em response.parsed_output:

from typing import Optional, List
from pydantic import BaseModel
import anthropic

class Contact(BaseModel):
    name: str
    email: Optional[str]
    interests: List[str]
    demo_requested: bool

client = anthropic.Anthropic()

response = client.messages.parse(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": "Extraia: Jane Doe (jane@co.com) quer plano Enterprise e uma demo.",
    }],
    output_format=Contact,  # kwarg do helper parse(): recebe o modelo Pydantic
)

contact = response.parsed_output  # instância Contact validada
print(contact.name, contact.demo_requested)

O padrão clássico: tool use com JSON schema

Antes dos structured outputs nativos, o padrão consolidado de extração era definir uma ferramenta cujo input_schema é o schema da extração e ler os dados do bloco tool_use da resposta. A "ferramenta" não executa nada — é só um recipiente tipado. Esse padrão continua válido, aparece bastante no exame, e é o único caminho quando você também precisa de ferramentas reais na mesma chamada.

import anthropic

client = anthropic.Anthropic()

extraction_tool = {
    "name": "record_invoice",
    "description": "Registra os dados extraídos de uma nota fiscal.",
    "strict": True,  # garante aderência exata ao input_schema
    "input_schema": {
        "type": "object",
        "properties": {
            "supplier": {"type": "string"},
            "total": {"type": ["number", "null"]},
            "line_items": {
                "type": "array",
                "items": {
                    "type": "object",
                    "properties": {
                        "description": {"type": "string"},
                        "amount": {"type": "number"},
                    },
                    "required": ["description", "amount"],
                    "additionalProperties": False,
                },
            },
        },
        "required": ["supplier", "total", "line_items"],
        "additionalProperties": False,
    },
}

response = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    tools=[extraction_tool],
    tool_choice={"type": "any"},  # obriga a chamar uma ferramenta (ver restrição abaixo)
    messages=[{"role": "user", "content": "Extraia: 'ACME - item A R$ 100 - item B R$ 50 - total R$ 150'"}],
)

for block in response.content:
    if block.type == "tool_use":
        print(block.input)  # dict já estruturado conforme o schema

tool_choice: auto, any e forçado

strict: true — garantia sintática, não semântica

strict: true na definição da ferramenta (e o output_config.format nativo) garantem que a saída adere exatamente ao schema: tipos corretos, campos obrigatórios presentes, nenhuma propriedade extra, JSON sempre parseável. Eliminam a classe inteira de erros de sintaxe.

O que eles não garantem é a semântica dos valores:

• itens de linha que não somam o total declarado (line_items = 100 + 50, total = 180);
• valor colocado no campo errado (data de emissão no campo de vencimento);
• valor inventado para satisfazer um campo obrigatório.

Erros semânticos exigem validação pós-extração e retry com feedback (Lição 5) e schemas bem projetados (abaixo).

Design de schema que evita fabricação

• Campos opcionais/nullable: se o documento pode não conter a informação, o campo deve aceitar null (ou ser opcional). Campo obrigatório + informação ausente = convite à fabricação: o modelo precisa preencher algo para satisfazer o schema.
• Enum com "unclear": para classificações, incluir um valor de saída para "ambíguo/ilegível" dá ao modelo uma rota honesta em vez de forçar um chute entre categorias.
• Enum com "other" + campo detail: categorias do mundo real são abertas; "other" acompanhado de um campo texto (category_detail) captura casos fora da lista sem quebrar o schema — e os detail acumulados indicam quais categorias novas criar.
• Regras de normalização no prompt: o schema define a forma; regras como "datas em ISO 8601, valores como número decimal sem símbolo de moeda" entram no prompt, ao lado do schema.

Prefill de assistente: padrão obsoleto (erro 400)

Um padrão antigo de forçar JSON era o prefill: terminar messages com uma mensagem assistant parcial (ex.: {"role": "assistant", "content": "{"}) para o modelo "continuar" de dentro do JSON. Nos modelos atuais esse padrão retorna erro 400 — a API rejeita a mensagem assistant parcial ao final. Ele foi substituído por output_config.format e por tool use com strict, que dão garantias reais de schema (o prefill nunca garantiu validade — só induzia o começo). Em questões de prova, prefill aparece como distrator de "solução legada".

Pegadinhas da prova

• Distrator típico: "use prefill de assistente para forçar JSON" — obsoleto, retorna 400 nos modelos atuais e nunca garantiu schema.
• Distrator típico: "com strict: true os totais sempre baterão" — strict garante sintaxe/aderência ao schema, não aritmética nem campo certo (validação semântica continua necessária).
• Distrator típico: tool_choice: "auto" quando a saída estruturada é obrigatória — auto permite resposta em texto; a garantia vem de any/forçado (em claude-opus-5) ou de output_config.format.
• Distrator típico: tornar todos os campos required "para garantir extração completa" — isso causa fabricação quando o documento não tem a informação; o correto é nullable/opcional.
• Distrator típico: parâmetro top-level output_format na API — o parâmetro atual é output_config={"format": ...} (não confundir com o kwarg output_format do helper parse() do SDK).

Resumo em 5 linhas

Documentação oficial

• Structured outputs
• Tool use
• Implement tool use (tool_choice)

Questões de fixação