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 determinar o que fazer em seguida. Para o conceito, a estrutura do turno e como ele se comporta em modelos com 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 (descontinuado) e em modelos Claude 4 anteriores, adicione o cabeçalho beta interleaved-thinking-2025-05-14 à sua requisiçã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 o pensamento estendido (Claude Sonnet 4.5 (descontinuado), 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 nesses modelos, e type: "adaptive" retorna um erro 400. Mantenha budget_tokens até passar para um modelo que suporte o 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, Claude Fable 5.1 ou Claude Haiku 5.5, 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" é o padrão no Claude Sonnet 4.6, portanto omiti-lo aqui produz um comportamento idêntico; ele aparece apenas para mostrar onde fica o controle de profundidade no modo adaptativo. O Claude Opus 5.5 e o Claude Haiku 5.5 têm "medium" como padrão, e outros modelos que suportam effort têm "high" como padrão (consulte Níveis de esforço).

Espere uma diferença de comportamento, não apenas uma mudança de sintaxe. Com um orçamento fixo, Claude pensa em todas as requisições. Com o pensamento adaptativo, Claude determina 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 a migração: 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 (descontinuado), 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