Você chama a API do Claude — a interface da Anthropic pra enviar prompts e receber respostas programaticamente — e tarefas simples funcionam perfeitamente. Extração, sumarização, classificação: o Claude manda bem. Aí você joga algo difícil. Revisar um pull request de 2.000 linhas. Planejar uma migração de banco de dados. Debugar uma race condition. A resposta volta rápida, confiante e sutilmente errada. Tipo aquele aluno que leu a apostila por cima e tá improvisando na prova.

O problema não é o modelo. O problema é que você não tá dando rascunho pra ele.

Por que "só ler a documentação" não resolve

O Claude tem um recurso chamado extended thinking — a capacidade de raciocinar passo a passo internamente antes de responder, tipo mostrar os cálculos na prova de matemática, só que os cálculos ficam escondidos. A Anthropic lançou em 24 de fevereiro de 2025 com o Claude 3.7 Sonnet, e evoluiu drasticamente desde então.

A documentação é completa. Também são 4.000 palavras de tabelas de parâmetros, avisos de deprecação e guias de migração espalhados por três páginas separadas. A maioria dos devs faz uma de três coisas: ignora o thinking completamente, copia e cola uma config de um blog post voltado pra um modelo antigo, ou ativa sem controle de custo e recebe uma surpresa de R$ 250 na fatura.

Em 16 de abril de 2026, a Anthropic lançou o Claude Opus 4.7 e quebrou as três abordagens. O parâmetro manual budget_tokens que costumava controlar o custo do thinking? Retorna erro 400 agora. Um novo tokenizador infla a contagem de tokens em até 35%. E o thinking é invisível por padrão — enquanto ainda te cobra a taxa cheia de $25 por milhão de tokens.

Veja como configurar corretamente, na data de 27 de abril de 2026.

Passo 1: Ativar Adaptive Thinking

No Opus 4.7, você usa adaptive thinking — o modelo decide quanto pensar com base na dificuldade do problema. Sem orçamentos manuais de tokens. Você controla a intensidade com um parâmetro effort (um rótulo simples como "low", "high" ou "max") ao invés de chutar um número.

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "high"},
    messages=[{
        "role": "user",
        "content": "Review this SQL migration for correctness and edge cases: ..."
    }],
)

Três linhas adicionadas: thinking, output_config e um max_tokens maior — o teto de quantos tokens (pedaços de palavras que a IA processa, aproximadamente ¾ de uma palavra em inglês) a resposta pode conter. Tokens de thinking contam contra esse teto, então defina pelo menos 16.000. A Anthropic recomenda 32.000+ pra tarefas complexas. Se só o thinking já exceder seu max, a requisição falha — sem resposta parcial, só um erro.

/faion é a ferramenta de prompt do Nero pra gerar código funcional a partir de uma spec — cole o bloco abaixo e tenha um ponto de partida pronto pra produção.

/faion
Generate a Python function `call_with_thinking(prompt: str, effort: str = "high") -> str` that calls Claude Opus 4.7 with adaptive thinking using the anthropic Python SDK. Accept an effort parameter ("low", "medium", "high", "xhigh", "max"). Set max_tokens to 16000. Return the text response. Include error handling for API errors and a docstring explaining the effort levels.

Passo 2: Escolher o Nível de Esforço Certo

Nem todo prompt merece um doutorado em filosofia. Aqui vai a cola, baseada na orientação da Anthropic e dados de produção dos testes da Resolve AI:

Effort O que faz Quando usar
low Pula o thinking pra tarefas triviais Classificação, extração, pipelines de alto volume
medium Raciocínio moderado, pode pular Custo/qualidade equilibrado, maioria dos workflows agentic
high Quase sempre pensa profundamente Code review, análise, planejamento
xhigh Exploração estendida (só Opus 4.7) Código multi-arquivo, cadeias agentic longas
max Sem restrições no thinking Problemas de fronteira, pesquisa, orçamento ilimitado

A descoberta-chave da Resolve AI: Sonnet 4.6 em medium se iguala aproximadamente à qualidade do Opus 4.6 por uma fração do custo. Não vá direto pro maior modelo — vá pro nível de esforço certo num modelo mais barato. A otimização mais inteligente muitas vezes é não pagar pelo Opus.

Passo 3: Stream de Thinking pra UX em Tempo Real

Sem streaming, uma requisição com thinking pesado significa que seu usuário fica encarando uma tela morta por 30+ segundos. Com streaming, ele acompanha o raciocínio do modelo se desdobrando ao vivo — progresso visível ao invés de dúvida existencial sobre se o app travou.

with client.messages.stream(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    messages=[{"role": "user", "content": "Analyze this codebase architecture..."}],
) as stream:
    for event in stream:
        if event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(f"[thinking] {event.delta.thinking}", end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)

