Esta nota responde a uma pergunta que aparece assim que um time começa a usar modelos que pensam antes de responder: quando vale pedir ao modelo que pense mais, quanto isso custa em tokens e em tempo, e como decidir se o ganho compensa? A resposta curta é que o raciocínio custa saída paga e tempo de espera, e só compensa quando a tarefa tem passos que um rascunho realmente ajuda a acertar. Quem decide isso é uma medição feita no seu conjunto de casos, porque a impressão de que a resposta ficou mais cuidadosa não basta para justificar a conta.

A aula depende da 2.1 Escolha de modelo contra um eval. Sem o eval de lá, não há como saber se o raciocínio extra mudou alguma coisa. Os fatos desta nota foram lidos na documentação oficial da Anthropic em 18 de outubro de 2026, e os nomes de campos e parâmetros estão confirmados nessa leitura. Números de preço e de latência não aparecem aqui, porque não os confirmei para o raciocínio. Onde a documentação não disse algo, a nota diz que não disse.

Mapa da aula

Pré-requisitos: LLMs explica tokens, janela de contexto e o que o modelo faz com o texto. A 2.1 Escolha de modelo contra um eval explica o eval, o esforço como alavanca e a conta de custo por caso concluído.

Parte 1: o conceito

1. O que é raciocínio estendido

Imagine uma prova de matemática em que você não pode usar rascunho. Você lê a questão e escreve a resposta na primeira tentativa, sem voltar atrás. Quem resolve problemas difíceis assim costuma errar, porque a conta intermediária que pegaria o erro nunca foi escrita. Agora imagine que você pode rabiscar no canto da folha antes de escrever a resposta final. Esse rascunho é a ideia por trás do raciocínio estendido.

Em termos técnicos, raciocínio estendido (extended thinking) é a capacidade de o modelo gerar, antes da resposta visível, uma etapa interna de raciocínio. A documentação descreve essa etapa como o momento em que Claude reformula o pedido, tenta caminhos, confere resultados intermediários e abandona o que não se sustenta. Esse trecho volta para a aplicação em blocos de conteúdo do tipo thinking, separados do texto final.

Existem dois jeitos de ligar esse recurso, e a diferença entre eles é o assunto da seção 4. No modo manual, você informa um orçamento de tokens para o raciocínio. No modo adaptativo (adaptive thinking), você informa um nível de esforço e o próprio modelo decide, a cada requisição, se pensa e quanto. Os modelos mais recentes aceitam só o adaptativo, e isso muda bastante como o código deve ser escrito.

2. Para que serve

Um modelo que responde em uma passada só precisa acertar tudo de primeira. Para uma conta de três passos, isso costuma dar certo. Para um bug que aparece só quando duas funções interagem, ou para um plano que precisa respeitar cinco restrições ao mesmo tempo, a resposta direta costuma sair bem escrita e errada. A documentação diz que o pensamento melhora o desempenho justamente em matemática, código, análise e trabalho agêntico longo, onde a qualidade depende de um trabalho intermediário que, sem o rascunho, ou seria comprimido dentro da resposta ou seria pulado.

Repare que o problema raramente é falta de conhecimento. O modelo costuma saber as regras. O que falta é espaço para aplicar essas regras em sequência e voltar atrás quando uma delas não fecha. Por isso o ganho aparece em tarefas de passos encadeados e quase não aparece numa pergunta de fato, em que a resposta já está pronta na memória do modelo ou num documento que você passou.

3. Exemplos no plural

Quatro cenas mostram o padrão. Na primeira, um assistente de suporte recebe a pergunta “qual é o prazo de devolução?”. A resposta está num documento e não exige cálculo. Pensar mais aqui só gasta saída, e a resposta não melhora.

Na segunda, um sistema precisa decidir se um pedido de reembolso se enquadra em três regras que dependem umas das outras, com duas exceções. Um rascunho ajuda a não esquecer a exceção que anula a regra do meio, e o custo extra se paga se a alternativa for uma decisão errada com dinheiro envolvido.

