Direcionando o pensamento

O pensamento de Claude é adaptativo: o modelo avalia cada solicitação e decide por si mesmo se deve pensar e quanto. Você define uma intenção, opcionalmente especifica o esforço, e o modelo aloca raciocínio onde julga que o raciocínio ajudará.

Isso torna o pensamento uma ótima opção para cargas de trabalho que misturam solicitações triviais e complexas, e para fluxos de trabalho agênticos de longo horizonte onde a quantidade certa de raciocínio varia de etapa para etapa.

Para saber como ativar o pensamento, como ler a saída do pensamento e a saída do pensamento no Claude Fable 5 e Claude Mythos 5, consulte a visão geral de Pensamento. Esta página cobre como Claude decide quando pensar, como direcionar essa decisão e a mecânica de cache, custo e preços que decorre disso.



Como Claude decide quando pensar

O pensamento é opcional para o modelo. Em cada solicitação, Claude pondera a complexidade da entrada e decide se um raciocínio mais profundo melhoraria a resposta. Uma pergunta factual simples pode receber uma resposta direta sem nenhum bloco de pensamento; um problema matemático de várias etapas ou uma tarefa de depuração complicada aciona um raciocínio mais profundo.

A decisão acontece por solicitação. A mesma conversa pode conter turnos com e sem pensamento, e um turno em que Claude escolheu não pensar não contém bloco de pensamento. Não construa lógica de aplicação que presuma que todo turno do assistente começa com um.

O controle principal sobre essa decisão é o parâmetro effort, que atua como orientação suave sobre o quão disposto Claude deve estar a pensar e com que profundidade; consulte Níveis de esforço nesta página para saber o que cada nível faz.

Se você quiser que Claude pense com menos frequência, reduza o nível de esforço antes de recorrer ao direcionamento baseado em prompt.

O pensamento também se intercala com o uso de ferramentas automaticamente: Claude pode pensar entre chamadas de ferramentas, refletindo sobre cada resultado de ferramenta antes de decidir o que fazer em seguida (pensamento intercalado). Você não precisa de um cabeçalho beta ou de qualquer configuração adicional para isso.

Para o panorama completo de como a configuração de pensamento e o parâmetro effort interagem, consulte Pensamento e esforço.



Direcionando com que frequência Claude pensa

Se Claude pensa em um determinado turno é algo que pode ser controlado por prompt. O esforço define a postura geral, mas você também pode moldar a decisão diretamente com orientação em linguagem natural, seja globalmente no prompt do sistema ou por mensagem a partir do turno do usuário.

Use as duas alavancas juntas nesta ordem:

1. Defina o nível de esforço que corresponde ao equilíbrio padrão de qualidade e latência da sua carga de trabalho.
2. Adicione orientação no prompt apenas se o acionamento de Claude ainda não corresponder às suas necessidades nesse nível.

Para orientações mais amplas de prompting com pensamento, consulte aproveite as capacidades de pensamento e pensamento intercalado.



Níveis de esforço

O esforço é a principal alavanca de direcionamento para o pensamento. Cada nível define um padrão diferente para a frequência com que Claude pensa e com que profundidade:

Esta tabela descreve como cada nível altera o comportamento de pensamento. Para orientação sobre qual nível escolher para uma determinada carga de trabalho, incluindo recomendações por modelo, consulte Quando ajustar o parâmetro effort na página de esforço.

O esforço é definido em output_config.effort, não dentro do objeto thinking; para exemplos completos por linguagem, consulte Effort.

{
  "model": "claude-opus-4-8",
  "max_tokens": 4096,
  "output_config": { "effort": "medium" },
  "messages": [{ "role": "user", "content": "..." }]
}

A disponibilidade dos níveis varia por modelo; a tabela de disponibilidade de esforço na página de esforço é a autoridade sobre quais níveis cada modelo suporta.



Orientação no prompt do sistema

A orientação no prompt do sistema desloca o limiar de pensamento de Claude para todas as solicitações na conversa. Se Claude estiver pensando com mais frequência do que sua carga de trabalho precisa, adicione uma orientação como esta ao seu prompt do sistema:

Extended thinking adds latency and should only be used when it
will meaningfully improve answer quality, typically for problems
that require multistep reasoning. When in doubt, respond directly.

Para incentivar o pensamento, em vez disso, use uma frase como:

This task involves multistep reasoning. Think carefully before responding.

A eficácia do direcionamento pode ser sensível à formulação exata. Se uma formulação não produzir o comportamento desejado, tente uma variante mais direta.



Direcionamento por mensagem

Você também pode direcionar o pensamento por mensagem a partir do turno do usuário, independentemente do prompt do sistema. Anexar "Please think hard before responding." a uma mensagem do usuário incentiva Claude a pensar naquele turno; "Answer directly without deliberating." o suprime.

O direcionamento por mensagem é útil quando apenas algumas solicitações em uma conversa justificam raciocínio estendido. Um harness de agente, por exemplo, pode anexar a frase de incentivo em etapas de planejamento e a frase de supressão em confirmações rotineiras, sem tocar no prompt do sistema ou alterar quaisquer parâmetros de solicitação entre os turnos.



