Construindo com raciocínio estendido

O raciocínio estendido oferece ao Claude capacidades de raciocínio aprimoradas para tarefas complexas, enquanto fornece vários níveis de transparência em seu processo de pensamento passo a passo antes de entregar sua resposta final.

Modelos suportados

O raciocínio estendido é suportado em todos os modelos Claude suportados. Alguns modelos têm comportamento específico do modo:

• Claude Mythos Preview: raciocínio adaptativo é o padrão; thinking: {type: "enabled", budget_tokens: N} também é aceito. thinking: {type: "disabled"} não é suportado, e display padrão é "omitted" em vez de retornar conteúdo de raciocínio. Passe display: "summarized" para receber resumos.
• Claude Opus 4.6 (claude-opus-4-6): raciocínio adaptativo recomendado; modo manual (type: "enabled") está descontinuado, mas ainda funcional.
• Claude Sonnet 4.6 (claude-sonnet-4-6): raciocínio adaptativo recomendado; modo manual (type: "enabled") com modo intercalado está descontinuado, mas ainda funcional.

Como funciona o raciocínio estendido

Quando o raciocínio estendido é ativado, Claude cria blocos de conteúdo thinking onde produz seu raciocínio interno. Claude incorpora insights desse raciocínio antes de elaborar uma resposta final.

A resposta da API inclui blocos de conteúdo thinking, seguidos por blocos de conteúdo text.

Aqui está um exemplo do formato de resposta padrão:

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

Para mais informações sobre o formato de resposta do raciocínio estendido, consulte a Referência da API de Mensagens.

Como usar o raciocínio estendido

Aqui está um exemplo de uso do raciocínio estendido na API de Mensagens:

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-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?"
        }
    ]
}'

Para ativar o raciocínio estendido, adicione um objeto thinking, com o parâmetro type definido como enabled e o budget_tokens para um orçamento de token especificado para raciocínio estendido. Para Claude Opus 4.6 e Claude Sonnet 4.6, use type: "adaptive" em vez disso. Consulte Raciocínio adaptativo para detalhes. Embora type: "enabled" com budget_tokens ainda seja funcional nesses modelos, está descontinuado e será removido em uma versão futura.

O parâmetro budget_tokens determina o número máximo de tokens que Claude pode usar para seu processo de raciocínio interno. Nos modelos Claude 4 e posteriores, esse limite se aplica aos tokens de raciocínio completo, e não à saída resumida. Orçamentos maiores podem melhorar a qualidade da resposta, permitindo análise mais completa para problemas complexos, embora Claude possa não usar todo o orçamento alocado, especialmente em intervalos acima de 32k.

budget_tokens deve ser definido para um valor menor que max_tokens. No entanto, ao usar raciocínio intercalado com ferramentas, você pode exceder esse limite, pois o limite de token se torna sua janela de contexto inteira.

Raciocínio 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 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 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.

Controlando a exibição do raciocínio

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 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 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.

Pipelines automatizados que nunca expõem conteúdo de raciocínio aos usuários finais podem pular a sobrecarga de receber tokens de raciocínio pela rede. Aplicações sensíveis à latência obtêm a mesma qualidade de raciocínio sem esperar que o texto de raciocínio seja transmitido antes do início da resposta final.

Quando display: "omitted" é definido, a resposta contém blocos thinking com um campo thinking vazio:

{
  "content": [
    {
      "type": "thinking",
      "thinking": "",
      "signature": "EosnCkYICxIMMb3LzNrMu..."
    },
    {
      "type": "text",
      "text": "The answer is 12,231."
    }
  ]
}

Ao fazer streaming com display: "omitted", nenhum evento thinking_delta é emitido; consulte Streaming de raciocínio abaixo para a sequência de eventos.

Streaming de pensamento estendido

Você pode fazer streaming de respostas de pensamento estendido usando server-sent events (SSE).

Quando o streaming está habilitado para pensamento estendido, você recebe conteúdo de pensamento via eventos thinking_delta.

Quando display: "omitted" está definido, nenhum evento thinking_delta é emitido. Veja Controlando a exibição de pensamento.

