o problema
Um modelo que raciocina antes de responder gasta duas coisas que o produto sente: tokens, que são cobrados como output, e tempo, que o usuário espera olhando a tela. Enquanto o raciocínio é uma caixa preta do provedor, quem constrói em cima dele não consegue prometer nada — nem custo por chamada, nem latência de cauda. Uma pergunta trivial e uma prova de teoria dos números caem no mesmo endpoint e saem com contas radicalmente diferentes.
O inverso também quebra. Cortar o raciocínio por padrão para ficar barato entrega resposta rasa justamente nas tarefas em que ele importa. E a dificuldade não é uma propriedade do deployment, é uma propriedade de cada requisição: o mesmo agente que responde “qual o status do build” também precisa desenrolar um traceback de trinta frames. O controle, se existir, tem que ser por chamada.
a ideia
O modo manual de extended thinking expõe esse controle como um campo do corpo da requisição. Você manda thinking: {type: "enabled", budget_tokens: N} e o modelo raciocina contra esse orçamento antes de começar a resposta final. É orçamento de obra, não cronômetro: o modelo pode gastar menos que o combinado e frequentemente gasta, mas ninguém garante que ele pare exatamente ali. O corte duro continua sendo o max_tokens.
A justificativa que a documentação dá para o modo manual é honesta e estreita: ele serve quando a carga de trabalho exige latência previsível ou controle preciso do custo de raciocínio. Não é uma alavanca de qualidade, é uma alavanca de previsibilidade.
como funciona
{
"model": "claude-sonnet-4-6",
"max_tokens": 16000,
"thinking": { "type": "enabled", "budget_tokens": 10000 }
}As regras do orçamento são três. O mínimo é 1.024 tokens e a API rejeita valores menores. O budget precisa ser menor que max_tokens, porque os tokens de thinking contam para o mesmo limite do turno. E, como consequência disso, o modo manual não combina com cache pre-warming, que depende de max_tokens: 0.
A exceção é o interleaved thinking, em que o modelo pensa entre chamadas de ferramenta dentro de um mesmo turno de assistant. Ali o budget_tokens pode passar do max_tokens, porque o orçamento cobre todos os blocos de thinking do turno. Habilitar isso no modo manual exige o header beta interleaved-thinking-2025-05-14 no Opus 4.5, no Sonnet 4.5 e nos modelos Claude 4 anteriores.
Para calibrar: tarefa simples começa perto do mínimo e sobe aos poucos; tarefa complexa começa em 16.000 ou mais e desce até o ponto em que latência e qualidade se encontram. O retorno é decrescente e o tamanho da queda depende da tarefa. Acima de 32 mil tokens de thinking, a orientação é ir para batch processing, porque a requisição fica longa demais para timeouts e limites de conexão aberta.
A medição vem do campo usage.output_tokens_details.thinking_tokens, que separa quanto do output cobrado foi raciocínio interno. Em streaming, esse detalhamento só aparece no message_delta final. Uma restrição estrutural fecha o pacote: no modo manual, o turno final de assistant precisa começar com um bloco de thinking.
o que isso custou
O controle é aproximado. Um orçamento que é alvo e não teto não dá garantia de custo por requisição — dá uma faixa. Quem precisa de limite real ainda depende do max_tokens.
O preço mais caro é a interação com prompt caching. O valor do budget é renderizado dentro do prompt, então mudá-lo entre requisições invalida breakpoints: breakpoints de mensagem sempre erram, e se os de tool e system prompt erram também depende de onde o modelo renderiza a configuração. A documentação mostra o efeito num experimento — a terceira requisição, com o budget subindo de 4.000 para 8.000, recria 1.370 tokens de cache em vez de lê-los. Na prática, ajustar orçamento dinamicamente por dificuldade e manter cache quente são objetivos que brigam.
O interleaved thinking chega fragmentado. O Sonnet 4.6 ainda aceita o header no modo manual, mas depreciado; o Opus 4.6 não tem interleaving nenhum no modo manual; o Haiku 4.5 não suporta o recurso. Pior: o header é aceito em qualquer modelo, na API da Anthropic e nas plataformas parceiras, e ignorado onde não funciona. Você não recebe erro, recebe silêncio.
E o modo manual pensa sempre. Com budget fixo, toda requisição paga raciocínio, inclusive as que não precisavam.
onde isso aparece hoje
Esse último ponto é o que matou o recurso. Nos modelos 4.6, budget_tokens está depreciado — as requisições ainda passam. Do 4.7 em diante, incluindo Opus 5, Sonnet 5, Fable 5.1 e Mythos 5, type: "enabled" retorna 400. O Mythos Preview aceita os dois modos; o Sonnet 4.5, o Opus 4.5, o Haiku 4.5 e os Claude 4 anteriores só aceitam o manual, e ali não há o que migrar.
A migração é pequena no papel: tira o budget_tokens, põe thinking: {type: "adaptive"} e move a profundidade para output_config: {effort: ...}, cujo padrão é high. O que muda é a semântica — quem decide se e quanto pensar passa a ser o modelo, e em effort baixo ele pode não pensar nada numa entrada fácil. O header beta pode sair junto, porque o modo adaptativo interleava sozinho. A preservação de blocos de thinking também mudou de lado no caminho: Opus 4.5 e os modelos 4.6 ou superiores mantêm os blocos dos turnos anteriores no contexto e os cobram como input, enquanto Sonnet 4.5, Haiku 4.5 e anteriores os descartavam.