Na terceira, um agente lê um repositório, roda os testes, interpreta o erro e propõe uma correção. Cada passo depende do anterior, e um engano no começo se propaga pelo resto da tarefa. Aqui o raciocínio costuma valer, e a diferença de qualidade se acumula ao longo dos passos.

Na quarta, um extrator de campos de notas fiscais devolve um JSON com CNPJ, data e valor. Pedir que o modelo pense antes de cada campo é como pedir ao caixa da padaria que explique em voz alta cada moeda antes de dar o troco: o resultado pode até ser o mesmo, e você pagou pela explicação. Nesse caso, o problema costuma estar no formato da saída, e a solução é a saída estruturada, não mais pensamento.

Parte 2: como funciona

4. Dois modos de ativar

No modo manual, a requisição leva thinking: {"type": "enabled", "budget_tokens": N}. O campo budget_tokens é o orçamento de tokens que o modelo pode usar para raciocinar. A documentação impõe duas regras: o valor mínimo é 1.024 tokens, e ele precisa ser menor que max_tokens, porque o raciocínio consome o mesmo limite da resposta. Há uma exceção para o pensamento intercalado com ferramentas, descrita na seção 9. Esse modo ainda funciona em alguns modelos, mas está obsoleto no Claude Sonnet 4.6 e Claude Opus 4.6, e é recusado com erro 400 nos modelos da geração 4.7 em diante. Como os modelos da família 5.5 fazem parte dessa geração, o modo manual não é o caminho para eles.

No modo adaptativo, a requisição leva thinking: {"type": "adaptive"}, e a profundidade do raciocínio é controlada pelo nível de esforço, em output_config: {"effort": "..."}. Os níveis são low, medium, high, xhigh e max, e nem todo modelo aceita todos. O padrão é medium no Claude Opus 5.5 e no Claude Haiku 5.5, e high nos demais modelos que aceitam o parâmetro. A documentação alerta para não passar adaptive como valor de esforço, porque adaptive é um modo de pensamento e não um nível.

A tabela abaixo resume o que cada modelo aceita. Ela vem da página de configuração do raciocínio e mostra só os modelos usados neste texto.

A migração do modo manual para o adaptativo é pequena no código, mas muda o comportamento. A documentação mostra o mapeamento: remover budget_tokens, colocar thinking: {"type": "adaptive"} e controlar a profundidade com output_config.effort.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}

A mudança de comportamento importa tanto quanto a de sintaxe. No modo manual, o modelo pensava em toda requisição porque você mandava pensar. No adaptativo, ele decide, e em pedidos simples pode não produzir nenhum bloco de raciocínio. Quem migra e espera ver sempre um bloco thinking na resposta vai achar um bug que não existe.

5. Como ativar, com código

Para o modelo Opus 5.5, a forma mais simples é o modo adaptativo com o texto do raciocínio visível. O trecho abaixo faz isso com o SDK Python. Para rodar sem chave de API, troquei o endereço padrão por um servidor local que devolve uma resposta de exemplo no formato documentado. O script de teste ficou na pasta de rascunho e não entrou no vault.

import anthropic

client = anthropic.Anthropic()  # lê ANTHROPIC_API_KEY do ambiente

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=16000,
    thinking={"type": "adaptive", "display": "summarized"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Qual é o maior divisor comum de 1071 e 462?"}],
)

for block in response.content:
    if block.type == "thinking":
        print("thinking:", block.thinking)
    elif block.type == "text":
        print("text:", block.text)
print("output_tokens:", response.usage.output_tokens)
print("thinking_tokens:", response.usage.output_tokens_details.thinking_tokens)

A saída real do script, com o servidor local, foi esta. A primeira parte é o corpo que o SDK de fato enviou, capturado pelo servidor, e a chave de API foi omitida na impressão.