Para mais documentação sobre streaming via a API de Mensagens, veja Streaming de Mensagens.

Aqui está como lidar com streaming com pensamento:

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-sonnet-4-6",
    "max_tokens": 16000,
    "stream": true,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is the greatest common divisor of 1071 and 462?"
        }
    ]
}'

Exemplo de saída de streaming:

event: message_start
data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-sonnet-4-6", "stop_reason": null, "stop_sequence": null}}

event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": "", "signature": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "I need to find the GCD of 1071 and 462 using the Euclidean algorithm.\n\n1071 = 2 × 462 + 147"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n462 = 3 × 147 + 21\n147 = 7 × 21 + 0\n\nSo GCD(1071, 462) = 21"}}

// Additional thinking deltas...

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "signature_delta", "signature": "EqQBCgIYAhIM1gbcDa9GJwZA2b3hGgxBdjrkzLoky3dl1pkiMOYds..."}}

event: content_block_stop
data: {"type": "content_block_stop", "index": 0}

event: content_block_start
data: {"type": "content_block_start", "index": 1, "content_block": {"type": "text", "text": ""}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "The greatest common divisor of 1071 and 462 is **21**."}}

// Additional text deltas...

event: content_block_stop
data: {"type": "content_block_stop", "index": 1}

event: message_delta
data: {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": null}}

event: message_stop
data: {"type": "message_stop"}

Quando display: "omitted" está definido, o bloco de pensamento abre, um único signature_delta chega, e o bloco fecha sem nenhum evento thinking_delta. O streaming de texto começa imediatamente depois:

event: content_block_start
data: {"type":"content_block_start","index":0,"content_block":{"type":"thinking","thinking":"","signature":""}}

event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"signature_delta","signature":"EosnCkYICxIMMb3LzNrMu..."}}

event: content_block_stop
data: {"type":"content_block_stop","index":0}

event: content_block_start
data: {"type":"content_block_start","index":1,"content_block":{"type":"text","text":""}}

Pensamento estendido com uso de ferramentas

O pensamento estendido pode ser usado junto com uso de ferramentas, permitindo que Claude raciocine através da seleção de ferramentas e processamento de resultados.

Ao usar pensamento estendido com uso de ferramentas, esteja ciente das seguintes limitações:

1. Limitação de escolha de ferramenta: O uso de ferramentas com pensamento suporta apenas tool_choice: {"type": "auto"} (o padrão) ou tool_choice: {"type": "none"}. Usar tool_choice: {"type": "any"} ou tool_choice: {"type": "tool", "name": "..."} resultará em um erro porque essas opções forçam o uso de ferramentas, o que é incompatível com pensamento estendido.

2. Preservando blocos de pensamento: Durante o uso de ferramentas, você deve passar blocos thinking de volta para a API para a última mensagem do assistente. Inclua o bloco completo e não modificado de volta para a API para manter a continuidade do raciocínio.

Alternando modos de pensamento em conversas

Você não pode alternar o pensamento no meio de um turno do assistente, incluindo durante loops de uso de ferramentas. O turno completo do assistente deve operar em um único modo de pensamento:

• Se o pensamento estiver ativado, o turno final do assistente deve começar com um bloco de pensamento.
• Se o pensamento estiver desativado, o turno final do assistente não deve conter nenhum bloco de pensamento

Do ponto de vista do modelo, loops de uso de ferramentas fazem parte do turno do assistente. Um turno do assistente não se completa até que Claude termine sua resposta completa, que pode incluir múltiplas chamadas de ferramentas e resultados.

Por exemplo, esta sequência faz parte de um único turno do assistente:

User: "What's the weather in Paris?"
Assistant: [thinking] + [tool_use: get_weather]
User: [tool_result: "20°C, sunny"]
Assistant: [text: "The weather in Paris is 20°C and sunny"]

Embora haja múltiplas mensagens de API, o loop de uso de ferramentas é conceitualmente parte de uma resposta contínua do assistente.

Degradação graciosa do pensamento

