Direcionando o pensamento

O pensamento ("thinking") de Claude é adaptativo: o modelo avalia cada requisição e decide por si mesmo se deve pensar e quanto. Você define uma intenção, opcionalmente especifica o esforço ("effort"), 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 requisições triviais e complexas, e para fluxos de trabalho agênticos de longo horizonte em que a quantidade certa de raciocínio varia de etapa para etapa.

Para aprender como ativar o pensamento, como ler a saída de pensamento e sobre a saída de pensamento no Claude Fable 5 e no Claude Mythos 5, consulte a visão geral de Pensamento. Esta página aborda como Claude decide quando pensar, como direcionar essa decisão e as mecânicas de cache, custo e preços que decorrem disso.

Como Claude decide quando pensar

O pensamento é opcional para o modelo. Em cada requisiçã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 requisição. A mesma conversa pode conter turnos com e sem pensamento, e um turno em que Claude optou por não pensar não contém nenhum 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 uma orientação suave sobre o quanto Claude deve estar disposto 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 automaticamente com o uso de ferramentas: 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 nem de nenhuma 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 ou não em um determinado turno é algo que pode ser influenciado 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 entre qualidade e latência da sua carga de trabalho.
2. Adicione orientação no prompt apenas se o acionamento do pensamento 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 do pensamento. Cada nível define um padrão diferente para a frequência e a profundidade com que Claude pensa:

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 Esforço.

{
  "model": "claude-opus-5",
  "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 referência oficial sobre quais níveis cada modelo suporta.

Orientação no prompt do sistema

A orientação no prompt do sistema ("system prompt") desloca o limiar de pensamento de Claude para todas as requisições da 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, em vez disso, incentivar o pensamento, use uma frase como:

This task involves multistep reasoning. Think carefully before responding.

A eficácia do direcionamento pode ser sensível à redaçã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. Acrescentar "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 requisições em uma conversa justificam raciocínio estendido. Um harness de agente, por exemplo, pode acrescentar a frase de incentivo em etapas de planejamento e a frase de supressão em confirmações rotineiras, sem tocar no prompt do sistema nem alterar nenhum parâmetro de requisição entre 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ânicas

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 requisição com pensamento ativado comece com um; consulte Estrutura de turnos no modo manual.)

Para aplicações de múltiplos turnos, isso significa que você pode devolver o histórico da conversa no formato em que o tiver:

• Turnos do assistente em que Claude optou por 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.
• Histórico montado a partir de fontes mistas não precisa ter blocos de pensamento reinseridos no início de cada turno do assistente para passar na validação.

A flexibilização diz respeito à validação, não ao que você deve enviar. Quando você tiver blocos de pensamento, devolva-os sem modificação, 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

Requisições consecutivas que mantêm a mesma configuração de pensamento e o mesmo nível de esforço preservam o cache de prompt ("prompt caching"); consulte Pensamento e cache de prompt para as regras completas. O valor de esforço resolvido é renderizado no prompt, portanto alterá-lo entre requisições invalida os pontos de interrupção do cache, assim como alterar o parâmetro legado budget_tokens faz nos modelos que o utilizam. 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 acrescentada à mensagem mais recente do usuário deixa os pontos de interrupção de cache anteriores intactos, ao contrário de uma mudança de configuração ou de esforço.

O exemplo a seguir demonstra a invalidação com um script de múltiplos turnos que você pode executar por conta própria:

import requests

client = Anthropic()


def fetch_article_content(url):
    text = requests.get(url).text
    lines = (line.strip() for line in text.splitlines())
    return "\n".join(line for line in lines if line)


# Busca o conteúdo do artigo
book_url = "https://www.gutenberg.org/cache/epub/1342/pg1342.txt"
book_content = fetch_article_content(book_url)
# Usa apenas texto suficiente para cache (primeiros capítulos)
LARGE_TEXT = book_content[:10000]

# Sem prompt do sistema - cache nas mensagens em vez disso
MESSAGES = [
    {
        "role": "user",
        "content": [
            {
                "type": "text",
                "text": LARGE_TEXT,
                "cache_control": {"type": "ephemeral"},
            },
            {"type": "text", "text": "Analyze the tone of this passage."},
        ],
    }
]

# Primeira requisição - estabelece o cache
print("First request - establishing cache")
response1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"First response usage: {response1.usage}")

MESSAGES.append({"role": "assistant", "content": response1.content})
MESSAGES.append({"role": "user", "content": "Analyze the characters in this passage."})

# Segunda requisição - mesma configuração (acerto de cache esperado)
print("\nSecond request - same configuration (cache hit expected)")
response2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=MESSAGES,
)

print(f"Second response usage: {response2.usage}")

MESSAGES.append({"role": "assistant", "content": response2.content})
MESSAGES.append({"role": "user", "content": "Analyze the setting in this passage."})

# Terceira requisição - nível de esforço diferente (falha de cache esperada)
print("\nThird request - different effort level (cache miss expected)")
response3 = client.messages.create(
    model="claude-opus-5",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=MESSAGES,
)

print(f"Third response usage: {response3.usage}")

First request - establishing cache
First response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 15, output_tokens: 1033 }

Second request - same configuration (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 3546, input_tokens: 1062, output_tokens: 1630 }

Third request - different effort level (cache miss expected)
Third response usage: { cache_creation_input_tokens: 3546, cache_read_input_tokens: 0, input_tokens: 2706, output_tokens: 1468 }

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 para a saída total da requisição, pensamento e texto de resposta combinados. Claude nunca gera além dele. Em um loop de uso de ferramentas, cada requisição no turno tem seu próprio max_tokens, portanto 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 o 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 requisições difíceis.

No esforço high e acima, Claude pode pensar extensivamente e tem maior probabilidade de esgotar o orçamento. Se você vir stop_reason: "max_tokens" nas respostas, você tem duas soluções:

• 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 de resposta.

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

Preços

O pensamento gera 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 é cobrado de você é 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 parte da saída que não é raciocínio. Ao usar streaming, esse detalhamento aparece apenas no evento final message_delta.

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

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

Próximos passos