Pensamento adaptativo

O pensamento adaptativo é a forma recomendada de usar pensamento estendido com Claude Opus 4.6. Em vez de definir manualmente um orçamento de tokens de pensamento, o pensamento adaptativo permite que Claude decida dinamicamente quando e quanto pensar com base na complexidade de cada solicitação.

O pensamento adaptativo impulsiona consistentemente um desempenho melhor do que o pensamento estendido com um budget_tokens fixo, e recomendamos migrar para o pensamento adaptativo para obter as respostas mais inteligentes do Opus 4.6. Nenhum cabeçalho beta é necessário.

Modelos suportados

O pensamento adaptativo é suportado nos seguintes modelos:

Claude Opus 4.6 (claude-opus-4-6)

thinking.type: "enabled" e budget_tokens estão descontinuados no Opus 4.6 e serão removidos em um lançamento de modelo futuro. Use thinking.type: "adaptive" com o parâmetro de esforço em vez disso.

Modelos mais antigos (Sonnet 4.5, Opus 4.5, etc.) não suportam pensamento adaptativo e exigem thinking.type: "enabled" com budget_tokens.

Como o pensamento adaptativo funciona

No modo adaptativo, o pensamento é opcional para o modelo. Claude avalia a complexidade de cada solicitação e decide se e quanto pensar. No nível de esforço padrão (high), Claude quase sempre pensará. Em níveis de esforço mais baixos, Claude pode pular o pensamento para problemas mais simples.

O pensamento adaptativo também ativa automaticamente pensamento intercalado. Isso significa que Claude pode pensar entre chamadas de ferramentas, tornando-o especialmente eficaz para fluxos de trabalho de agentes.

Como usar pensamento adaptativo

Defina thinking.type como "adaptive" em sua solicitação de API:

Pensamento adaptativo com o parâmetro de esforço

Você pode combinar pensamento adaptativo com o parâmetro de esforço para orientar quanto Claude pensa. O nível de esforço atua como orientação suave para a alocação de pensamento de Claude:

Nível de esforço	Comportamento de pensamento
`max`	Claude sempre pensa sem restrições na profundidade do pensamento. Apenas Opus 4.6 — solicitações usando `max` em outros modelos retornarão um erro.
`high` (padrão)	Claude sempre pensa. Fornece raciocínio profundo em tarefas complexas.
`medium`	Claude usa pensamento moderado. Pode pular pensamento para consultas muito simples.
`low`	Claude minimiza o pensamento. Pula pensamento para tarefas simples onde a velocidade é mais importante.

Streaming com pensamento adaptativo

O pensamento adaptativo funciona perfeitamente com streaming. Os blocos de pensamento são transmitidos via eventos thinking_delta assim como no modo de pensamento manual:

Pensamento adaptativo vs manual vs desabilitado

Modo	Configuração	Disponibilidade	Quando usar
Adaptativo	`thinking: {type: "adaptive"}`	Opus 4.6	Claude decide quando e quanto pensar. Use `effort` para orientar.
Manual	`thinking: {type: "enabled", budget_tokens: N}`	Todos os modelos. Descontinuado no Opus 4.6 — use modo adaptativo em vez disso.	Quando você precisa de controle preciso sobre o gasto de tokens de pensamento.
Desabilitado	Omita o parâmetro `thinking`	Todos os modelos	Quando você não precisa de pensamento estendido e deseja a menor latência.

O pensamento adaptativo está atualmente disponível no Opus 4.6. Modelos mais antigos suportam apenas type: "enabled" com budget_tokens. No Opus 4.6, type: "enabled" com budget_tokens ainda é aceito, mas descontinuado — recomendamos usar pensamento adaptativo com o parâmetro de esforço em vez disso.

Considerações importantes

Mudanças de validação

Ao usar pensamento adaptativo, os turnos anteriores do assistente não precisam começar com blocos de pensamento. Isso é mais flexível do que o modo manual, onde a API impõe que os turnos com pensamento habilitado começam com um bloco de pensamento.