Quando ocorre um conflito de pensamento no meio do turno (como alternar o pensamento ativado ou desativado durante um loop de uso de ferramentas), a API desativa automaticamente o pensamento para essa solicitação. Para preservar a qualidade do modelo e permanecer na distribuição, a API pode:

• Remover blocos de pensamento da conversa quando criariam uma estrutura de turno inválida
• Desativar o pensamento para a solicitação atual quando o histórico de conversa é incompatível com o pensamento sendo ativado

Isso significa que tentar alternar o pensamento no meio do turno não causará um erro, mas o pensamento será silenciosamente desativado para essa solicitação. Para confirmar se o pensamento estava ativo, verifique a presença de blocos thinking na resposta.

Orientação prática

Melhor prática: Planeje sua estratégia de pensamento no início de cada turno em vez de tentar alternar no meio do turno.

Exemplo: Alternando pensamento após completar um turno

User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?"
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)

Ao completar o turno do assistente antes de alternar o pensamento, você garante que o pensamento esteja realmente ativado para a nova solicitação.

Preservando blocos de pensamento

Durante o uso de ferramentas, você deve passar blocos thinking de volta para a API, e você deve incluir o bloco completo e não modificado de volta para a API. Isso é crítico para manter o fluxo de raciocínio do modelo e a integridade da conversa.

Quando Claude invoca ferramentas, está pausando sua construção de uma resposta para aguardar informações externas. Quando os resultados das ferramentas são retornados, Claude continua construindo essa resposta existente. Isso necessita preservar blocos de pensamento durante o uso de ferramentas, por alguns motivos:

1. Continuidade de raciocínio: Os blocos de pensamento capturam o raciocínio passo a passo de Claude que levou aos pedidos de ferramentas. Quando você publica resultados de ferramentas, incluir o pensamento original garante que Claude possa continuar seu raciocínio de onde parou.

2. Manutenção de contexto: Embora os resultados das ferramentas apareçam como mensagens do usuário na estrutura da API, eles fazem parte de um fluxo de raciocínio contínuo. Preservar blocos de pensamento mantém esse fluxo conceitual em múltiplas chamadas de API. Para mais informações sobre gerenciamento de contexto, consulte o guia sobre janelas de contexto.

Importante: Ao fornecer blocos thinking, a sequência completa de blocos thinking consecutivos deve corresponder aos resultados gerados pelo modelo durante a solicitação original; você não pode reorganizar ou modificar a sequência desses blocos.

Pensamento intercalado

Extended thinking com uso de ferramentas em modelos Claude 4 suporta pensamento intercalado, que permite que Claude pense entre chamadas de ferramentas e faça raciocínio mais sofisticado após receber resultados de ferramentas.

Com pensamento intercalado, Claude pode:

• Raciocinar sobre os resultados de uma chamada de ferramenta antes de decidir o que fazer a seguir
• Encadear múltiplas chamadas de ferramentas com etapas de raciocínio entre elas
• Tomar decisões mais nuançadas com base em resultados intermediários

Suporte de modelo:

• Claude Mythos Preview: O pensamento intercalado acontece automaticamente. Cada etapa de raciocínio inter-ferramenta se move para um bloco de pensamento em vez de texto simples, e blocos de pensamento são preservados entre turnos por padrão. Nenhum cabeçalho beta é necessário ou suportado.
• Claude Opus 4.6: O pensamento intercalado é ativado automaticamente ao usar pensamento adaptativo. Nenhum cabeçalho beta é necessário. O cabeçalho beta interleaved-thinking-2025-05-14 é descontinuado no Opus 4.6 e é seguramente ignorado se incluído.
• Claude Sonnet 4.6: O pensamento intercalado é ativado automaticamente ao usar pensamento adaptativo (recomendado). O cabeçalho beta interleaved-thinking-2025-05-14 com pensamento estendido manual (thinking: {type: "enabled"}) ainda é funcional mas descontinuado.
• Outros modelos Claude 4 (Opus 4.5, Opus 4.1, Opus 4, Sonnet 4.5, Sonnet 4): Adicione o cabeçalho beta interleaved-thinking-2025-05-14 à sua solicitação de API para ativar o pensamento intercalado.

Aqui estão algumas considerações importantes para pensamento intercalado:

• Com pensamento intercalado, o budget_tokens pode exceder o parâmetro max_tokens, pois representa o orçamento total em todos os blocos de pensamento dentro de um turno do assistente.
• O pensamento intercalado é suportado apenas para ferramentas usadas via Messages API.
• Chamadas diretas para a API Claude permitem que você passe interleaved-thinking-2025-05-14 em solicitações para qualquer modelo, sem efeito (exceto Opus 4.6, onde é descontinuado e seguramente ignorado).
• Em plataformas de terceiros (por exemplo, Amazon Bedrock e Vertex AI), se você passar interleaved-thinking-2025-05-14 para qualquer modelo além de Claude Sonnet 4.6, Claude Opus 4.5, Claude Opus 4.1, Opus 4, Sonnet 4.5, ou Sonnet 4, sua solicitação falhará.

Pensamento estendido com cache de prompt

Cache de prompt com pensamento tem várias considerações importantes:

Remoção de contexto de bloco de pensamento

• Blocos de pensamento de turnos anteriores são removidos do contexto, o que pode afetar pontos de quebra de cache
• Ao continuar conversas com uso de ferramentas, blocos de pensamento são armazenados em cache e contam como tokens de entrada quando lidos do cache
• Isso cria uma compensação: enquanto blocos de pensamento não consomem espaço de janela de contexto visualmente, eles ainda contam para seu uso de tokens de entrada quando armazenados em cache
• Se o pensamento ficar desabilitado e você passar conteúdo de pensamento no turno atual de uso de ferramentas, o conteúdo de pensamento será removido e o pensamento permanecerá desabilitado para essa solicitação

Padrões de invalidação de cache

• Alterações nos parâmetros de pensamento (habilitado/desabilitado ou alocação de orçamento) invalidam pontos de quebra de cache de mensagem
• Pensamento intercalado amplifica a invalidação de cache, pois blocos de pensamento podem ocorrer entre múltiplas chamadas de ferramentas
• Prompts de sistema e ferramentas permanecem em cache apesar de alterações de parâmetros de pensamento ou remoção de bloco

Compreendendo o comportamento do cache de blocos de pensamento

Ao usar pensamento estendido com uso de ferramentas, os blocos de pensamento exibem um comportamento de cache específico que afeta a contagem de tokens:

Como funciona:

1. O cache ocorre apenas quando você faz uma solicitação subsequente que inclui resultados de ferramentas
2. Quando a solicitação subsequente é feita, o histórico de conversa anterior (incluindo blocos de pensamento) pode ser armazenado em cache
3. Esses blocos de pensamento em cache contam como tokens de entrada em suas métricas de uso quando lidos do cache
4. Quando um bloco de usuário que não é resultado de ferramenta é incluído, todos os blocos de pensamento anteriores são ignorados e removidos do contexto

Fluxo de exemplo detalhado:

Solicitação 1:

User: "What's the weather in Paris?"

Resposta 1:

[thinking_block_1] + [tool_use block 1]

Solicitação 2:

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True]

Resposta 2:

[thinking_block_2] + [text block 2]

A Solicitação 2 escreve um cache do conteúdo da solicitação (não da resposta). O cache inclui a mensagem de usuário original, o primeiro bloco de pensamento, bloco de uso de ferramenta e o resultado da ferramenta.

Solicitação 3:

User: ["What's the weather in Paris?"],
Assistant: [thinking_block_1] + [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [thinking_block_2] + [text block 2],
User: [Text response, cache=True]

Para Claude Opus 4.5 e posterior (incluindo Claude Opus 4.6), todos os blocos de pensamento anteriores são mantidos por padrão. Para modelos mais antigos, porque um bloco de usuário que não é resultado de ferramenta foi incluído, todos os blocos de pensamento anteriores são ignorados. Esta solicitação será processada da mesma forma que:

User: ["What's the weather in Paris?"],
Assistant: [tool_use block 1],
User: [tool_result_1, cache=True],
Assistant: [text block 2],
User: [Text response, cache=True]

Pontos-chave:

• Este comportamento de cache acontece automaticamente, mesmo sem marcadores explícitos de cache_control
• Este comportamento é consistente se usar pensamento regular ou pensamento intercalado

Máximo de tokens e tamanho da janela de contexto com pensamento estendido

Em modelos Claude mais antigos (anteriores ao Claude Sonnet 3.7), se a soma de tokens de prompt e max_tokens excedesse a janela de contexto do modelo, o sistema ajustaria automaticamente max_tokens para se adequar ao limite de contexto. Isso significava que você poderia definir um grande valor de max_tokens e o sistema o reduziria silenciosamente conforme necessário.

Com os modelos Claude 3.7 e 4, max_tokens (que inclui seu orçamento de pensamento quando o pensamento está ativado) é aplicado como um limite rigoroso. O sistema agora retornará um erro de validação se tokens de prompt + max_tokens exceder o tamanho da janela de contexto.

A janela de contexto com pensamento estendido

Ao calcular o uso da janela de contexto com pensamento ativado, há algumas considerações a serem observadas:

• Blocos de pensamento de turnos anteriores são removidos e não contam para sua janela de contexto
• O pensamento do turno atual conta para seu limite de max_tokens para esse turno

O diagrama abaixo demonstra o gerenciamento especializado de tokens quando o pensamento estendido está ativado:

A janela de contexto efetiva é calculada como:

context window =
  (current input tokens - previous thinking tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

Use a API de contagem de tokens para obter contagens de tokens precisas para seu caso de uso específico, especialmente ao trabalhar com conversas multi-turno que incluem pensamento.

A janela de contexto com pensamento estendido e uso de ferramentas

Ao usar pensamento estendido com uso de ferramentas, blocos de pensamento devem ser explicitamente preservados e retornados com os resultados das ferramentas.

O cálculo da janela de contexto efetiva para pensamento estendido com uso de ferramentas se torna:

context window =
  (current input tokens + previous thinking tokens + tool use tokens) +
  (thinking tokens + encrypted thinking tokens + text output tokens)

O diagrama abaixo ilustra o gerenciamento de tokens para pensamento estendido com uso de ferramentas:

Gerenciando tokens com pensamento estendido

Dado o comportamento da janela de contexto e max_tokens com pensamento estendido nos modelos Claude 3.7 e 4, você pode precisar:

• Monitorar e gerenciar mais ativamente seu uso de tokens
• Ajustar valores de max_tokens conforme o comprimento do seu prompt muda
• Potencialmente usar os endpoints de contagem de tokens com mais frequência
• Estar ciente de que blocos de pensamento anteriores não se acumulam em sua janela de contexto

Essa mudança foi feita para fornecer um comportamento mais previsível e transparente, especialmente conforme os limites de token máximo aumentaram significativamente.

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.

Blocos de pensamento redatados

Além dos blocos thinking regulares, a API pode retornar blocos redacted_thinking. Um bloco redacted_thinking contém conteúdo de pensamento criptografado em um campo data, sem nenhum resumo legível:

{
  "type": "redacted_thinking",
  "data": "..."
}

O campo data é opaco e criptografado. Como o campo signature em blocos de pensamento regulares, você deve passar blocos redacted_thinking de volta para a API inalterados ao continuar uma conversa multi-turno com ferramentas.

Diferenças no pensamento entre versões de modelo

A API de Mensagens lida com pensamento de forma diferente entre os modelos Claude Sonnet 3.7 e Claude 4, principalmente no comportamento de resumo.

Veja a tabela abaixo para uma comparação condensada:

Preservação de bloco de pensamento em Claude Opus 4.5 e posterior

A partir do Claude Opus 4.5 (e continuando no Claude Opus 4.6), blocos de pensamento de turnos anteriores do assistente são preservados no contexto do modelo por padrão. Isso difere dos modelos anteriores, que removem blocos de pensamento de turnos anteriores.

Benefícios da preservação de blocos de pensamento:

• Otimização de cache: Ao usar uso de ferramentas, blocos de pensamento preservados permitem acertos de cache, pois são passados de volta com resultados de ferramentas e armazenados em cache incrementalmente entre o turno do assistente, resultando em economia de tokens em fluxos de trabalho multi-etapas
• Sem impacto na inteligência: Preservar blocos de pensamento não tem efeito negativo no desempenho do modelo

Considerações importantes:

• Uso de contexto: Conversas longas consumirão mais espaço de contexto, pois blocos de pensamento são retidos no contexto
• Comportamento automático: Este é o comportamento padrão para Claude Opus 4.5 e modelos posteriores (incluindo Claude Mythos Preview e Claude Opus 4.6). Nenhuma alteração de código ou cabeçalho beta necessário
• Compatibilidade com versões anteriores: Para aproveitar esse recurso, continue passando blocos de pensamento completos e não modificados de volta para a API como você faria para uso de ferramentas

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 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)

Melhores práticas e considerações para pensamento estendido

Trabalhando com orçamentos de pensamento

• Otimização de orçamento: O orçamento mínimo é de 1.024 tokens. Comece no mínimo e aumente o orçamento de pensamento incrementalmente para encontrar o intervalo ideal para seu caso de uso. Contagens de tokens mais altas permitem raciocínio mais abrangente, mas com retornos decrescentes dependendo da tarefa. Aumentar o orçamento pode melhorar a qualidade da resposta em troca de latência aumentada. Para tarefas críticas, teste diferentes configurações para encontrar o equilíbrio ideal. Observe que o orçamento de pensamento é um alvo em vez de um limite rigoroso. O uso real de tokens pode variar com base na tarefa.
• Pontos de partida: Comece com orçamentos de pensamento maiores (16k+ tokens) para tarefas complexas e ajuste com base em suas necessidades.
• Orçamentos grandes: Para orçamentos de pensamento acima de 32k, use processamento em lote para evitar problemas de rede. Solicitações que empurram o modelo para pensar acima de 32k tokens causam solicitações de longa duração que podem atingir limites de tempo limite do sistema e limites de conexão aberta.
• Rastreamento de uso de tokens: Monitore o uso de tokens de pensamento para otimizar custos e desempenho.

Considerações de desempenho

• Tempos de resposta: Esteja preparado para tempos de resposta mais longos devido ao processamento adicional. Gerar blocos de pensamento aumenta o tempo de resposta geral.
• Requisitos de streaming: Os SDKs exigem streaming quando max_tokens é maior que 21.333 para evitar timeouts HTTP em solicitações de longa duração. Esta é uma validação do lado do cliente, não uma restrição da API. Se você não precisar processar eventos incrementalmente, use .stream() com .get_final_message() (Python) ou .finalMessage() (TypeScript) para obter o objeto Message completo sem lidar com eventos individuais. Veja Streaming de Mensagens para detalhes. Ao fazer streaming, esteja preparado para lidar com blocos de conteúdo de pensamento e texto conforme chegam.
• Omitindo pensamento para latência: Se seu aplicativo não exibir conteúdo de pensamento, defina display: "omitted" na configuração de pensamento para reduzir o tempo até o primeiro token de texto. Veja Controlando a exibição de pensamento.

Compatibilidade de recursos

• Pensamento não é compatível com modificações de temperature ou top_k, bem como uso forçado de ferramentas.
• Quando o pensamento está ativado, você pode definir top_p para valores entre 1 e 0,95.
• Você não pode pré-preenchimento de respostas quando o pensamento está ativado.
• Alterações no orçamento de pensamento invalidam prefixos de prompt em cache que incluem mensagens. No entanto, prompts de sistema em cache e definições de ferramentas continuarão funcionando quando os parâmetros de pensamento mudarem.

Diretrizes de uso

• Seleção de tarefa: Use pensamento estendido para tarefas particularmente complexas que se beneficiam de raciocínio passo a passo, como matemática, codificação e análise.
• Manipulação de contexto: Você não precisa remover blocos de pensamento anteriores você mesmo. A API Claude automaticamente ignora blocos de pensamento de turnos anteriores e eles não são incluídos ao calcular o uso de contexto.
• Engenharia de prompt: Revise as dicas de prompt de pensamento estendido se você quiser maximizar as capacidades de pensamento do Claude.

Próximas etapas