Repare no "display": "summarized". No Opus 4.7, o padrão é "omitted" — o modelo pensa, você paga pelos tokens, mas o texto do thinking volta vazio. Você precisa definir display explicitamente se quiser ver o que o modelo raciocinou. Debugar raciocínio invisível é exatamente tão divertido quanto parece.

/faion
Generate a Python function `stream_thinking_response(prompt: str, effort: str = "high")` that calls Claude Opus 4.7 with adaptive thinking and streaming enabled via the anthropic Python SDK. Set display to "summarized". Print thinking deltas prefixed with "[thinking]" and text deltas without prefix. Set max_tokens to 32000. Handle stream cleanup properly with a context manager.

Passo 4: Tool Use Sem Quebrar a Cadeia

Se sua integração usa tools — funções que o modelo pode chamar, como consultar um banco de dados ou bater numa API externa — você precisa preservar os blocos de thinking ao continuar a conversa. Remova eles e o Claude perde o contexto de raciocínio no meio do fluxo.

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    tools=[your_tool],
    messages=[
        {"role": "user", "content": "What's the production error rate?"},
        {"role": "assistant", "content": [
            thinking_block,   # MANTENHA ISSO — remover mata o contexto
            tool_use_block
        ]},
        {"role": "user", "content": [tool_result]},
    ],
)

Uma restrição que vai morder arquiteturas agentic: com thinking ativado, tool_choice — que controla se o Claude deve usar uma tool específica — só aceita "auto" ou "none". Forçar uma tool específica retorna erro.

Passo 5: Monitorar o Que Você Realmente Está Pagando

Toda resposta inclui um objeto usage. Depois de ativar o thinking, essa se torna a linha mais importante do seu codebase:

cost_per_mtok = 25  # Preço de output do Opus 4.7
output_cost = (response.usage.output_tokens / 1_000_000) * cost_per_mtok
print(f"Output tokens: {response.usage.output_tokens} (${output_cost:.4f})")

A contagem de tokens de output inclui TODOS os tokens de thinking — mesmo os invisíveis com display: "omitted". Se sua resposta visível tem 500 tokens mas output_tokens diz 8.000, você acabou de pagar por 7.500 tokens de raciocínio que ninguém viu. Segundo a página de preços da Anthropic, tokens de thinking são cobrados na taxa cheia de output: $25/MTok pro Opus, $15/MTok pro Sonnet.

/faion
Generate a Python helper function `log_thinking_cost(response, model: str = "claude-opus-4-7")` that takes an Anthropic Messages API response object and prints a cost breakdown: input tokens, output tokens (including thinking), cache read tokens, and total estimated cost in USD. Use a dict of per-model pricing (Opus 4.7: $15 input / $25 output, Sonnet 4.6: $3 input / $15 output). Warn if output_tokens exceeds 5000 with a note about possible high thinking usage.

Armadilhas Que Vão Te Pegar

O Imposto do Tokenizador. O novo tokenizador do Opus 4.7 gera até 35% mais tokens pro mesmo texto comparado ao Opus 4.6. Seus custos sobem sem nenhuma mudança de código ao trocar de modelo. Um processo de thinking que custava $0.25 no Opus 4.6 pode sair $0.34 no 4.7 — mesmo raciocínio, conta maior. Monitore usage antes e depois de trocar de modelo.

Tokens de Thinking Não Podem Ser Cacheados. Prompt caching — o recurso da Anthropic que dá desconto em tokens de input repetidos — não se aplica a conteúdo de thinking. Em loops agentic com muitas chamadas de tool, o Claude relê blocos de thinking de turnos anteriores como input. Isso cria custos compostos que você não vai ver a menos que rastreie cache_read_input_tokens separadamente.

A Armadilha Legacy. Ainda no Claude Sonnet 4.6 ou Opus 4.6? budget_tokens ainda funciona. Atualize pro Opus 4.7 e ele retorna erro 400 sem aviso de deprecação em runtime — só uma falha seca. Teste antes de fazer deploy.

O Teto do max_tokens. Tokens de thinking e tokens de resposta compartilham o mesmo limite de max_tokens. Defina max_tokens: 4000, e se o modelo pensar por 3.800 tokens, você recebe uma resposta de 200 tokens. Sempre defina mais alto do que acha necessário.

O Que Você Pode Fazer Agora

Você tem duas marchas. Pra os 80% rotineiros — extração, formatação, Q&A simples — use effort: "low" ou pule o thinking completamente. Pros 20% difíceis — code review, planejamento de arquitetura, análise complexa — use "high" ou "xhigh" com streaming e monitoramento de custos. Rode 100 chamadas, confira os números de usage, depois ajuste.

Há um ano, toda chamada à API do Claude rodava na mesma profundidade — rápida, rasa, uma marcha só. Agora você controla o dial. O modelo que raciocina por 30 segundos num bug difícil é o mesmo modelo que pula o thinking completamente numa tarefa de classificação. Mesmo endpoint, mesmo código, três linhas de config de diferença. Gire.