Pensamento adaptativo

Pensamento adaptativo é a forma recomendada de usar pensamento estendido com Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6, e é o modo padrão em Claude Mythos Preview (onde se aplica automaticamente sempre que thinking não está definido). Em vez de definir manualmente um orçamento de token de pensamento, pensamento adaptativo permite que Claude determine dinamicamente quando e quanto usar pensamento estendido com base na complexidade de cada solicitação. No Claude Opus 4.7, pensamento adaptativo é o único modo de pensamento suportado; thinking: {type: "enabled", budget_tokens: N} manual não é mais aceito.

Modelos suportados

Pensamento adaptativo é suportado nos seguintes modelos:

• Claude Mythos Preview (claude-mythos-preview), pensamento adaptativo é o padrão; thinking: {type: "disabled"} não é suportado
• Claude Opus 4.7 (claude-opus-4-7), pensamento adaptativo é o único modo de pensamento suportado. Pensamento está desativado a menos que você defina explicitamente thinking: {type: "adaptive"} em sua solicitação; thinking: {type: "enabled"} manual é rejeitado com um erro 400.
• Claude Opus 4.6 (claude-opus-4-6)
• Claude Sonnet 4.6 (claude-sonnet-4-6)

Como funciona o pensamento adaptativo

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

Pensamento adaptativo também ativa automaticamente pensamento intercalado. Isso significa que Claude pode pensar entre chamadas de ferramenta, 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:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=16000,
    thinking={"type": "adaptive"},
    messages=[
        {
            "role": "user",
            "content": "Explain why the sum of two even numbers is always even.",
        }
    ],
)

for block in response.content:
    if block.type == "thinking":
        print(f"\nThinking: {block.thinking}")
    elif block.type == "text":
        print(f"\nResponse: {block.text}")

Pensamento adaptativo com o parâmetro de esforço

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

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-opus-4-7",
    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)

Streaming com pensamento adaptativo

Pensamento adaptativo funciona perfeitamente com streaming. Blocos de pensamento são transmitidos via eventos thinking_delta assim como modo de pensamento manual:

client = anthropic.Anthropic()

with client.messages.stream(
    model="claude-opus-4-7",
    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)

Pensamento adaptativo vs manual vs desativado

Considerações importantes

Mudanças de validação

Ao usar pensamento adaptativo, turnos anteriores do assistente não precisam começar com blocos de pensamento. Isso é mais flexível do que modo manual, onde a API impõe que 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 ferramenta permanecem em cache independentemente de mudanças de modo.

Ajuste do comportamento de pensamento

O comportamento de acionamento do pensamento adaptativo é solicitável. 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.

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 dão a você controle efetivo sobre custo.

Nos níveis de esforço high e max, Claude pode pensar mais extensivamente e pode ser mais provável de esgotar o orçamento de 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 seguintes conceitos 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. This is the default behavior on Claude 4 models when the display field on the thinking configuration is unset or set to "summarized". On Claude Opus 4.7 and Claude Mythos Preview, display defaults to "omitted" instead, so you must set display: "summarized" explicitly to receive summarized thinking.

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.
• On Claude 4 models, the first few lines of thinking output are more verbose, providing detailed reasoning that's particularly helpful for prompt engineering purposes. Claude Mythos Preview summarizes from the first token, so its thinking blocks do not show this verbose preamble.
• 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.
• Summarization is processed by a different model than the one you target in your requests. The thinking model does not see the summarized output.

Controlando a exibição de pensamento

The display field on the thinking configuration controls how thinking content is returned in API responses. It accepts two values:

• "summarized": Thinking blocks contain summarized thinking text. See Summarized thinking for details. This is the default on Claude Opus 4.6, Claude Sonnet 4.6, and earlier Claude 4 models.
• "omitted": Thinking blocks are returned with an empty thinking field. The signature field still carries the encrypted full thinking for multi-turn continuity (see Thinking encryption). This is the default on Claude Opus 4.7 and Claude Mythos Preview.

Setting display: "omitted" is useful when your application doesn't surface thinking content to users. The primary benefit is faster time-to-first-text-token when streaming: The server skips streaming thinking tokens entirely and delivers only the signature, so the final text response begins streaming sooner.

Here are some important considerations for omitted thinking:

• You're still charged for the full thinking tokens. Omitting reduces latency, not cost.
• If you pass thinking blocks back in multi-turn conversations, pass them unchanged. The server decrypts the signature to reconstruct the original thinking for prompt construction (see Preserving thinking blocks). Any text you place in the thinking field of a round-tripped omitted block is ignored.
• display is invalid with thinking.type: "disabled" (there is nothing to display).
• When using thinking.type: "adaptive" and the model skips thinking for a simple request, no thinking block is produced regardless of display.

thinking = {
    "type": "adaptive",
    "display": "summarized",
}

Para exemplos de código e comportamento de streaming com display: "omitted", veja Controlando a exibição de pensamento na página de pensamento estendido. Os exemplos lá usam type: "enabled"; com pensamento adaptativo, use:

thinking = {"type": "adaptive", "display": "omitted"}

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.

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.
• signature values are compatible across platforms (Claude APIs, Amazon Bedrock, and Vertex AI). Values generated on one platform will be compatible with another.

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 prior assistant turns kept in context: only the last turn on earlier Opus/Sonnet models and all Haiku models; all turns by default on Opus 4.5+ and Sonnet 4.6+ (input tokens)
• Standard text output tokens

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

When using display: "omitted":

• Input tokens: Tokens in your original request (same as summarized)
• Output tokens (billed): The original thinking tokens that Claude generated internally (same as summarized)
• Output tokens (visible): Zero thinking tokens (the thinking field is empty)

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 ferramenta com pensamento: As mesmas regras se aplicam para pensamento adaptativo: preserve blocos de pensamento entre chamadas de ferramenta e esteja ciente das limitações de tool_choice quando 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 ferramenta permanecem em cache).
• Janelas de contexto: Como tokens de pensamento interagem com max_tokens e limites de janela de contexto.

Próximos passos