== corpo recebido pelo servidor ==
{
  "max_tokens": 16000,
  "messages": [
    {
      "role": "user",
      "content": "Qual é o maior divisor comum de 1071 e 462?"
    }
  ],
  "model": "claude-opus-5-5",
  "output_config": {
    "effort": "medium"
  },
  "thinking": {
    "type": "adaptive",
    "display": "summarized"
  }
}
== cabeçalhos ==
{
  "anthropic-version": "2023-06-01"
}
== blocos ==
thinking: Euclides: 1071 = 2*462 + 147; 462 = 3*147 + 21; 147 = 7*21. MDC = 21.
text: O maior divisor comum de 1071 e 462 é 21.
== usage ==
output_tokens: 348
thinking_tokens: 312

O que esse teste prova é o formato: os campos chegam como a documentação pede, o SDK lê os blocos e o usage traz thinking_tokens. O que ele não prova é nada sobre o modelo real, porque o texto do bloco e os números foram escritos por mim seguindo o formato de exemplo. A chamada contra a API de verdade fica como exercício, porque não havia chave no ambiente.

Repare em duas coisas do código. A primeira é o display. Nos modelos da família 5.5, o padrão é omitted, em que o bloco thinking volta com o campo de texto vazio. A cobrança é a mesma nos dois casos, mas só com summarized você recebe o resumo para ler. A segunda é que o código não presume que o bloco exista: ele percorre os blocos e trata cada tipo, porque nem toda resposta vai trazer um thinking.

6. O orçamento e o que é cobrado

No modo manual, budget_tokens é uma meta e não um teto. A documentação diz que o modelo pode parar bem antes de gastar o orçamento, e que o limite rígido é sempre max_tokens, que inclui o raciocínio e a resposta juntos. No modo adaptativo não existe orçamento de raciocínio. Há dois controles: max_tokens, que é o limite duro da requisição, e effort, que é uma orientação sobre quanto gastar e não garante nenhuma quantidade de tokens. Em uma tarefa com ferramentas, cada requisição da mesma resposta tem o seu próprio max_tokens, então esse limite não segura o gasto da tarefa inteira.

Sobre a cobrança, a regra é direta. Os tokens de raciocínio são cobrados como tokens de saída. Isso vale mesmo quando o texto do raciocínio não é devolvido, porque o display muda apenas o que você vê e não o que você paga. A documentação é explícita sobre isso: o total de saída cobrado não bate com a contagem visível na resposta, porque a cobrança é pelo processo inteiro e não pelo resumo.

Para saber quanto foi gasto em raciocínio, leia usage.output_tokens_details.thinking_tokens. Esse campo é uma fatia de output_tokens, e o próprio output_tokens continua sendo o total cobrado. A documentação mostra o formato:

{
  "usage": {
    "input_tokens": 25,
    "output_tokens": 348,
    "output_tokens_details": {
      "thinking_tokens": 312
    }
  }
}

Nesse exemplo, 312 dos 348 tokens de saída foram raciocínio. Se você subtrair o raciocínio do total, sobra a parte que virou resposta visível, que é a que aparece para o usuário. Quando a requisição é em streaming, esse detalhamento aparece só no último evento message_delta.

Quando a resposta para em stop_reason: "max_tokens", quase sempre com um bloco de texto cortado ou ausente, o raciocínio pode ter consumido o limite antes da resposta. A documentação oferece dois remédios e diz como escolher entre eles. Se as respostas cortadas precisavam mesmo do raciocínio, suba max_tokens. Se elas foram superpensadas para uma pergunta simples, baixe o effort.

Esse ponto se liga à conta de custo da 2.1 Escolha de modelo contra um eval. Lá, o custo é a soma da entrada com a saída, cada uma multiplicada pelo seu preço. O raciocínio entra na parcela de saída, então ele aumenta a conta na mesma tabela de preços que você já usa. Não há um preço separado para o pensamento.

