Pensamento estendido

O "extended thinking" (pensamento estendido) no modo manual dá a você controle direto sobre quanto Claude pensa. Você define um orçamento de tokens de pensamento em cada requisição com thinking: {type: "enabled", budget_tokens: N}, e Claude pensa dentro desse orçamento antes de começar sua resposta final. O modo manual continua útil quando sua carga de trabalho exige latência previsível ou controle preciso sobre os custos de pensamento. Esta página aborda como definir e ajustar o orçamento, como o modo manual interage com o pensamento intercalado e o "prompt caching" (cache de prompt), e como migrar para o pensamento adaptativo.

Para aprender como o pensamento em si funciona, incluindo blocos de pensamento e o formato da resposta, o parâmetro display, streaming, pensamento com "tool use" (uso de ferramentas) e criptografia, consulte a visão geral do pensamento.

Modelos suportados

A disponibilidade do pensamento estendido por modelo, incluindo os modelos em que o pensamento estendido é o único modo, está listada na tabela de configuração por modelo.

Como usar o pensamento estendido

Aqui está um exemplo de uso do pensamento estendido na Messages API:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=16000,
    thinking={"type": "enabled", "budget_tokens": 10000},
    messages=[
        {
            "role": "user",
            "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
        }
    ],
)

# A resposta contém blocos de pensamento resumidos e blocos de texto
for block in response.content:
    match block.type:
        case "thinking":
            print(f"\nThinking summary: {block.thinking}")
        case "text":
            print(f"\nResponse: {block.text}")

Para ativar o pensamento estendido manual, adicione um objeto thinking com type definido como enabled e um valor de budget_tokens.

O parâmetro budget_tokens define uma meta de quantos tokens Claude pode usar em seu processo de raciocínio interno. Orçamentos maiores podem melhorar a qualidade da resposta ao permitir uma análise mais completa de problemas complexos.

Regras e ajuste do orçamento

budget_tokens deve satisfazer estas restrições:

• Mínimo de 1.024 tokens. A API rejeita valores menores.
• Menor que max_tokens. Os tokens de pensamento contam para o limite de max_tokens do turno, portanto o orçamento deve deixar espaço para a resposta final. A única exceção é o pensamento intercalado, em que budget_tokens pode exceder max_tokens porque o orçamento abrange todos os blocos de pensamento dentro de um turno do assistente.
• Sem pré-aquecimento de cache. Como budget_tokens deve ser menor que max_tokens, o pensamento estendido não pode ser combinado com max_tokens: 0 (pré-aquecimento do cache).

O orçamento é uma meta, não um limite rígido. O uso real de tokens varia com a tarefa, e Claude pode parar de raciocinar bem antes de o orçamento se esgotar; max_tokens continua sendo o teto rígido da saída total.

No Claude Opus 4.5, o único modelo exclusivo de pensamento estendido que suporta effort, o effort molda a resposta geral enquanto budget_tokens define a profundidade do pensamento; defina ambos.

Para ajustar o orçamento:

• Adeque o ponto de partida à tarefa. Para tarefas simples, comece perto do mínimo de 1.024 tokens e aumente gradualmente para encontrar a faixa ideal para o seu caso de uso. Para tarefas complexas, comece com um orçamento maior, de 16.000 tokens ou mais, e ajuste conforme suas necessidades de latência e qualidade. Orçamentos maiores permitem um raciocínio mais abrangente, com retornos decrescentes que dependem da tarefa, e ao custo de maior latência. Para tarefas críticas, teste diferentes configurações para encontrar o equilíbrio certo.
• Para orçamentos de pensamento acima de 32k, use o processamento em lote para evitar problemas de rede. Forçar o modelo a pensar além de 32k tokens produz requisições de longa duração que podem atingir timeouts do sistema e limites de conexões abertas.

Para acompanhar quanto um orçamento realmente custa a você, monitore o campo usage.output_tokens_details.thinking_tokens na resposta, que informa quantos dos tokens de saída cobrados foram raciocínio interno. Ao usar streaming, esse detalhamento aparece apenas no evento final message_delta.

Quando você estiver pronto para deixar os orçamentos manuais, consulte Migrando para o pensamento adaptativo.

Pensamento intercalado no modo manual

O "interleaved thinking" (pensamento intercalado) permite que Claude pense entre chamadas de ferramentas dentro de um único turno do assistente, raciocinando sobre cada resultado de ferramenta antes de decidir o que fazer em seguida. Para o conceito, a estrutura de turnos e como ele se comporta em modelos de pensamento adaptativo, consulte pensamento intercalado na visão geral do pensamento. Esta seção aborda como ativá-lo quando você usa o pensamento manual type: "enabled".

No Claude Opus 4.5, no Claude Sonnet 4.5 e em modelos Claude 4 anteriores, adicione o cabeçalho beta interleaved-thinking-2025-05-14 à sua solicitação de API.

A geração 4.6 se divide no modo manual:

• Claude Sonnet 4.6: o cabeçalho beta com type: "enabled" manual ainda funciona, mas está descontinuado. Prefira o pensamento adaptativo, que intercala automaticamente sem cabeçalho.
• Claude Opus 4.6: o modo manual não tem pensamento intercalado algum. Apenas seu modo adaptativo intercala, então mude para thinking: {type: "adaptive"} se você precisar de raciocínio entre chamadas de ferramentas neste modelo.

O Claude Haiku 4.5 não suporta pensamento intercalado. Na Claude API, o cabeçalho beta é aceito, mas ignorado.