Cache de prompt

Solicitações consecutivas usando pensamento adaptive preservam pontos de interrupção de cache de prompt. No entanto, alternar entre modos de pensamento adaptive e enabled/disabled quebra pontos de interrupção de cache para mensagens. Prompts de sistema e definições de ferramentas permanecem em cache independentemente de mudanças de modo.

Ajuste do comportamento de pensamento

O comportamento de acionamento do pensamento adaptativo é orientável por prompt. Se Claude está pensando mais ou menos frequentemente do que você gostaria, você pode adicionar orientação ao seu prompt de sistema:

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

Orientar Claude a pensar com menos frequência pode reduzir a qualidade em tarefas que se beneficiam do raciocínio. Meça o impacto em suas cargas de trabalho específicas antes de implantar ajuste baseado em prompt em produção. Considere testar com níveis de esforço mais baixos primeiro.

Controle de custo

Use max_tokens como um limite rígido na saída total (pensamento + texto de resposta). O parâmetro effort fornece orientação suave adicional sobre quanto pensamento Claude aloca. Juntos, esses lhe dão controle efetivo sobre o custo.

Nos níveis de esforço high e max, Claude pode pensar mais extensivamente e pode ser mais provável que esgote o orçamento max_tokens. Se você observar stop_reason: "max_tokens" em respostas, considere aumentar max_tokens para dar mais espaço ao modelo, ou diminuir o nível de esforço.

Trabalhando com blocos de pensamento

Os conceitos a seguir se aplicam a todos os modelos que suportam pensamento estendido, independentemente de você usar modo adaptativo ou manual.

Pensamento resumido

With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude's full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse.

Here are some important considerations for summarized thinking:

You're charged for the full thinking tokens generated by the original request, not the summary tokens.
The billed output token count will not match the count of tokens you see in the response.
The first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes.
As Anthropic seeks to improve the extended thinking feature, summarization behavior is subject to change.
Summarization preserves the key ideas of Claude's thinking process with minimal added latency, enabling a streamable user experience and easy migration from Claude Sonnet 3.7 to Claude 4 and later models.
Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

Claude Sonnet 3.7 continues to return full thinking output.

In rare cases where you need access to full thinking output for Claude 4 models, contact our sales team.

Criptografia de pensamento

Full thinking content is encrypted and returned in the signature field. This field is used to verify that thinking blocks were generated by Claude when passed back to the API.

It is only strictly necessary to send back thinking blocks when using tools with extended thinking. Otherwise you can omit thinking blocks from previous turns, or let the API strip them for you if you pass them back.

If sending back thinking blocks, we recommend passing everything back as you received it for consistency and to avoid potential issues.

Here are some important considerations on thinking encryption:

When streaming responses, the signature is added via a signature_delta inside a content_block_delta event just before the content_block_stop event.
signature values are significantly longer in Claude 4 models than in previous models.
The signature field is an opaque field and should not be interpreted or parsed - it exists solely for verification purposes.
signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

Redação de pensamento

Occasionally Claude's internal reasoning will be flagged by our safety systems. When this occurs, we encrypt some or all of the thinking block and return it to you as a redacted_thinking block. redacted_thinking blocks are decrypted when passed back to the API, allowing Claude to continue its response without losing context.

When building customer-facing applications that use extended thinking:

Be aware that redacted thinking blocks contain encrypted content that isn't human-readable
Consider providing a simple explanation like: "Some of Claude's internal reasoning has been automatically encrypted for safety reasons. This doesn't affect the quality of responses."
If showing thinking blocks to users, you can filter out redacted blocks while preserving normal thinking blocks
Be transparent that using extended thinking features may occasionally result in some reasoning being encrypted
Implement appropriate error handling to gracefully manage redacted thinking without breaking your UI

