O pensamento 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.
O pensamento estendido é suportado nos seguintes modelos:
claude-sonnet-4-5-20250929)claude-sonnet-4-20250514)claude-3-7-sonnet-20250219) (descontinuado)claude-haiku-4-5-20251001)claude-opus-4-5-20251101)claude-opus-4-1-20250805)claude-opus-4-20250514)O comportamento da API difere entre os modelos Claude Sonnet 3.7 e Claude 4, mas as formas da API permanecem exatamente as mesmas.
Para mais informações, consulte Diferenças no pensamento entre versões de modelos.
Quando o pensamento estendido é ativado, Claude cria blocos de conteúdo thinking onde produz seu raciocínio interno. Claude incorpora insights deste raciocínio antes de elaborar uma resposta final.
A resposta da API incluirá 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 pensamento estendido, consulte a Referência da API de Mensagens.
Aqui está um exemplo de uso do pensamento estendido na API de Mensagens:
Para ativar o pensamento 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 pensamento estendido.
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, este limite se aplica aos tokens de pensamento completo, e não à saída resumida. Orçamentos maiores podem melhorar a qualidade da resposta ao permitir 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 pensamento intercalado com ferramentas, você pode exceder este limite, pois o limite de token se torna sua janela de contexto inteira (200k tokens).
Com o pensamento estendido ativado, a API de Mensagens para modelos Claude 4 retorna um resumo do processo de pensamento completo de Claude. O pensamento resumido fornece os benefícios completos de inteligência do pensamento estendido, enquanto previne abuso.
Aqui estão algumas considerações importantes para pensamento resumido:
Claude Sonnet 3.7 continua retornando saída de pensamento completo.
Em casos raros onde você precisa de acesso à saída de pensamento completo para modelos Claude 4, entre em contato com nossa equipe de vendas.
Você pode fazer streaming de respostas de pensamento estendido usando eventos enviados pelo servidor (SSE).
Quando o streaming está ativado para pensamento estendido, você recebe conteúdo de pensamento via eventos thinking_delta.
Para mais documentação sobre streaming via API de Mensagens, consulte Streaming de Mensagens.
Aqui está como lidar com streaming com pensamento:
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-5", "stop_reason": null, "stop_sequence": null}}
event: content_block_start
data: {"type": "content_block_start", "index": 0, "content_block": {"type": "thinking", "thinking": ""}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}
event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}
// 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": "27 * 453 = 12,231"}}
// 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"}Ao usar streaming com pensamento ativado, você pode notar que o texto às vezes chega em pedaços maiores alternando com entrega token por token. Este é o comportamento esperado, especialmente para conteúdo de pensamento.
O sistema de streaming precisa processar conteúdo em lotes para desempenho ideal, o que pode resultar neste padrão de entrega "em pedaços", com possíveis atrasos entre eventos de streaming. Estamos continuamente trabalhando para melhorar esta experiência, com futuras atualizações focadas em fazer o conteúdo de pensamento fazer streaming mais suavemente.
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:
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 estas opções forçam o uso de ferramentas, que é incompatível com pensamento estendido.
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 não modificado de volta para a API para manter a continuidade de raciocínio.
Você não pode alternar pensamento no meio de um turno do assistente, incluindo durante loops de uso de ferramentas. O turno inteiro do assistente deve operar em um único modo 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 é toda 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 da API, o loop de uso de ferramentas é conceitualmente parte de uma resposta contínua do assistente.
Você pode encontrar este erro:
Expected `thinking` or `redacted_thinking`, but found `tool_use`.
When `thinking` is enabled, a final `assistant` message must start
with a thinking block (preceding the lastmost set of `tool_use` and
`tool_result` blocks).Isto tipicamente ocorre quando:
✗ Inválido: Alternando pensamento imediatamente após uso de ferramentas
User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
// Cannot enable thinking here - still in the same assistant turn✓ Válido: Complete o turno do assistente primeiro
User: "What's the weather?"
Assistant: [tool_use] (thinking disabled)
User: [tool_result]
Assistant: [text: "It's sunny"]
User: "What about tomorrow?" (thinking disabled)
Assistant: [thinking] + [text: "..."] (thinking enabled - new turn)Melhor prática: Planeje sua estratégia de pensamento no início de cada turno em vez de tentar alternar no meio do turno.
Alternar modos de pensamento também invalida o cache de prompt para histórico de mensagens. Para mais detalhes, consulte a seção Pensamento estendido com cache de prompt.
Durante o uso de ferramentas, você deve passar blocos thinking de volta para a API, e você deve incluir o bloco completo não modificado de volta para a API. Isto é crítico para manter o fluxo de raciocínio do modelo e a integridade da conversa.
Embora você possa omitir blocos thinking de turnos anteriores do assistant, sugerimos sempre passar de volta todos os blocos de pensamento para a API para qualquer conversa multi-turno. A API irá:
Ao alternar modos de pensamento durante uma conversa, lembre-se que o turno inteiro do assistente (incluindo loops de uso de ferramentas) deve operar em um único modo de pensamento. Para mais detalhes, consulte Alternando modos de pensamento em conversas.
Quando Claude invoca ferramentas, está pausando sua construção de uma resposta para aguardar informações externas. Quando resultados de ferramentas são retornados, Claude continuará construindo essa resposta existente. Isto necessita preservar blocos de pensamento durante o uso de ferramentas, por um par de razões:
Continuidade de raciocínio: Os blocos de pensamento capturam o raciocínio passo a passo de Claude que levou a solicitações de ferramentas. Quando você publica resultados de ferramentas, incluir o pensamento original garante que Claude possa continuar seu raciocínio de onde parou.
Manutenção de contexto: Embora resultados de ferramentas apareçam como mensagens de usuário na estrutura da API, eles fazem parte de um fluxo de raciocínio contínuo. Preservar blocos de pensamento mantém este fluxo conceitual através de múltiplas chamadas de API. Para mais informações sobre gerenciamento de contexto, consulte nosso guia sobre janelas de contexto.
Importante: Ao fornecer blocos thinking, a sequência inteira 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 destes blocos.
O pensamento estendido com uso de ferramentas em modelos Claude 4 suporta pensamento intercalado, que permite que Claude pense entre chamadas de ferramentas e faça raciocínios mais sofisticados após receber resultados de ferramentas.
Com pensamento intercalado, Claude pode:
Para ativar o pensamento intercalado, adicione o cabeçalho beta interleaved-thinking-2025-05-14 à sua solicitação de API.
Aqui estão algumas considerações importantes para pensamento intercalado:
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.interleaved-thinking-2025-05-14.interleaved-thinking-2025-05-14 em solicitações para qualquer modelo, sem efeito.interleaved-thinking-2025-05-14 para qualquer modelo além de Claude Opus 4.5, Claude Opus 4.1, Opus 4 ou Sonnet 4, sua solicitação falhará.Cache de prompt com pensamento tem várias considerações importantes:
Tarefas de pensamento estendido geralmente levam mais de 5 minutos para serem concluídas. Considere usar a duração de cache de 1 hora para manter acertos de cache em sessões de pensamento mais longas e fluxos de trabalho com múltiplas etapas.
Remoção de contexto de bloco de pensamento
Padrões de invalidação de cache
Embora blocos de pensamento sejam removidos para cache e cálculos de contexto, eles devem ser preservados ao continuar conversas com uso de ferramentas, especialmente com pensamento intercalado.
Ao usar pensamento estendido com uso de ferramentas, blocos de pensamento exibem comportamento de cache específico que afeta a contagem de tokens:
Como funciona:
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, todos os blocos de pensamento anteriores são mantidos por padrão. Para modelos mais antigos, como um bloco de usuário de resultado não-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:
cache_control explícitosEm 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 caber dentro do 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 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.
Você pode ler nosso guia sobre janelas de contexto para uma análise mais profunda.
Ao calcular o uso da janela de contexto com pensamento ativado, há algumas considerações a serem observadas:
max_tokens para esse turnoO 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)Recomendamos usar a API de contagem de tokens para obter contagens de tokens precisas para seu caso de uso específico, especialmente ao trabalhar com conversas com múltiplos turnos que incluem pensamento.
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 efetivo da janela de contexto 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:
Dado o comportamento da janela de contexto e max_tokens com pensamento estendido em modelos Claude 3.7 e 4, você pode precisar:
max_tokens conforme o comprimento do seu prompt mudaEsta mudança foi feita para fornecer comportamento mais previsível e transparente, especialmente conforme os limites de tokens máximos aumentaram significativamente.
O conteúdo completo do pensamento é criptografado e retornado no campo signature. Este campo é usado para verificar que blocos de pensamento foram gerados por Claude quando passados de volta para a API.
É apenas estritamente necessário enviar de volta blocos de pensamento ao usar ferramentas com pensamento estendido. Caso contrário, você pode omitir blocos de pensamento de turnos anteriores, ou deixar a API removê-los para você se você os passar de volta.
Se enviar de volta blocos de pensamento, recomendamos passar tudo de volta como você recebeu para consistência e para evitar possíveis problemas.
Aqui estão algumas considerações importantes sobre criptografia de pensamento:
signature_delta dentro de um evento content_block_delta logo antes do evento content_block_stop.signature são significativamente mais longos em modelos Claude 4 do que em modelos anteriores.signature é um campo opaco e não deve ser interpretado ou analisado - ele existe apenas para fins de verificação.signature são compatíveis entre plataformas (Claude APIs, Amazon Bedrock e Vertex AI). Valores gerados em uma plataforma serão compatíveis com outra.Ocasionalmente, o raciocínio interno de Claude será sinalizado por nossos sistemas de segurança. Quando isso ocorre, criptografamos parte ou todo o bloco thinking e o retornamos como um bloco redacted_thinking. Os blocos redacted_thinking são descriptografados quando passados de volta para a API, permitindo que Claude continue sua resposta sem perder contexto.
Ao construir aplicações voltadas para o cliente que usam pensamento estendido:
Aqui está um exemplo mostrando blocos de pensamento normais e redatados:
{
"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..."
}
]
}Ver blocos de pensamento redatado em sua saída é um comportamento esperado. O modelo ainda pode usar esse raciocínio redatado para informar suas respostas enquanto mantém proteções de segurança.
Se você precisar testar o tratamento de pensamento redatado em sua aplicação, você pode usar esta string de teste especial como seu prompt: ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB
Ao passar blocos thinking e redacted_thinking de volta para a API em uma conversa com múltiplos turnos, você deve incluir o bloco completo e não modificado de volta para a API para o último turno do assistente. Isso é crítico para manter o fluxo de raciocínio do modelo. Sugerimos sempre passar todos os blocos de pensamento de volta para a API. Para mais detalhes, consulte a seção Preservando blocos de pensamento acima.
A API de Mensagens lida com pensamento de forma diferente entre os modelos Claude Sonnet 3.7 e Claude 4, principalmente no comportamento de redação e sumarização.
Veja a tabela abaixo para uma comparação condensada:
| Recurso | Claude Sonnet 3.7 | Modelos Claude 4 (pré-Opus 4.5) | Claude Opus 4.5 e posterior |
|---|---|---|---|
| Saída de Pensamento | Retorna saída de pensamento completa | Retorna pensamento sumarizado | Retorna pensamento sumarizado |
| Pensamento Intercalado | Não suportado | Suportado com cabeçalho beta interleaved-thinking-2025-05-14 | Suportado com cabeçalho beta interleaved-thinking-2025-05-14 |
| Preservação de Bloco de Pensamento | Não preservado entre turnos | Não preservado entre turnos | Preservado por padrão (habilita otimização de cache, economia de tokens) |
Claude Opus 4.5 introduz um novo comportamento padrão: 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:
Considerações importantes:
Para modelos anteriores (Claude Sonnet 4.5, Opus 4.1, etc.), blocos de pensamento de turnos anteriores continuam sendo removidos do contexto. O comportamento existente descrito na seção Pensamento estendido com cache de prompt se aplica a esses modelos.
Para informações completas de preços, incluindo taxas base, gravações de cache, acertos de cache e tokens de saída, consulte a página de preços.
O processo de pensamento incorre em cobranças por:
Quando o pensamento estendido está habilitado, um prompt de sistema especializado é automaticamente incluído para suportar este recurso.
Ao usar pensamento sumarizado:
A contagem de tokens de saída cobrada não corresponderá à contagem de tokens visível na resposta. Você é cobrado pelo processo de pensamento completo, não pelo resumo que você vê.
max_tokens é maior que 21.333. Ao fazer streaming, esteja preparado para lidar com blocos de conteúdo de pensamento e texto conforme chegam.temperature ou top_k, bem como uso forçado de ferramenta.top_p para valores entre 1 e 0,95.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-5",
"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?"
}
]
}'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-5",
"max_tokens": 16000,
"stream": true,
"thinking": {
"type": "enabled",
"budget_tokens": 10000
},
"messages": [
{
"role": "user",
"content": "What is 27 * 453?"
}
]
}'Explore exemplos práticos de pensamento em nosso livro de receitas.