7. Latência e custo: quando o ganho se paga

A latência do raciocínio tem um mecanismo simples. O bloco de pensamento vem antes do texto. Por isso, quando você usa streaming com resumo visível, o primeiro token de texto só chega depois que o raciocínio termina. A documentação diz que display: "omitted" reduz o tempo até o primeiro token de texto justamente porque o servidor pula o streaming dos tokens de pensamento e entrega só a assinatura. A mesma lógica explica por que orçamentos maiores aumentam a latência: mais raciocínio significa mais tempo antes da resposta. A documentação também diz que o ganho de orçamentos maiores tem retorno decrescente, e que esse retorno depende da tarefa.

Dois detalhes práticos completam o quadro. No modo manual, a documentação recomenda processamento em lote quando o orçamento passa de 32 mil tokens, para evitar timeouts de rede em requisições longas. E baixar o effort reduz tokens, latência e custo de uma vez, com perda de capacidade em tarefas difíceis. A documentação não traz números de latência para cada nível, então não há tabela de milissegundos nesta aula. O número certo é o da sua carga.

Para medir, use o método da 2.1 Escolha de modelo contra um eval. Registre o tempo até o primeiro token e o tempo total de cada caso, guarde a mediana e o percentil 95, e some o custo por caso concluído, com os thinking_tokens em uma coluna à parte. Assim você vê, na mesma tabela, quanto o raciocínio custou e quanto ele mudou a pontuação.

A pergunta de quando o ganho se paga tem a mesma resposta que 2.1 Escolha de modelo contra um eval dá para a escolha de modelo. Compare o custo de um erro que chega ao usuário com o custo extra do raciocínio. Se um erro custa pouco e pode ser corrigido por outra pessoa, o raciocínio extra raramente se paga. Se um erro custa dinheiro, confiança ou uma ação irreversível, e se o seu eval mostra que o raciocínio fecha a diferença, ele se paga. A conta fica honesta quando você mede a diferença de qualidade no seu conjunto de casos, e não na promessa da propaganda.

8. Blocos de pensamento na resposta

A resposta de uma requisição com raciocínio é uma lista de blocos em content. Quando o modelo pensa, o primeiro bloco é do tipo thinking, e depois vêm os blocos text. Cada bloco thinking tem três campos relevantes: type, thinking com o texto (que pode estar vazio) e signature, uma cópia criptografada do raciocínio completo. Quando parte do raciocínio é redigida por motivos de segurança, o bloco vem como redacted_thinking, com um campo data opaco e sem texto legível.

O campo display controla o que chega no texto. Com summarized, o thinking traz um resumo do raciocínio. Com omitted, o campo vem vazio e só a assinatura carrega o conteúdo. Existe também updates, em beta, que devolve frases curtas de progresso que alguns modelos escrevem entre chamadas de ferramenta, e exige o cabeçalho beta thinking-display-updates-2026-08-18. O resumo não é o raciocínio bruto. A documentação diz que o texto é produzido por um modelo diferente do que você chamou, e que a cobrança segue o raciocínio completo e não o resumo.

A figura abaixo mostra o caminho de uma requisição com raciocínio, da aplicação até os blocos que voltam, incluindo o caso em que o limite de tokens interrompe a resposta.

Leia a figura da esquerda para a direita. A aplicação envia a requisição com a configuração de raciocínio e o esforço, e a API a repassa ao modelo. Dentro do modelo, a etapa de raciocínio é o que gera o bloco thinking, e o texto final gera o bloco text. As setas verdes mostram o que volta para você. O usage recebe a soma de tudo como saída, e a seta “conta como saída” lembra que o raciocínio é cobrado mesmo quando o campo de texto está vazio. A seta rosa marca o caminho que quebra a resposta: se o max_tokens acaba durante o raciocínio, o modelo para e a resposta sai sem o texto completo.