Here's an example showing both normal and redacted thinking blocks:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "Let me analyze this step by step...",
      "signature": "WaUjzkypQ2mUEVM36O2TxuC06KN8xyfbJwyem2dw3URve/op91XWHOEBLLqIOMfFG/UvLEczmEsUjavL...."
    },
    {
      "type": "redacted_thinking",
      "data": "EmwKAhgBEgy3va3pzix/LafPsn4aDFIT2Xlxh0L5L8rLVyIwxtE3rAFBa8cr3qpPkNRj2YfWXGmKDxH4mPnZ5sQ7vB9URj2pLmN3kF8/dW5hR7xJ0aP1oLs9yTcMnKVf2wRpEGjH9XZaBt4UvDcPrQ..."
    },
    {
      "type": "text",
      "text": "Based on my analysis..."
    }
  ]
}

Seeing redacted thinking blocks in your output is expected behavior. The model can still use this redacted reasoning to inform its responses while maintaining safety guardrails.

If you need to test redacted thinking handling in your application, you can use this special test string as your prompt: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB

When passing thinking and redacted_thinking blocks back to the API in a multi-turn conversation, you must include the complete unmodified block back to the API for the last assistant turn. This is critical for maintaining the model's reasoning flow. We suggest always passing back all thinking blocks to the API. For more details, see the Preserving thinking blocks section.

Preços

For complete pricing information including base rates, cache writes, cache hits, and output tokens, see the pricing page.

The thinking process incurs charges for:

Tokens used during thinking (output tokens)
Thinking blocks from the last assistant turn included in subsequent requests (input tokens)
Standard text output tokens

When extended thinking is enabled, a specialized system prompt is automatically included to support this feature.

When using summarized thinking:

Input tokens: Tokens in your original request (excludes thinking tokens from previous turns)
Output tokens (billed): The original thinking tokens that Claude generated internally
Output tokens (visible): The summarized thinking tokens you see in the response
No charge: Tokens used to generate the summary

The billed output token count will not match the visible token count in the response. You are billed for the full thinking process, not the summary you see.

Tópicos adicionais

A página de pensamento estendido cobre vários tópicos em mais detalhes com exemplos de código específicos do modo:

Uso de ferramentas com pensamento: As mesmas regras se aplicam ao pensamento adaptativo — preserve blocos de pensamento entre chamadas de ferramentas e esteja ciente das limitações de tool_choice quando o pensamento está ativo.
Cache de prompt: Com pensamento adaptativo, solicitações consecutivas usando o mesmo modo de pensamento preservam pontos de interrupção de cache. Alternar entre modos adaptive e enabled/disabled quebra pontos de interrupção de cache para mensagens (prompts de sistema e definições de ferramentas permanecem em cache).
Janelas de contexto: Como tokens de pensamento interagem com max_tokens e limites de janela de contexto.

Próximos passos

curl https://api.anthropic.com/v1/messages \
     --header "x-api-key: $ANTHROPIC_API_KEY" \
     --header "anthropic-version: 2023-06-01" \
     --header "content-type: application/json" \
     --data \
'{
    "model": "claude-opus-4-6",
    "max_tokens": 16000,
    "thinking": {
        "type": "adaptive"
    },
    "messages": [
        {
            "role": "user",
            "content": "Explain why the sum of two even numbers is always even."
        }
    ]
}'

import anthropic

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={
        "type": "adaptive"
    },
    output_config={
        "effort": "medium"
    },
    messages=[{
        "role": "user",
        "content": "What is the capital of France?"
    }]
)

print(response.content[0].text)

import anthropic

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-6",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[{"role": "user", "content": "What is the greatest common divisor of 1071 and 462?"}],
) as stream:
    for event in stream:
        if event.type == "content_block_start":
            print(f"\nStarting {event.content_block.type} block...")
        elif event.type == "content_block_delta":
            if event.delta.type == "thinking_delta":
                print(event.delta.thinking, end="", flush=True)
            elif event.delta.type == "text_delta":
                print(event.delta.text, end="", flush=True)