Verifique o direcionamento na sua carga de trabalho

O direcionamento baseado em prompt altera o comportamento do modelo, então trate-o como qualquer outra mudança de prompt: meça antes de lançar. Execute uma amostra representativa do seu tráfego com e sem a orientação, e compare com que frequência o pensamento é acionado (a presença de blocos de pensamento nas respostas), o uso de tokens de saída, a latência e a qualidade das respostas nos casos que importam para você.



Mecânica

Três mecânicas decorrem do fato de Claude gerenciar seu próprio pensamento: validação de turnos, cache de prompt e como você limita o custo.



Validação de turnos

Os turnos do assistente não precisam começar com um bloco de pensamento. (Modelos que usam um orçamento de pensamento manual legado exigem que o turno final do assistente de uma solicitação com pensamento habilitado comece com um; consulte Estrutura de turnos no modo manual.)

Para aplicações multi-turno, isso significa que você pode passar de volta o histórico da conversa no formato que tiver:

• Turnos do assistente em que Claude escolheu não pensar são histórico válido como estão.
• Você pode retomar uma conversa que começou sem pensamento, ou que usou uma configuração de pensamento diferente, sem reescrever seu histórico.
• O histórico montado a partir de fontes mistas não precisa de blocos de pensamento reinseridos no início de cada turno do assistente para passar na validação.

A flexibilização é sobre validação, não sobre o que você deve enviar. Quando você tiver blocos de pensamento, passe-os de volta sem modificações, particularmente durante o uso de ferramentas, onde eles carregam o raciocínio por trás das chamadas de ferramentas de Claude. Consulte a visão geral de Pensamento para as regras completas.



Cache de prompt

Solicitações consecutivas que mantêm a mesma configuração de pensamento e nível de esforço preservam o cache de prompt; consulte Pensamento e cache de prompt para as regras completas. O valor de esforço resolvido é renderizado no prompt, então alterá-lo entre solicitações invalida os pontos de interrupção do cache, assim como alterar o parâmetro legado budget_tokens faz nos modelos que o usam. Definir effort explicitamente como o padrão do modelo é equivalente a omiti-lo e não quebra o cache.

A consequência prática: escolha uma configuração de pensamento e um nível de esforço por conversa e mantenha-os. Se alguns turnos precisarem de mais ou menos pensamento, direcione com prompting por mensagem: a orientação anexada à mensagem mais recente do usuário deixa os pontos de interrupção de cache anteriores intactos, enquanto uma mudança de configuração ou de esforço não.

O exemplo a seguir demonstra a invalidação com um script multi-turno que você mesmo pode executar:



Controle de custo

Você não define um orçamento de tokens de pensamento. Dois controles limitam o custo:

• max_tokens é um limite rígido na saída total da solicitação, pensamento e texto de resposta combinados. Claude nunca gera além dele. Em um loop de uso de ferramentas, cada solicitação no turno tem seu próprio max_tokens, então ele não limita o gasto do turno inteiro.
• effort é uma orientação suave sobre quanto dessa saída Claude aloca para o pensamento. Ele molda o comportamento, mas não garante uma contagem de tokens.

Como o pensamento conta para max_tokens, defina-o alto o suficiente para deixar espaço tanto para o raciocínio quanto para a resposta. Um max_tokens dimensionado para uma resposta sem pensamento costuma ser pequeno demais quando Claude começa a pensar em solicitações difíceis.

No esforço high e acima, Claude pode pensar extensivamente e é mais provável que esgote o orçamento. Se você vir stop_reason: "max_tokens" nas respostas, você tem dois remédios:

• Aumente max_tokens para dar ao modelo mais espaço para o pensamento mais a resposta.
• Reduza o nível de esforço para que Claude pense menos e deixe mais do orçamento para o texto da resposta.

Qual deles é o correto depende de se as respostas truncadas precisavam do raciocínio. Se a qualidade nessas solicitações importa, aumente o limite; se elas foram pensadas em excesso, reduza o esforço.



Preços

O pensamento incorre em cobranças por:

• Tokens que Claude usa enquanto pensa (cobrados como tokens de saída)
• Blocos de pensamento de turnos anteriores do assistente que permanecem no contexto, conforme o padrão de preservação: todos os turnos por padrão em modelos que mantêm tudo, apenas o último turno nos demais (cobrados como tokens de entrada)
• Tokens de saída de texto padrão

O que você é cobrado é o mesmo independentemente da configuração display; apenas o que você vê muda:

Para ver quantos tokens de saída cobrados foram gastos em raciocínio interno, leia usage.output_tokens_details.thinking_tokens na resposta. Esse valor reflete o raciocínio bruto que o modelo gerou (não o texto resumido retornado no corpo) e é sempre menor ou igual a output_tokens. Subtraia-o de output_tokens para aproximar a porção da saída que não é raciocínio. Ao usar streaming, esse detalhamento aparece apenas no evento message_delta final.

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

output_tokens continua sendo o total inclusivo e autoritativo usado para cobrança. output_tokens_details é um detalhamento somente leitura para observabilidade. Para informações completas de preços, incluindo taxas base, gravações de cache, acertos de cache e tokens de saída, consulte Preços.



Próximos passos