Para o código, a regra é devolver a resposta do assistente exatamente como veio quando ela contém uma chamada de ferramenta. Isso importa porque a assinatura prova ao servidor que o bloco foi gerado pelo Claude, e alterar o bloco causa erro 400. O SDK Python permite isso diretamente. Em um laço de ferramenta, a mensagem do assistente recebe response.content sem tratamento, e só depois vem o resultado da ferramenta. Testei esse fluxo contra o servidor local: a segunda requisição levou de volta o bloco thinking com a assinatura, o redacted_thinking com o campo data e o tool_use, todos sem alteração.

messages.append({"role": "assistant", "content": response.content})
messages.append({
    "role": "user",
    "content": [{"type": "tool_result", "tool_use_id": "toolu_1", "content": "20 C, sol"}],
})

O erro mais comum aparece aqui. Um filtro como [b for b in content if b.type == "text"] remove os blocos de raciocínio e quebra o protocolo. Se o filtro existir só para mostrar o texto ao usuário, ele deve ficar na exibição, nunca na mensagem que volta para a API. A documentação também alerta para o redacted_thinking: filtrar apenas por block.type == "thinking" o deixa de fora em silêncio.

Em streaming, o raciocínio chega como eventos thinking_delta, seguidos de um único signature_delta antes do fechamento do bloco, e só depois começam os text_delta. Para remontar os blocos completos com a assinatura, use o acumulador do SDK, como stream.get_final_message() em Python, em vez de concatenar os deltas na mão.

Por fim, não suponha que toda resposta traz um bloco thinking. No modo adaptativo, o modelo pode decidir que um pedido não precisa de raciocínio, e nesse caso a resposta começa direto pelo texto. Se a chamada de ferramenta for forçada, a resposta começa direto pelo tool_use, sem bloco de raciocínio. A seção 9 mostra quando essa forma de chamada é permitida.

9. Restrições

O raciocínio não combina com tudo, e as restrições mais úteis vêm da documentação de ferramentas, de amostragem e de desligamento do recurso.

Com ferramentas, o comportamento depende do modo. No modo manual, a documentação aceita só tool_choice: {"type": "auto"}, que é o padrão, ou {"type": "none"}. Os valores any e tool forçam a chamada de uma ferramenta, e isso é incompatível com o raciocínio manual, então a requisição dá erro. No modo adaptativo, a chamada forçada funciona, exceto nos modelos Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1, que rejeitam any e tool com erro 400. Quando a chamada forçada é aceita, a resposta começa com o tool_use e não traz bloco thinking. Se você quer que o modelo pense antes de chamar a ferramenta, use auto e diga no prompt quando usar a ferramenta.

Outra regra de ferramentas é a da troca de modo no meio do turno. Uma resposta com chamadas de ferramenta, somada aos resultados, é um único turno do assistente, e você não pode ligar ou desligar o raciocínio no meio dele. Se fizer isso, a API não dá erro, mas desliga o raciocínio daquela requisição em silêncio. Por isso a regra é trocar a configuração entre turnos e não dentro deles.

Com saídas estruturadas, a documentação que consultei não diz como output_config.format com json_schema combina com o raciocínio nem com tool_choice. Li a página até o limite de 100 mil dos cerca de 103 mil caracteres, e o trecho que li fala de ferramentas estritas e de limites conjuntos de esquemas, mas não trata do raciocínio. Esta é uma lacuna declarada, e a confirmação precisa vir de um teste seu. Um dado da mesma página vale a atenção: quando há ferramentas na requisição, o modelo pode chamar a ferramenta em vez de responder com o JSON. Na documentação de Haiku 5.5, também há a observação de que, com o raciocínio desligado, o modelo pode pular uma chamada de ferramenta de que precisaria quando você também pede JSON.