Mais duas considerações sobre o pensamento intercalado no modo manual:

• budget_tokens pode exceder max_tokens aqui; as regras do orçamento explicam essa exceção.
• O pensamento intercalado é suportado apenas para ferramentas usadas por meio da Messages API.

A forma como as plataformas tratam o cabeçalho beta difere. A Claude API e a Claude Platform on AWS aceitam interleaved-thinking-2025-05-14 em qualquer modelo e o ignoram onde não é suportado. Aceitação não é o mesmo que efeito: em modelos que rejeitam type: "enabled" (4.7 e posteriores) ou que não têm intercalação no modo manual (Claude Opus 4.6), o cabeçalho não tem efeito no modo manual; o pensamento adaptativo intercala automaticamente nesses casos.

Plataformas operadas por parceiros (Amazon Bedrock e Google Cloud) também aceitam o cabeçalho em qualquer modelo sem retornar erro e o ignoram em modelos que não suportam pensamento intercalado.

Estrutura de turnos no modo manual

As regras gerais de estrutura de turnos, incluindo o loop de uso de ferramentas em um único turno, o tratamento de conflitos no meio do turno e a alternância do pensamento entre turnos, estão em Pensamento com uso de ferramentas.

O modo manual adiciona um requisito: o turno final do assistente em uma requisição com pensamento ativado deve começar com um bloco de pensamento (o pensamento adaptativo elimina esse requisito). Alterar a configuração de pensamento entre turnos também invalida o cache de prompt; consulte a seção a seguir.

Cache de prompt no modo manual

O modo manual adiciona uma regra além do comportamento de cache neutro em relação ao modo descrito em pensamento e cache de prompt: alterar budget_tokens entre requisições invalida os pontos de interrupção do cache, assim como alternar modos de pensamento, porque o valor do orçamento é renderizado no prompt. Pontos de interrupção no nível de mensagem sempre falham após uma mudança de orçamento; se os pontos de interrupção de ferramentas e do prompt do sistema também falham depende de onde o modelo renderiza a configuração.

Na prática, escolha um orçamento e mantenha-o estável durante toda a vida de uma conversa em cache. Executar uma conversa de vários turnos com cache no nível de mensagem no Claude Sonnet 4.6 e alterar o orçamento na terceira requisição de 4.000 para 8.000 tokens mostra a invalidação diretamente:

First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }

A terceira requisição recria o cache (cache_creation_input_tokens=1370, cache_read_input_tokens=0) porque o orçamento mudou entre as requisições. Para uma versão executável do mesmo experimento no modo adaptativo, em que o nível de effort desempenha o papel de cache que budget_tokens desempenha aqui, consulte Cache de prompt na página de direcionamento.

Mecânicas compartilhadas

A maior parte do comportamento do pensamento é neutra em relação ao modo e está documentada uma única vez na página Pensamento. Tudo o que está lá também se aplica ao modo manual:

• Controlando a exibição do pensamento
• Streaming do pensamento
• Pensamento com uso de ferramentas, incluindo preservação de blocos de pensamento
• Pensamento e cache de prompt
• Pensamento e a janela de contexto
• Criptografia do pensamento
• Preços (na página Direcionando o pensamento)

Migrando para o pensamento adaptativo

Se o seu modelo suporta apenas pensamento estendido (Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5 e modelos Claude 4 anteriores), nenhuma ação é necessária agora: o pensamento adaptativo não está disponível neles, e type: "adaptive" retorna um erro 400. Mantenha budget_tokens até mudar para um modelo que suporte pensamento adaptativo e, então, aplique o mapeamento a seguir.

Você precisa migrar de type: "enabled" se:

• Você usa o Claude Opus 4.6 ou o Claude Sonnet 4.6, em que budget_tokens está descontinuado.
• Você usa o Claude 4.7 ou um modelo posterior, como Claude Opus 5.5, Claude Sonnet 5, Claude Sonnet 5.5 ou Claude Fable 5.1, em que type: "enabled" retorna um erro 400.

O mapeamento é pequeno: remova budget_tokens, defina thinking: {type: "adaptive"} e controle a profundidade do raciocínio com output_config: {effort: ...} em vez de um orçamento de tokens.

{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}

torna-se:

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

effort: "high" corresponde ao padrão da API; ele aparece aqui apenas para mostrar onde o controle de profundidade agora fica, e omiti-lo produz comportamento idêntico.

Espere uma diferença de comportamento, não apenas uma mudança de sintaxe. Com um orçamento fixo, Claude pensa em toda requisição. Com o pensamento adaptativo, Claude decide se e quanto pensar em cada requisição e, em configurações de effort mais baixas, pode pular o pensamento completamente em entradas fáceis. Você também pode remover o cabeçalho beta interleaved-thinking-2025-05-14 após migrar: o pensamento adaptativo intercala automaticamente, e a Claude API ignora o cabeçalho nesses modelos. A preservação de blocos de pensamento também muda: o Claude Opus 4.5 e os modelos numerados 4.6 e superiores mantêm os blocos de pensamento de turnos anteriores no contexto e os cobram como entrada, enquanto o Claude Sonnet 4.5, o Claude Haiku 4.5 e modelos anteriores os removiam; consulte preservação de blocos de pensamento por modelo.

Alternar modos é uma mudança de configuração de pensamento, portanto a primeira requisição após a troca invalida os pontos de interrupção do cache, conforme descrito em Cache de prompt no modo manual.

Para orientação completa, consulte pensamento adaptativo, effort e o guia de migração de modelos.

Próximos passos