Com amostragem, a regra é mais dura do que parece. Nos modelos da família 4.7 em diante, incluindo Opus 5.5, Sonnet 5.5, Haiku 5.5 e Fable 5.1, valores de temperature, top_p ou top_k diferentes do padrão retornam erro 400 em toda requisição, com ou sem raciocínio. Nos modelos mais antigos, temperature e top_k são incompatíveis com o raciocínio ligado. Assim, se o seu código ajusta a temperatura para ter respostas mais estáveis, ele pode quebrar justamente ao trocar para um modelo com raciocínio.

Com o desligamento, cada modelo tem a sua regra. Claude Opus 5.5 e Claude Fable 5.1 não permitem desligar o raciocínio. Claude Sonnet 5.5 rejeita disabled e usa between_tools, que desliga o pensamento antes das ferramentas. Claude Haiku 5.5 aceita disabled com effort até high, e rejeita com xhigh ou max. Antes de enviar, verifique a configuração do modelo, porque a mesma linha de código pode funcionar em um e dar erro em outro.

Há ainda a prefilagem. Os modelos da geração 4.6 em diante rejeitam uma última mensagem do assistente pré-preenchida, com ou sem raciocínio. Quem usa esse truque para forçar um formato precisa de outro caminho, como a saída estruturada, que a própria documentação oferece como alternativa.

10. Critério de decisão: mais raciocínio, modelo maior ou mais contexto

Quando uma resposta sai ruim, há três alavancas plausíveis, e elas respondem a perguntas diferentes. Mais contexto responde à falta de informação. Mais raciocínio responde à falta de passos. Um modelo maior responde à falta de capacidade que sobrou depois das duas primeiras. A ordem importa porque cada alavanca custa diferente e porque ela só resolve o problema certo.

A figura abaixo transforma essa ordem em uma árvore de decisão. Ela começa a partir de uma resposta reprovada no eval, porque sem o eval a decisão é chute.

Leia a figura de cima para baixo. A primeira pergunta é sobre informação. Raciocínio não inventa um dado que o modelo não recebeu, então, se a resposta depende de um fato ausente, o caminho é adicionar contexto (recuperação de documentos, arquivos ou uma ferramenta) e medir de novo. A segunda pergunta é sobre passos. Se o erro acontece em uma sequência de deduções, a alavanca é o effort, que é mais barata de testar do que trocar de modelo. A terceira pergunta é sobre corte: se a resposta parou por max_tokens, o problema é de configuração e não de capacidade. Só no fim aparece o modelo maior, e a própria figura diz que ele precisa ser testado no mesmo eval e com o mesmo esforço. Comparar um modelo em esforço alto com outro em esforço baixo não diz nada sobre qual é o melhor.

Essa ordem segue 2.1 Escolha de modelo contra um eval. Lá, a seção 12 mostra que o esforço é uma alavanca antes da troca de nível, e a seção 13 mostra a conta entre custo de errar e custo de acertar mais caro. Aqui, o que muda é que o raciocínio aparece como uma das alavancas, com custo em saída e em latência.

Há um custo escondido na alavanca de esforço que vale checar antes de ajustar. Dentro de uma conversa com cache de prompt, trocar o nível de esforço no nível da requisição invalida o cache, porque o valor entra no prefixo renderizado. A documentação diz que, nos modelos que aceitam esforço por mensagem (em beta, com o cabeçalho mid-conversation-output-config-2026-07-01), você pode mudar o nível no meio da conversa sem perder o cache. Em modelos que não aceitam, escolha o nível no começo e mantenha. Isso significa que um ajuste de esforço pode ser barato no teste e caro em produção, se o cache dos seus prompts for grande.

11. Erros comuns e boas práticas

O primeiro erro é usar budget_tokens num modelo novo. A requisição falha com 400 porque o modo manual foi retirado da geração 4.7 em diante. A correção é trocar para thinking: {"type": "adaptive"} e controlar a profundidade com output_config.effort. Esse erro é o mais fácil de achar, porque a mensagem de erro cita o campo.

O segundo erro é reservar pouco max_tokens. O raciocínio consome o mesmo limite da resposta, e uma tarefa difícil pode gastar tudo antes do texto. O sintoma é stop_reason: "max_tokens" com texto cortado. A correção depende de a resposta cortada precisar do raciocínio: se precisar, suba o limite, e se não precisar, baixe o esforço.

O terceiro erro é filtrar os blocos de raciocínio ao devolver o histórico. O motivo é que a assinatura é verificada, e um bloco alterado ou faltando causa erro 400, enquanto um redacted_thinking removido quebra o protocolo sem aviso. A correção é devolver response.content como veio e filtrar só na exibição.

O quarto erro é supor que o raciocínio aparece em toda resposta. No modo adaptativo, o modelo decide caso a caso, e um código que espera sempre um bloco thinking na posição zero falha em pedidos simples. A correção é tratar cada tipo de bloco por nome.

O quinto erro é pedir “pense menos” no prompt para economizar. A documentação diz que, em Claude Sonnet 5.5, essa instrução não reduz o raciocínio de forma confiável, e que em Haiku 5.5 o mesmo acontece. O motivo é que o controle calibrado é o esforço, não a redação do pedido. A correção é baixar o esforço primeiro e só depois, se ainda for preciso, testar uma instrução no prompt, medindo o efeito.

O sexto erro é comparar modelos com esforços diferentes e atribuir a diferença ao modelo. A pontuação medida mistura o modelo com a quantidade de raciocínio. A correção é fixar o esforço, como 2.1 Escolha de modelo contra um eval já ensina, e variar uma coisa de cada vez.

O sétimo erro é mudar o esforço no meio de uma conversa com cache sem medir o efeito. A troca invalida o prefixo em cache e o custo sobe justamente na parte que deveria ser barata. A correção é escolher o esforço no início da conversa e manter, ou usar a troca por mensagem quando o modelo permitir.

O oitavo erro é tentar obter o raciocínio pedindo que o modelo o escreva no texto da resposta. A documentação diz que, em alguns modelos, um pedido desse tipo pode ser recusado com o motivo reasoning_extraction. A correção é ler o bloco thinking quando ele existir e, se você precisa de uma justificativa no texto, pedir uma explicação curta e não o raciocínio.

O nono erro é medir só o custo de texto. Quem olha apenas o texto da resposta subestima a conta, porque o raciocínio é cobrado como saída e aparece em thinking_tokens. A correção é registrar os dois valores em colunas separadas e somar no custo por caso concluído.

12. Exercícios

Primeiro exercício: pegue três chamadas de um sistema que você conhece e separe as que precisam de raciocínio das que não precisam. Para cada uma, escreva em uma frase o critério. Se você não tem um sistema, use os quatro exemplos da seção 3 e marque qual cena ganharia com o raciocínio.

Segundo exercício: rode vinte casos de um conjunto seu com o modelo Opus 5.5, uma vez com effort: low e outra com effort: medium. Registre a pontuação, a mediana e o percentil 95 de latência, o output_tokens e o thinking_tokens. Repita a execução e veja se a diferença de pontuação se mantém, como 2.1 Escolha de modelo contra um eval ensina sobre ruído.

Terceiro exercício: pegue um caso que terminou em stop_reason: "max_tokens" e decida, usando a figura 2, se o problema é de contexto, de passos ou de configuração. Escreva a pergunta que decidiu.

Quarto exercício: escreva o laço de ferramenta da seção 8 com uma ferramenta real do seu projeto. Depois troque o append do assistente por uma versão que filtra só os blocos text, rode e observe o erro. Corrija e explique em uma frase por que o filtro quebra o protocolo.

Quinto exercício, com chave de API: confirme os erros 400 de budget_tokens em Opus 5.5 e de tool_choice: any em Opus 5.5. Se não tiver chave, leia a tabela da seção 4 e escreva a mensagem de erro que você espera receber.

13. Glossário

Raciocínio estendido (extended thinking): etapa em que o modelo raciocina antes da resposta visível, com orçamento definido pela aplicação no modo manual.

Raciocínio adaptativo (adaptive thinking): modo em que o modelo decide, a cada requisição, se pensa e quanto, controlado pelo nível de esforço.

Bloco thinking: bloco de conteúdo com o resumo do raciocínio, quando display é summarized, e com a assinatura.

Assinatura (signature): versão criptografada do raciocínio completo, que precisa voltar sem alteração nas mensagens seguintes.

Bloco redacted_thinking: parte do raciocínio redigida por motivos de segurança, com o conteúdo no campo data.

budget_tokens: orçamento de tokens do raciocínio no modo manual. É uma meta, com mínimo de 1.024 tokens e sempre menor que max_tokens.

Esforço (effort): parâmetro em output_config que orienta quanto o modelo gasta em toda a resposta, incluindo o raciocínio. Os níveis são low, medium, high, xhigh e max.

max_tokens: limite rígido de saída da requisição, que inclui o raciocínio e o texto.

thinking_tokens: fatia de output_tokens que corresponde ao raciocínio, lida em usage.output_tokens_details.

stop_reason: motivo pelo qual a resposta terminou. O valor max_tokens indica que o limite foi atingido antes do fim.

display: campo que decide se o texto do raciocínio volta na resposta (summarized), volta vazio (omitted) ou traz apenas frases de progresso (updates, em beta).

Cache de prompt: reaproveitamento de um prefixo já processado. Mudar a configuração de raciocínio ou o esforço no meio da conversa pode invalidá-lo.

Eval: conjunto fixo de casos com critério de correção, usado para comparar configurações de forma repetível.

Navegação

Fontes

Consultadas em 18 de outubro de 2026, em platform.claude.com. Li as páginas pela ferramenta de leitura. Algumas são longas, então li as partes que tratam diretamente do assunto.

• Claude: Extended thinking: modo manual, regras de budget_tokens, migração para o adaptativo, cabeçalhos beta e observação sobre o modo manual nos modelos 4.6.
• Claude: Thinking: visão geral, tabela de configuração por modelo, display, blocos, streaming, ferramentas e limites. A página é longa e foi lida em trechos, com busca no texto para as seções de preservação e limites.
• Claude: Steering thinking: níveis de esforço e comportamento do raciocínio, custo, cobrança e usage.output_tokens_details.
• Claude: Troubleshooting thinking: tabela de modelos com modos aceitos, padrões e rejeições, e as mensagens de erro 400 mais comuns.
• Claude: Effort: parâmetro output_config.effort, níveis, padrões por modelo, esforço com ferramentas e troca de esforço por mensagem em beta.
• Claude: Structured outputs: output_config.format e uso com ferramentas. Li até cerca de 100 mil dos 103 mil caracteres da página, e não encontrei nela nada sobre raciocínio.
• Nota 2.1 Escolha de modelo contra um eval: tabela de preços, seção de esforço e método de medição usados como referência.

Não verificado

Não chamei a API real. Não havia chave de API no ambiente, então o código foi executado contra um servidor local que devolve uma resposta de exemplo no formato da documentação. O que foi testado é o formato da requisição, a leitura dos blocos e o reenvio dos blocos de raciocínio. Os textos e números da resposta são de exemplo.

Não há números de latência nem de preço do raciocínio nesta aula. A documentação não trouxe números de latência por nível de esforço, e eu não os confirmei em outra fonte.

A combinação de saída estruturada com raciocínio e com tool_choice ficou sem confirmação, pelo motivo descrito na seção 9.

Não detalhei a regra de preservação dos blocos de raciocínio por modelo, isto é, quais turnos anteriores continuam no contexto e como são cobrados como entrada. Li essa parte da documentação só por trechos, e um teste seu com conversa longa confirmaria o comportamento.

Relacionados

• 2.1 Escolha de modelo contra um eval
• LLMs