--- title: Pensamento url: https://platform.claude.com/docs/pt-BR/build-with-claude/thinking description: "Entenda como o pensamento do Claude funciona: ative-o, leia a saída de pensamento, ajuste a profundidade do pensamento com o esforço e use o pensamento com ferramentas, cache e streaming." --- Para saber como a "zero data retention" (retenção zero de dados), ou ZDR, se aplica a este recurso, consulte [API e retenção de dados](https://platform.claude.com/docs/pt-BR/manage-claude/api-and-data-retention). Um modelo que responde em uma única passagem precisa acertar tudo na primeira tentativa: sem rascunho, sem verificação, sem mudar de rumo no meio do caminho. Para uma prova, um bug complicado ou uma tarefa agêntica longa, a primeira abordagem muitas vezes não é a melhor. O pensamento remove essa restrição. Quando o pensamento está ativo, o Claude trabalha o problema com suas próprias palavras antes de responder: ele reformula o que está sendo pedido, testa abordagens, verifica resultados intermediários e abandona caminhos que não se sustentam. Esse pensamento antecipado chega em blocos de conteúdo `thinking` antes da resposta, e o Claude se baseia nele para produzir a resposta final. É por isso que o pensamento melhora o desempenho em tarefas complexas como matemática, programação, análise e trabalho agêntico de longa duração, em que a qualidade da resposta depende de um trabalho intermediário que, de outra forma, seria comprimido na própria resposta ou ignorado. O pensamento tem um custo: os tokens que o Claude gasta raciocinando são cobrados como tokens de saída, mesmo quando o texto do pensamento não é retornado para você, e eles contam para o `max_tokens` junto com o texto da resposta. Esta página aborda como o pensamento se comporta em toda a superfície da API: como ativá-lo, como ler sua saída e como gerenciar suas interações com ferramentas, "streaming", "prompt caching" (cache de prompt) e a "context window" (janela de contexto). ## Como o pensamento funciona ![Diagrama: o Claude determina se deve pensar antecipadamente, pode pensar entre chamadas de ferramentas e retorna "thinking blocks" (blocos de pensamento) antes do texto](https://platform.claude.com/docs/pt-BR/images/how-thinking-works.svg) Se o Claude pensa em uma determinada solicitação, e com que profundidade, depende da sua configuração de pensamento e da complexidade da solicitação. Veja como o pensamento antecipado aparece em uma resposta: um ou mais blocos de conteúdo `thinking` chegam antes dos blocos `text`. O bloco de pensamento ainda é conteúdo gerado, como o bloco `text` que o segue, mas fica separado da resposta canônica. Cada bloco de pensamento também carrega um campo `signature`, uma cópia criptografada do raciocínio completo que você devolve sem alterações em conversas de múltiplos turnos e com uso de ferramentas (consulte [Criptografia do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-encryption)): ```json { "content": [ { "type": "thinking", "thinking": "Let me break this down. The question has two parts, so I'll start with the simpler one and use its result to constrain the second...", "signature": "WaUjzkypQ2mUEVM36O2Txu...." }, { "type": "text", "text": "Based on my analysis..." } ] } ``` Você nem sempre vê esse texto, e o que você vê nunca é a cadeia de pensamento bruta: o texto em um bloco de pensamento é um [resumo do raciocínio do Claude](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#summarized-thinking). O campo `display` na configuração de pensamento controla se esse resumo é retornado: `"summarized"` o retorna, enquanto `"omitted"`, o padrão em muitos modelos, retorna blocos de pensamento com um campo `thinking` vazio. De qualquer forma, o bloco é cobrado da mesma maneira e devolvido da mesma maneira em conversas de múltiplos turnos. Consulte [Controlando a exibição do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#controlling-thinking-display) para ver os padrões e detalhes por modelo. Se o Claude usar ferramentas, o pensamento também pode aparecer entre chamadas de ferramentas. Consulte [Pensamento com uso de ferramentas](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-with-tool-use). Para o formato completo da resposta, consulte a [referência da Messages API](https://platform.claude.com/docs/pt-BR/api/messages/create). ## Configurando o pensamento Na maioria dos modelos, o pensamento está ativado por padrão ou a um parâmetro de distância. A tabela a seguir mostra o que cada modelo faz com cada valor de `thinking` que uma solicitação pode enviar. Um erro 400 significa que a API rejeita a solicitação, e [Solução de problemas do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting) apresenta cada erro e sua correção. | Modelo | Sem campo `thinking` | `"adaptive"` | `"enabled"` com `budget_tokens` | `"between_tools"` | `"disabled"` | | --------------------- | --------------------- | --------------------- | ------------------------------------ | --------------------------------------------------------------- | ---------------------------------------------------- | | Claude Opus 5.5 | Pensamento adaptativo | Pensamento adaptativo | Erro 400 | Erro 400 | Erro 400 | | Claude Sonnet 5.5 | Pensamento adaptativo | Pensamento adaptativo | Erro 400 | Pensamento antecipado desativado com esforço `high` ou inferior | Erro 400 | | Claude Haiku 5.5 | Pensamento adaptativo | Pensamento adaptativo | Erro 400 | Erro 400 | Pensamento desativado com esforço `high` ou inferior | | Claude Fable 5.1 | Pensamento adaptativo | Pensamento adaptativo | Erro 400 | Erro 400 | Erro 400 | | Claude Mythos 5.1 | Pensamento adaptativo | Pensamento adaptativo | Erro 400 | Erro 400 | Erro 400 | | Claude Fable 5 | Pensamento adaptativo | Pensamento adaptativo | Erro 400 | Erro 400 | Erro 400 | | Claude Mythos 5 | Pensamento adaptativo | Pensamento adaptativo | Erro 400 | Erro 400 | Erro 400 | | Claude Opus 5 | Pensamento adaptativo | Pensamento adaptativo | Erro 400 | Erro 400 | Pensamento desativado com esforço `high` ou inferior | | Claude Sonnet 5 | Pensamento adaptativo | Pensamento adaptativo | Erro 400 | Erro 400 | Pensamento desativado | | Claude Opus 4.8 | Pensamento desativado | Pensamento adaptativo | Erro 400 | Erro 400 | Pensamento desativado | | Claude Opus 4.7 | Pensamento desativado | Pensamento adaptativo | Erro 400 | Erro 400 | Pensamento desativado | | Claude Mythos Preview | Pensamento adaptativo | Pensamento adaptativo | Pensamento estendido | Erro 400 | Erro 400 | | Claude Opus 4.6 | Pensamento desativado | Pensamento adaptativo | Pensamento estendido (descontinuado) | Erro 400 | Pensamento desativado | | Claude Sonnet 4.6 | Pensamento desativado | Pensamento adaptativo | Pensamento estendido (descontinuado) | Erro 400 | Pensamento desativado | | Claude Opus 4.5 | Pensamento desativado | Erro 400 | Pensamento estendido | Erro 400 | Pensamento desativado | | Claude Sonnet 4.5 | Pensamento desativado | Erro 400 | Pensamento estendido | Erro 400 | Pensamento desativado | | Claude Haiku 4.5 | Pensamento desativado | Erro 400 | Pensamento estendido | Erro 400 | Pensamento desativado | Na tabela, "com esforço `high` ou inferior" significa que a solicitação funciona com esforço `low`, `medium` e `high` e retorna um erro 400 com `xhigh` ou `max`. No Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview e Claude Haiku 5.5, o pensamento já está ativado e não precisa de configuração. `display` tem como padrão `"omitted"` nesses modelos, então o texto do pensamento fica oculto até que você opte por exibi-lo. Opte por exibi-lo com `thinking: {"type": "adaptive", "display": "summarized"}`, como fazem os exemplos a seguir. No Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6 e Claude Sonnet 4.6, o pensamento fica desativado até que você defina `thinking: {type: "adaptive"}`, o que permite que o Claude determine quando e com que profundidade pensar com base na solicitação. A mesma solicitação, com a [string do modelo](https://platform.claude.com/docs/pt-BR/models/overview) trocada, o ativa nesses modelos. Os exemplos a seguir definem `display: "summarized"` para que o texto do pensamento fique visível e usam um `max_tokens` generoso: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 16000, "thinking": { "type": "adaptive", "display": "summarized" }, "messages": [ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?" } ] }' ``` ```bash CLI ant messages create \ --model claude-opus-5-5 \ --max-tokens 16000 \ --thinking '{type: adaptive, display: summarized}' \ --message '{role: user, content: "What is the greatest common divisor of 1071 and 462?"}' \ --transform content \ --format yaml ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-opus-5-5", max_tokens=16000, thinking={"type": "adaptive", "display": "summarized"}, messages=[ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?", } ], ) for block in response.content: match block.type: case "thinking": print(f"\nThinking: {block.thinking}") case "text": print(f"\nResponse: {block.text}") ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive", display: "summarized" }, messages: [ { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } ] }); for (const block of response.content) { switch (block.type) { case "thinking": console.log(`\nThinking: ${block.thinking}`); break; case "text": console.log(`\nResponse: ${block.text}`); break; } } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 16000, Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }, Messages = [ new() { Role = Role.User, Content = "What is the greatest common divisor of 1071 and 462?" } ] }; var message = await client.Messages.Create(parameters); foreach (var block in message.Content) { if (block.TryPickThinking(out ThinkingBlock? thinking)) { Console.WriteLine($"\nThinking: {thinking.Thinking}"); } else if (block.TryPickText(out TextBlock? text)) { Console.WriteLine($"\nResponse: {text.Text}"); } } ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 16000, Thinking: anthropic.ThinkingConfigParamUnion{ OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{ Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")), }, }) if err != nil { log.Fatal(err) } for _, block := range response.Content { switch v := block.AsAny().(type) { case anthropic.ThinkingBlock: fmt.Printf("\nThinking: %s", v.Thinking) case anthropic.TextBlock: fmt.Printf("\nResponse: %s", v.Text) } } ``` ```java Java import com.anthropic.models.messages.ThinkingConfigAdaptive; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(16000L) .thinking(ThinkingConfigAdaptive.builder() .display(ThinkingConfigAdaptive.Display.SUMMARIZED) .build()) .addUserMessage("What is the greatest common divisor of 1071 and 462?") .build(); Message response = client.messages().create(params); response.content().forEach(block -> { block.thinking().ifPresent(thinkingBlock -> IO.println("\nThinking: " + thinkingBlock.thinking()) ); block.text().ifPresent(textBlock -> IO.println("\nResponse: " + textBlock.text()) ); }); } ``` ```php PHP use Anthropic\Messages\TextBlock; use Anthropic\Messages\ThinkingBlock; $client = new Client(); $message = $client->messages->create( maxTokens: 16000, messages: [ [ 'role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?' ] ], model: 'claude-opus-5-5', thinking: ['type' => 'adaptive', 'display' => 'summarized'], ); foreach ($message->content as $block) { switch (true) { case $block instanceof ThinkingBlock: echo "\nThinking: " . $block->thinking; break; case $block instanceof TextBlock: echo "\nResponse: " . $block->text; break; } } ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive", # Um hash simples como este aceita display:. A classe tipada ThinkingConfigAdaptive # o escreve como display_ (com sublinhado no final) para não sombrear o Kernel#display do Ruby. # A requisição ainda envia display. display: "summarized" }, messages: [ { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } ] ) message.content.each do |block| case block when Anthropic::Models::ThinkingBlock puts "\nThinking: #{block.thinking}" when Anthropic::Models::TextBlock puts "\nResponse: #{block.text}" end end ``` Executar o exemplo imprime o pensamento resumido e, em seguida, a resposta: ```text Output wrap Thinking: Use Euclidean algorithm. 1071 = 2*462 + 147 462 = 3*147 + 21 147 = 7*21 + 0 GCD = 21 Response: ## Finding GCD of 1071 and 462 I'll use the **Euclidean algorithm**, repeatedly dividing and taking remainders... ``` Os tokens de pensamento contam para `max_tokens`, então defina-o alto o suficiente para deixar espaço tanto para o pensamento quanto para o texto da resposta. Consulte [Controle de custos](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost#cost-control) na página de direcionamento e [Pensamento e a janela de contexto](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-the-context-window). ### Desativando o pensamento No Claude Sonnet 5, em que o pensamento está ativado por padrão, você pode desativá-lo: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-sonnet-5", "max_tokens": 4096, "thinking": {"type": "disabled"}, "messages": [ { "role": "user", "content": "Summarize this article in one sentence." } ] }' ``` ```bash CLI ant messages create \ --model claude-sonnet-5 \ --max-tokens 4096 \ --thinking '{type: disabled}' \ --message '{role: user, content: "Summarize this article in one sentence."}' ``` ```python Python client = anthropic.Anthropic() response = client.messages.create( model="claude-sonnet-5", max_tokens=4096, thinking={"type": "disabled"}, messages=[{"role": "user", "content": "Summarize this article in one sentence."}], ) ``` ```typescript TypeScript const client = new Anthropic(); const response = await client.messages.create({ model: "claude-sonnet-5", max_tokens: 4096, thinking: { type: "disabled" }, messages: [{ role: "user", content: "Summarize this article in one sentence." }] }); ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeSonnet5, MaxTokens = 4096, Thinking = new ThinkingConfigDisabled(), Messages = [ new() { Role = Role.User, Content = "Summarize this article in one sentence." } ] }; var message = await client.Messages.Create(parameters); ``` ```go Go client := anthropic.NewClient() response, err := client.Messages.New(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeSonnet5, MaxTokens: 4096, Thinking: anthropic.ThinkingConfigParamUnion{ OfDisabled: &anthropic.ThinkingConfigDisabledParam{}, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("Summarize this article in one sentence.")), }, }) if err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.messages.ThinkingConfigDisabled; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_SONNET_5) .maxTokens(4096L) .thinking(ThinkingConfigDisabled.builder().build()) .addUserMessage("Summarize this article in one sentence.") .build(); Message response = client.messages().create(params); } ``` ```php PHP $client = new Client(); $message = $client->messages->create( maxTokens: 4096, messages: [ [ 'role' => 'user', 'content' => 'Summarize this article in one sentence.' ] ], model: 'claude-sonnet-5', thinking: ['type' => 'disabled'], ); ``` ```ruby Ruby client = Anthropic::Client.new message = client.messages.create( model: "claude-sonnet-5", max_tokens: 4096, thinking: { type: "disabled" }, messages: [ { role: "user", content: "Summarize this article in one sentence." } ] ) ``` O Claude Opus 5 também tem o pensamento ativado por padrão e aceita `thinking: {type: "disabled"}` com "[effort](https://platform.claude.com/docs/pt-BR/build-with-claude/effort)" (esforço) `high` ou inferior. Com esforço `xhigh` ou `max`, o pensamento não pode ser desativado: solicitações que combinam `thinking: {type: "disabled"}` com esses níveis de esforço retornam um erro 400. Essa restrição é aplicada em cada solicitação. Com o pensamento desativado, o Claude Opus 5 pode ocasionalmente emitir chamadas de ferramentas como texto simples ou incluir tags XML internas em sua saída visível. Consulte [Executando com o pensamento desativado](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5#running-with-thinking-disabled) para ver mitigações via prompt. O Claude Sonnet 5.5 também tem o pensamento ativado por padrão e rejeita `thinking: {type: "disabled"}` com um erro 400. Para desativar o pensamento antecipado, envie `thinking: {type: "between_tools"}` em vez disso. Essa é a configuração de pensamento mais baixa no Claude Sonnet 5.5 e é aceita com [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) `high` ou inferior. O modelo ainda retorna suas [atualizações de progresso entre chamadas de ferramentas](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#progress-updates). Sem ferramentas, a resposta contém apenas texto, como acontece com `disabled` no Claude Sonnet 5. Consulte [Executando sem pensamento antecipado](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#running-without-up-front-thinking) para orientações sobre prompts. O Claude Haiku 5.5 também tem o pensamento ativado por padrão e aceita `thinking: {type: "disabled"}` com [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) `high` ou inferior. Com esforço `xhigh` ou `max`, essa combinação retorna um erro 400. Para obter menos pensamento, reduza primeiro o nível de esforço. Com o pensamento desativado, o modelo pode pular uma chamada de ferramenta de que precisa quando você também solicita saída JSON. Um [`output_config.effort` por mensagem](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#change-effort-mid-conversation-beta) que difere do nível em vigor também retorna um erro 400 enquanto o pensamento está desativado. Consulte [Use o esforço para controlar o pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#use-effort-to-control-thinking) e [Use o pensamento adaptativo com saída JSON e suas próprias ferramentas](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-haiku-5-5#json-output-with-your-own-tools). Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5 e Claude Mythos Preview rejeitam `thinking: {type: "disabled"}`. O pensamento não pode ser desativado nesses modelos. Para verificar se um modelo aceita `"disabled"` antes de enviar uma solicitação, leia o valor `capabilities.thinking.types.disabled.supported` na Models API. [Usando a Models API](https://platform.claude.com/docs/pt-BR/models/overview#using-the-models-api) descreve o campo. Se o seu modelo oferece suporte apenas ao pensamento estendido (consulte a [tabela de configuração por modelo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#supported-models)), configure-o com `type: "enabled"` e um valor de `budget_tokens` em vez disso. A página [Pensamento estendido](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking) aborda essa configuração. E se qualquer configuração de pensamento retornar um erro 400, [Solução de problemas do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting) associa cada mensagem de erro à sua correção. ## Lendo a saída do pensamento ### Controlando a exibição do pensamento O campo `display` na configuração de pensamento controla como o conteúdo do pensamento é retornado nas respostas da API. `display` funciona em ambos os modos: defina-o junto com `type: "adaptive"` ou `type: "enabled"`. Ele aceita estes valores: * `"summarized"`: os blocos de pensamento contêm texto de [pensamento resumido](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#summarized-thinking), um resumo legível do raciocínio do Claude. Este é o padrão no Claude Opus 4.6, Claude Sonnet 4.6 e modelos anteriores. * `"omitted"`: os blocos de pensamento são retornados com um campo `thinking` vazio. O campo `signature` ainda carrega o pensamento completo criptografado para a continuidade em múltiplos turnos (consulte [Criptografia do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-encryption)). Este é o padrão no Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Opus 4.8, Claude Opus 4.7, [Claude Mythos Preview](https://anthropic.com/glasswing) e Claude Haiku 5.5. * `"updates"` (beta): os blocos de raciocínio são retornados com um campo `thinking` vazio, como em `"omitted"`, e as breves [atualizações de progresso](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#progress-updates) que alguns modelos escrevem entre chamadas de ferramentas retornam como texto legível. Requer o cabeçalho beta `thinking-display-updates-2026-08-18`. Defina `display: "omitted"` quando sua aplicação não exibe o conteúdo do pensamento aos usuários. O principal benefício é um tempo menor até o primeiro token de texto durante o streaming: o servidor pula totalmente o streaming dos tokens de pensamento e entrega apenas a assinatura, de modo que a resposta de texto final começa a ser transmitida mais cedo. Com `display: "omitted"`, a resposta contém blocos `thinking` com um campo `thinking` vazio: ```json Output { "content": [ { "type": "thinking", "thinking": "", "signature": "EosnCkYICxIMMb3LzNrMu..." }, { "type": "text", "text": "The answer is 12,231." } ] } ``` Tenha em mente o seguinte ao trabalhar com pensamento omitido: * Você ainda é cobrado pelos tokens de pensamento completos. Omitir reduz a "latency" (latência), não o custo. * Se você devolver blocos de pensamento em conversas de múltiplos turnos, devolva-os sem alterações. O servidor descriptografa a `signature` para reconstruir o pensamento original para a construção do prompt (consulte [Preservando blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserving-thinking-blocks)). Qualquer texto que você colocar no campo `thinking` de um bloco omitido devolvido é ignorado. * `display` é inválido com `thinking.type: "disabled"` (não há nada para exibir) e com `thinking.type: "between_tools"` (apenas Claude Sonnet 5.5), que não aceita nenhum outro campo. Com `between_tools`, as atualizações de progresso ainda retornam com texto de resumo, como acontece com `display: "updates"` (consulte [Atualizações de progresso](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#progress-updates)). * Ao usar `thinking.type: "adaptive"` e o modelo pular o pensamento em uma solicitação simples, nenhum bloco de pensamento é produzido, independentemente de `display`. * Ao fazer streaming com `display: "omitted"`, nenhum texto de pensamento é transmitido. Cada bloco de pensamento transmite um `thinking_delta` com uma string `thinking` vazia e, em seguida, seu `signature_delta`. Com `display: "updates"`, apenas os [blocos de atualização de progresso](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#progress-updates) transmitem eventos `thinking_delta` que carregam texto. Consulte [Streaming do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#streaming-thinking) para ver a sequência de eventos. O campo `signature` é idêntico qualquer que seja o valor de `display` que você definir. Alternar os valores de `display` entre turnos de uma conversa é suportado. ### Pensamento resumido Quando `display` é `"summarized"`, o texto de pensamento que você recebe é um resumo do processo de pensamento completo do Claude, e não a cadeia de pensamento bruta. O pensamento resumido oferece todos os benefícios de inteligência do pensamento, ao mesmo tempo em que evita usos indevidos. Nenhuma configuração de `display` retorna a cadeia de pensamento bruta. Tenha em mente o seguinte ao trabalhar com pensamento resumido: * Você é cobrado pelos tokens de pensamento completos gerados pela solicitação original, não pelos tokens do resumo. A contagem de tokens de saída cobrada não corresponde à contagem de tokens que você vê na resposta. * No Claude Opus 4.6, Claude Sonnet 4.6 e modelos anteriores, as primeiras linhas da saída de pensamento são mais detalhadas, fornecendo um raciocínio minucioso que é particularmente útil para fins de engenharia de prompt. O [Claude Mythos Preview](https://anthropic.com/glasswing) resume desde o primeiro token, então seus blocos de pensamento não mostram esse preâmbulo detalhado. * A sumarização preserva as ideias principais do processo de pensamento do Claude com latência adicional mínima, de modo que os resumos podem ser transmitidos à medida que chegam. * A sumarização é processada por um modelo diferente daquele que você usa em suas solicitações. O modelo que pensa não vê a saída resumida. * À medida que a Anthropic busca aprimorar o recurso de pensamento, o comportamento da sumarização está sujeito a alterações. Em casos raros em que você precise de acesso à saída de pensamento completa, [entre em contato com a equipe de vendas da Anthropic](mailto:sales@anthropic.com). Para ver o raciocínio do modelo, leia os blocos `thinking` em vez de pedir o raciocínio no texto da resposta. No Claude Fable 5.1, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5 e Claude Fable 5, uma solicitação que tente extrair o raciocínio interno do modelo como parte do texto da resposta pode ser recusada com `stop_details.category: "reasoning_extraction"`. Consulte [Categorias de recusa](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#refusal-response) para a referência do campo e [Mantenha o raciocínio nos blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#keep-reasoning-in-thinking-blocks) para saber o que pedir em vez disso. ### Streaming do pensamento O pensamento funciona com [streaming](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming). Os blocos de pensamento são transmitidos como eventos `thinking_delta` dentro de eventos `content_block_delta`, seguidos por um único evento `signature_delta` logo antes do `content_block_stop` do bloco. Os blocos de texto são transmitidos em seguida, como de costume. ![Diagrama da sequência de eventos de streaming com "thinking" (pensamento): o bloco de pensamento é aberto, os deltas de pensamento carregam texto apenas quando a configuração de exibição retorna texto (summarized, ou updates para blocos de atualização de progresso), um único delta de assinatura fecha o bloco e, em seguida, os deltas de texto são transmitidos](https://platform.claude.com/docs/pt-BR/images/how-thinking-streams.svg) Os exemplos a seguir transmitem uma resposta com pensamento adaptativo, imprimindo os deltas de pensamento e de texto à medida que chegam: ```bash cURL curl https://api.anthropic.com/v1/messages \ -H "x-api-key: $ANTHROPIC_API_KEY" \ -H "anthropic-version: 2023-06-01" \ -H "content-type: application/json" \ -d '{ "model": "claude-opus-5-5", "max_tokens": 16000, "stream": true, "thinking": { "type": "adaptive", "display": "summarized" }, "messages": [ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?" } ] }' ``` ```bash CLI ant messages create \ --model claude-opus-5-5 \ --max-tokens 16000 \ --thinking '{type: adaptive, display: summarized}' \ --message '{role: user, content: "What is the greatest common divisor of 1071 and 462?"}' \ --stream \ --format jsonl ``` ```python Python client = anthropic.Anthropic() with client.messages.stream( model="claude-opus-5-5", max_tokens=16000, thinking={"type": "adaptive", "display": "summarized"}, messages=[ { "role": "user", "content": "What is the greatest common divisor of 1071 and 462?", } ], ) as stream: for event in stream: match event.type: case "content_block_start": print(f"\nStarting {event.content_block.type} block...") case "content_block_delta": delta = event.delta match delta.type: case "thinking_delta": print(delta.thinking, end="", flush=True) case "text_delta": print(delta.text, end="", flush=True) ``` ```typescript TypeScript const client = new Anthropic(); const stream = client.messages.stream({ model: "claude-opus-5-5", max_tokens: 16000, thinking: { type: "adaptive", display: "summarized" }, messages: [{ role: "user", content: "What is the greatest common divisor of 1071 and 462?" }] }); for await (const event of stream) { switch (event.type) { case "content_block_start": console.log(`\nStarting ${event.content_block.type} block...`); break; case "content_block_delta": switch (event.delta.type) { case "thinking_delta": process.stdout.write(event.delta.thinking); break; case "text_delta": process.stdout.write(event.delta.text); break; } break; } } ``` ```csharp C# AnthropicClient client = new(); var parameters = new MessageCreateParams { Model = Model.ClaudeOpus5_5, MaxTokens = 16000, Thinking = new ThinkingConfigAdaptive { Display = Display.Summarized }, Messages = [new() { Role = Role.User, Content = "What is the greatest common divisor of 1071 and 462?" }] }; await foreach (var rawEvent in client.Messages.CreateStreaming(parameters)) { if (rawEvent.TryPickContentBlockStart(out var start)) { Console.WriteLine($"\nStarting {start.ContentBlock.Type} block..."); } else if (rawEvent.TryPickContentBlockDelta(out var delta)) { if (delta.Delta.TryPickThinking(out var thinkingDelta)) { Console.Write(thinkingDelta.Thinking); } else if (delta.Delta.TryPickText(out var textDelta)) { Console.Write(textDelta.Text); } } } ``` ```go Go client := anthropic.NewClient() stream := client.Messages.NewStreaming(context.TODO(), anthropic.MessageNewParams{ Model: anthropic.ModelClaudeOpus5_5, MaxTokens: 16000, Thinking: anthropic.ThinkingConfigParamUnion{ OfAdaptive: &anthropic.ThinkingConfigAdaptiveParam{ Display: anthropic.ThinkingConfigAdaptiveDisplaySummarized, }, }, Messages: []anthropic.MessageParam{ anthropic.NewUserMessage(anthropic.NewTextBlock("What is the greatest common divisor of 1071 and 462?")), }, }) for stream.Next() { event := stream.Current() switch eventVariant := event.AsAny().(type) { case anthropic.ContentBlockStartEvent: fmt.Printf("\nStarting %s block...\n", eventVariant.ContentBlock.Type) case anthropic.ContentBlockDeltaEvent: switch deltaVariant := eventVariant.Delta.AsAny().(type) { case anthropic.ThinkingDelta: fmt.Print(deltaVariant.Thinking) case anthropic.TextDelta: fmt.Print(deltaVariant.Text) } } } if err := stream.Err(); err != nil { log.Fatal(err) } ``` ```java Java import com.anthropic.models.messages.ThinkingConfigAdaptive; void main() { AnthropicClient client = AnthropicOkHttpClient.fromEnv(); MessageCreateParams params = MessageCreateParams.builder() .model(Model.CLAUDE_OPUS_5_5) .maxTokens(16000L) .thinking(ThinkingConfigAdaptive.builder() .display(ThinkingConfigAdaptive.Display.SUMMARIZED) .build()) .addUserMessage("What is the greatest common divisor of 1071 and 462?") .build(); try (var streamResponse = client.messages().createStreaming(params)) { streamResponse.stream().forEach(event -> { switch (event.type().value()) { case CONTENT_BLOCK_START -> { var startEvent = event.asContentBlockStart(); var block = startEvent.contentBlock(); switch (block.type().value()) { case THINKING -> IO.println("\nStarting thinking block..."); case TEXT -> IO.println("\nStarting text block..."); } } case CONTENT_BLOCK_DELTA -> { var deltaEvent = event.asContentBlockDelta(); deltaEvent.delta().thinking().ifPresent(td -> IO.print(td.thinking()) ); deltaEvent.delta().text().ifPresent(td -> IO.print(td.text()) ); } } }); } } ``` ```php PHP use Anthropic\Messages\RawContentBlockDeltaEvent; use Anthropic\Messages\RawContentBlockStartEvent; use Anthropic\Messages\TextDelta; use Anthropic\Messages\ThinkingDelta; $client = new Client(); $stream = $client->messages->createStream( maxTokens: 16000, messages: [ ['role' => 'user', 'content' => 'What is the greatest common divisor of 1071 and 462?'] ], model: 'claude-opus-5-5', thinking: ['type' => 'adaptive', 'display' => 'summarized'], ); foreach ($stream as $event) { switch (true) { case $event instanceof RawContentBlockStartEvent: echo "\nStarting {$event->contentBlock->type} block...\n"; break; case $event instanceof RawContentBlockDeltaEvent: switch (true) { case $event->delta instanceof ThinkingDelta: echo $event->delta->thinking; break; case $event->delta instanceof TextDelta: echo $event->delta->text; break; } break; } } ``` ```ruby Ruby client = Anthropic::Client.new stream = client.messages.stream( model: "claude-opus-5-5", max_tokens: 16000, # Um hash simples como este aceita display:. A classe tipada ThinkingConfigAdaptive # o escreve como display_ (com sublinhado no final) para não sombrear o Kernel#display do Ruby. # A requisição ainda envia display. thinking: { type: "adaptive", display: "summarized" }, messages: [ { role: "user", content: "What is the greatest common divisor of 1071 and 462?" } ] ) stream.each do |event| case event when Anthropic::Streaming::ThinkingEvent print event.thinking when Anthropic::Streaming::TextEvent print event.text end end ``` Para remontar blocos de pensamento completos com suas assinaturas após o streaming, use o auxiliar de acumulação de mensagens do seu SDK, `stream.get_final_message()` (typescript: `stream.finalMessage()`; ruby: `stream.accumulated_message`; csharp: `.Aggregate()`; go: `message.Accumulate(event)`; java, php: `MessageAccumulator`), em vez de concatenar os deltas você mesmo. ```sse Output event: message_start data: {"type": "message_start", "message": {"id": "msg_01...", "type": "message", "role": "assistant", "content": [], "model": "claude-opus-5-5", "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": "EqQBCgIYAhIM1gbcDa9GJwZA2b..."}} 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 é aberto, chega um `thinking_delta` com uma string `thinking` vazia, segue-se um único `signature_delta` e o bloco é fechado. O streaming de texto começa imediatamente depois: ```sse Output 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":""}} 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":""}} ``` Com `display: "updates"` (beta), os blocos de raciocínio são transmitidos como em `"omitted"`. Cada [bloco de atualização de progresso](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#progress-updates) transmite seu texto como eventos `thinking_delta` antes do bloco `tool_use` que ele introduz. Uma pausa de vários segundos antes da abertura do bloco de atualização de progresso é normal: ```sse Output event: content_block_start data: {"type":"content_block_start","index":1,"content_block":{"type":"thinking","thinking":"","signature":""}} event: content_block_delta data: {"type":"content_block_delta","index":1,"delta":{"type":"thinking_delta","thinking":"Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call."}} event: content_block_delta data: {"type":"content_block_delta","index":1,"delta":{"type":"signature_delta","signature":"Es8CCkYICxIM..."}} event: content_block_stop data: {"type":"content_block_stop","index":1} event: content_block_start data: {"type":"content_block_start","index":2,"content_block":{"type":"tool_use","id":"toolu_01D7FLrfh4GYq7yT1ULFeyMV","name":"edit_file","input":{}}} ``` Em `"updates"`, trate um bloco como uma atualização de progresso assim que um de seus eventos `thinking_delta` carregar texto não vazio. Ao usar streaming com o pensamento ativado, você pode notar que o texto às vezes chega em blocos maiores, alternando com uma entrega menor, token por token. Esse é o comportamento esperado, especialmente para o conteúdo de pensamento. O sistema de streaming processa o conteúdo em lotes, o que pode atrasar e agrupar os eventos de streaming nesse padrão de entrega "em blocos". Para a mecânica geral de streaming, consulte [Streaming de mensagens](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming). ## Pensamento e esforço O parâmetro `thinking` controla se o Claude pensa em [blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) antes de responder; o parâmetro `effort` controla quanto trabalho o Claude dedica à resposta inteira, o que, no modo adaptativo, inclui com que frequência e com que profundidade ele pensa. Não passe `adaptive` como um valor de `effort`: `adaptive` é um modo de pensamento, não um nível de esforço. Para saber o que cada nível de esforço faz com o comportamento do pensamento, consulte a [tabela de comportamento do pensamento por nível](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost#effort-levels) na página [Direcionando o pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost). A página [Esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) documenta o próprio parâmetro, incluindo quais níveis cada modelo suporta. No Claude Opus 4.5, o único modelo exclusivamente de pensamento estendido que suporta esforço, o esforço se combina com `budget_tokens`. Consulte [Regras e ajuste do orçamento](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking#budget-rules-and-tuning). Com os dois controles separados dessa forma, escolha aquele que corresponde ao seu objetivo: * **Menor custo ou latência em uma carga de trabalho com pensamento ativado:** reduza `effort` primeiro. Ele reduz a resposta inteira, incluindo o pensamento. * **O Claude está pensando raramente demais ou de forma superficial demais:** aumente `effort` ou consulte [Direcionando com que frequência Claude pensa](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior) na página de direcionamento. * **Você precisa do pensamento totalmente desativado:** use `thinking: {type: "disabled"}` nos modelos que permitem isso (consulte a [tabela de configuração por modelo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#supported-models)). O Claude Sonnet 5.5 rejeita `"disabled"`. Sua configuração mais baixa é `thinking: {type: "between_tools"}`, que desativa o pensamento antecipado. * **Você precisa de um teto rígido de gastos:** use `max_tokens`. O esforço é uma orientação flexível. `max_tokens` é um limite estrito. ## Pensamento com uso de ferramentas O pensamento funciona junto com o [uso de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview), permitindo que o Claude raciocine sobre a seleção de ferramentas e processe os resultados das ferramentas. Duas restrições se aplicam: 1. **Limitação de escolha de ferramenta (modo manual):** o uso de ferramentas com pensamento estendido manual (`thinking: {type: "enabled"}`) 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": "..."}` resulta em erro, porque essas opções forçam o uso de ferramentas, o que é incompatível com o pensamento estendido manual. O pensamento adaptativo, inclusive em modelos em que o pensamento está ativado por padrão, suporta o uso forçado de ferramentas, exceto no Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1 (consulte [Preenchimento prévio da resposta e uso forçado de ferramentas](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#limits-and-feature-compatibility)). Onde o uso forçado de ferramentas é aceito, a resposta começa com a chamada de ferramenta e não tem bloco `thinking`. 2. **Preservação dos blocos de pensamento:** ao retornar resultados de ferramentas, você deve devolver à API os blocos de pensamento da mensagem do assistente, completos e sem modificações. Consulte [Preservando blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserving-thinking-blocks). **Um loop de uso de ferramentas é um único turno do assistente.** Da perspectiva do modelo, um turno do assistente não termina até que o Claude conclua sua resposta completa, que pode incluir várias chamadas de ferramentas e resultados. Toda esta sequência é um único turno do assistente: ```text wrap 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"] ``` O turno inteiro é executado em um único modo de pensamento: você não pode alternar o pensamento no meio de um turno, inclusive durante o loop de uso de ferramentas. No modo estendido (manual), a API também exige que o turno final do assistente de uma solicitação com pensamento ativado comece com um bloco de pensamento. O modo adaptativo flexibiliza isso: nenhum turno do assistente precisa começar com um. **Conflitos no meio do turno são tratados de forma tolerante.** Se você alternar o pensamento no meio de um turno (por exemplo, entre enviar uma chamada de ferramenta e retornar seu resultado), a API não gera erro. Em vez disso, ela desativa silenciosamente o pensamento para essa solicitação. Para preservar a qualidade do modelo, a API pode remover blocos de pensamento que criariam uma estrutura de turno inválida, ou desativar o pensamento quando o histórico da conversa for incompatível com o pensamento ativado. Para confirmar se o pensamento estava ativo, verifique a presença de blocos `thinking` na resposta. **Alterne entre turnos, não dentro deles.** Planeje sua estratégia de pensamento no início de cada turno. Conclua o turno do assistente e, em seguida, altere a configuração de pensamento para o próximo: ```text wrap 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) ``` Alternar os modos de pensamento também invalida o cache de prompt. Consulte [Pensamento e cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-prompt-caching). ### Preservando blocos de pensamento Quando o Claude invoca uma ferramenta, ele pausa a construção de sua resposta para aguardar informações externas. Quando você retorna o resultado da ferramenta, o Claude continua construindo essa mesma resposta, então seu raciocínio anterior ainda precisa estar presente. Devolva cada bloco `thinking` à API completo e sem modificações, junto com o bloco `tool_use` que ele acompanhava. Isso é importante por dois motivos: 1. **Continuidade do raciocínio:** os blocos de pensamento capturam o raciocínio passo a passo que levou às solicitações de ferramentas. Incluí-los permite que o Claude continue raciocinando de onde parou. 2. **Manutenção do contexto:** os resultados das ferramentas aparecem como mensagens do usuário na estrutura da API, mas fazem parte de um fluxo de raciocínio contínuo. Preservar os blocos de pensamento mantém esse fluxo entre as chamadas de API. Em resumo: * **Obrigatório:** dentro de um turno de uso de ferramentas, devolva os blocos de pensamento. * **Recomendado:** entre turnos, devolva tudo. * **Permitido:** fora do uso de ferramentas, omita o pensamento de turnos anteriores. Você não precisa remover pensamentos antigos por conta própria. Devolva todos os blocos de pensamento em conversas de múltiplos turnos, e a API os filtra automaticamente, mantém os blocos necessários para preservar o raciocínio do modelo e cobra tokens de entrada apenas pelos blocos efetivamente mostrados ao Claude. Quais blocos de turnos anteriores são mantidos varia por modelo. Consulte [Preservação de blocos de pensamento por modelo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-block-preservation-by-model). Para substituir o padrão, use a [estratégia de edição de contexto `clear_thinking_20251015`](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing#thinking-block-clearing). Dentro da mensagem mais recente do assistente, a sequência de blocos `thinking` consecutivos deve corresponder ao que o modelo gerou na solicitação original: você não pode reorganizá-los, editá-los ou descartá-los parcialmente. Isso inclui os [blocos `redacted_thinking`](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#redacted-thinking-blocks). Blocos de pensamento modificados são rejeitados com um erro 400. Consulte [Um erro 400 diz que os blocos de pensamento não podem ser modificados](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) para ver a mensagem exata, as causas comuns e a correção. A única exceção: texto colocado no campo `thinking` vazio de um bloco [omitido](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#controlling-thinking-display) é ignorado em vez de rejeitado. Para um passo a passo completo de dois turnos com código em todos os SDKs, consulte [Pensamento em fluxos de trabalho com ferramentas e múltiplos turnos](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-tool-workflows#two-turn-tool-use-round-trip). Ele define uma ferramenta, recebe uma resposta com pensamento e uso de ferramenta e devolve o turno do assistente junto com o resultado da ferramenta. ### Pensamento intercalado O "interleaved thinking" (pensamento intercalado) permite que o Claude pense entre chamadas de ferramentas, raciocinando sobre cada resultado de ferramenta antes de agir com base nele. Com o pensamento intercalado, o Claude pode: * Raciocinar sobre os resultados de uma chamada de ferramenta antes de determinar o que fazer em seguida * Encadear várias chamadas de ferramentas com etapas de raciocínio entre elas * Tomar decisões mais refinadas com base em resultados intermediários Chamadas de ferramentas consecutivas não exigem pensamento intercalado. O Claude pode encadear chamadas de ferramentas com ou sem pensamento intercalado. A intercalação muda onde os blocos de pensamento aparecem entre as chamadas de ferramentas, não se as chamadas de ferramentas podem ser encadeadas. Com o pensamento adaptativo, o pensamento intercalado é automático em todos os modelos que suportam pensamento adaptativo. Nenhum cabeçalho beta é necessário. No Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Opus 4.8 e Claude Opus 4.7, o raciocínio entre chamadas de ferramentas sempre aparece em blocos de pensamento. O Claude Haiku 4.5 não suporta pensamento intercalado. Em modelos que usam pensamento estendido manual, a intercalação requer um cabeçalho beta e altera a forma como o orçamento de pensamento é contabilizado. [Pensamento intercalado no modo manual](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking#interleaved-thinking) aborda as regras por modelo e o comportamento do cabeçalho específico de cada plataforma. Com o pensamento intercalado, a alocação de pensamento pode abranger todo o turno do assistente, em vez de uma única resposta. O pensamento intercalado é suportado apenas para [ferramentas usadas por meio da Messages API](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/overview). Para uma comparação prática que mostra o que o pensamento intercalado muda em um fluxo de trabalho com duas ferramentas, consulte [Como o pensamento intercalado muda o fluxo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-tool-workflows#how-interleaved-thinking-changes-the-flow). ### Atualizações de progresso entre chamadas de ferramentas No Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5 e Claude Fable 5, o modelo pode escrever uma atualização de progresso entre chamadas de ferramentas. Uma atualização de progresso é uma nota sobre o que o modelo acabou de descobrir e o que está prestes a fazer em seguida, escrita para a pessoa que acompanha o agente, e não como raciocínio. Cada uma retorna como seu próprio bloco `thinking` com sua própria `signature`, separado de qualquer bloco de raciocínio no mesmo ponto. Ela fica imediatamente antes do bloco `tool_use` ou `server_tool_use` que introduz. No máximo uma atualização de progresso precede cada chamada de ferramenta, e o modelo pode pular qualquer uma delas. As atualizações de progresso não são [pensamento intercalado](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#interleaved-thinking): elas aparecem independentemente de blocos de raciocínio aparecerem entre as chamadas de ferramentas, e uma resposta pode conter ambos. O que um bloco de atualização de progresso contém depende de [`display`](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#controlling-thinking-display): | `display` | Blocos de raciocínio | Blocos de atualização de progresso | | ------------------------------------- | ---------------------- | --------------------------------------------------------- | | `"omitted"` (o padrão nesses modelos) | Campo `thinking` vazio | Campo `thinking` vazio | | `"updates"` (beta) | Campo `thinking` vazio | Texto de resumo | | `"summarized"` | Texto de resumo | Texto de resumo, indistinguível de um bloco de raciocínio | No Claude Sonnet 5.5, a configuração de pensamento mais baixa é `thinking: {type: "between_tools"}`. Ela desativa o pensamento antecipado, e cada atualização de progresso retorna com seu texto de resumo, como aconteceria com `display: "updates"`. `between_tools` é aceito apenas com [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) `high` ou inferior. Com `xhigh` ou `max`, uma solicitação com ele retorna um erro 400. `between_tools` não aceita nenhum outro campo: `display`, `budget_tokens` ou `block_binding` enviados com ele retornam um erro 400. A configuração não precisa de cabeçalho beta e funciona em todas as plataformas que oferecem o Claude Sonnet 5.5. Devolva os blocos sem alterações: um bloco de atualização de progresso que você devolve fornece ao modelo a nota completa que ele escreveu, não o resumo. Use `display: "updates"` para uma interface de agente que mantém o raciocínio oculto e mostra ao usuário uma linha de status a cada etapa. Com ele, qualquer bloco `thinking` com texto não vazio é uma atualização de progresso, então renderize esses blocos e nada mais. Ele está em beta e requer o cabeçalho beta `thinking-display-updates-2026-08-18` (para enviá-lo no Amazon Bedrock, Google Cloud ou Microsoft Foundry, consulte [Recursos beta em outras plataformas](https://platform.claude.com/docs/pt-BR/api/beta-headers#beta-features-on-other-platforms)). Sem ele, o valor é rejeitado com o mesmo erro 400 `invalid_request_error` de um valor de `display` desconhecido. ```json { "model": "claude-fable-5-1", "max_tokens": 16000, "thinking": { "type": "adaptive", "display": "updates" }, "tools": [ { "name": "edit_file", "description": "Replace the contents of a file in the repository.", "input_schema": { "type": "object", "properties": { "path": { "type": "string" }, "content": { "type": "string" } }, "required": ["path", "content"] } } ], "messages": [ { "role": "user", "content": "The login test fails after an hour of uptime. Find out why and fix it." } ] } ``` Com `"updates"`, o início da resposta que segue um `tool_result` tem esta aparência. O primeiro bloco é de raciocínio e permanece vazio, como ficaria com `"omitted"`. O segundo carrega texto, então é uma atualização de progresso. Com `"summarized"`, ambos os blocos carregam texto e, com `"omitted"`, ambos ficam vazios. ```json Output { "content": [ { "type": "thinking", "thinking": "", "signature": "EqMBCkYICxIM..." }, { "type": "thinking", "thinking": "Confirmed the retry path never refreshes the expired token. Editing auth.py to add the refresh call.", "signature": "Es8CCkYICxIM..." }, { "type": "tool_use", "id": "toolu_01D7FLrfh4GYq7yT1ULFeyMV", "name": "edit_file", "input": { "path": "auth.py", "content": "..." } } ] } ``` Tenha em mente o seguinte ao trabalhar com atualizações de progresso: * Devolva os blocos de atualização de progresso sem alterações junto com o restante do turno do assistente, como qualquer outro bloco `thinking`. * O texto que você recebe é um resumo da atualização de progresso, normalmente uma ou duas frases. Não dependa do seu tamanho. A atualização de progresso conta para `usage.output_tokens` com seu tamanho completo, não com o do resumo. * Um bloco de atualização de progresso pode retornar com um campo `thinking` vazio com qualquer valor de `display`. Não renderize nada para um bloco vazio. Com `"updates"`, ele tem a mesma aparência de um bloco de raciocínio vazio e não precisa de tratamento separado. * Quando uma resposta para em `max_tokens`, `model_context_window_exceeded` ou `stop_sequence` logo após uma chamada de ferramenta ou um resultado de ferramenta, seu último bloco pode ser um bloco de atualização de progresso que substitui o trabalho que o modelo não havia concluído. Com `"updates"` e `"summarized"`, seu texto é exatamente `This part of the response was interrupted before it finished.` e você pode exibi-lo como qualquer outra atualização. Com `"omitted"`, ele fica vazio. Para continuar, devolva o turno do assistente sem alterações e acrescente uma nova mensagem `user` (com um `tool_result` para cada bloco `tool_use` nesse turno). * Ao fazer [streaming](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#streaming-thinking), espere uma pausa de vários segundos antes da abertura de um bloco de atualização de progresso. Consulte o rastreamento de `"updates"` em [Streaming do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#streaming-thinking). * Esses modelos escrevem menos atualizações de progresso com [esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) mais alto e em cadeias longas de ferramentas. Se sua interface depende delas, consulte [Peça atualizações de progresso voltadas ao usuário](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-fable-5-1#ask-for-user-facing-progress-updates) ou, para o Claude Opus 5.5, [Atualizações de progresso voltadas ao usuário](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates). Para o Claude Sonnet 5.5, consulte [Atualizações de progresso voltadas ao usuário](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5#user-facing-progress-updates). ### Preservação de blocos de pensamento por modelo Se os blocos de pensamento de turnos anteriores do assistente permanecem no contexto por padrão depende do modelo: * **Manter todos os turnos anteriores:** Claude Opus 4.5 e modelos Opus posteriores, Claude Sonnet 4.6 e modelos Sonnet posteriores, Claude Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5 e Claude Mythos Preview. * **Manter apenas o último turno:** modelos Opus e Sonnet anteriores, e todos os modelos Haiku até o Claude Haiku 4.5. Quando você envia blocos de pensamento mais antigos de volta, a API os remove automaticamente. Você não precisa removê-los por conta própria. A preservação traz dois benefícios: * **Otimização de cache:** blocos de pensamento preservados permitem acertos de cache durante o uso de ferramentas, pois são enviados de volta com os resultados das ferramentas e armazenados em cache de forma incremental ao longo do turno do assistente, resultando em economia de tokens em fluxos de trabalho de várias etapas. * **Nenhum impacto na inteligência:** preservar blocos de pensamento não tem efeito negativo no desempenho do modelo. A contrapartida é o uso de contexto: conversas longas consomem mais espaço de contexto em modelos que mantêm tudo, porque os blocos de pensamento retidos contam como entrada como qualquer outro histórico de conversa (consulte [Pensamento e a janela de contexto](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-the-context-window)). O comportamento é automático em ambos os regimes. Nenhuma alteração de código ou cabeçalho beta é necessária, e você deve continuar enviando de volta blocos de pensamento completos e não modificados, conforme descrito em [Preservando blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserving-thinking-blocks). Para substituir o padrão em qualquer direção, use a [limpeza de blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing#thinking-block-clearing). **Trocando de modelo no meio da conversa.** Continue enviando de volta os blocos de pensamento sem alterações quando você trocar de modelo, por exemplo após um [fallback por recusa do classificador](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback). Um bloco de pensamento só pode ser lido pelo modelo que o produziu e por certos outros modelos, e a API ignora ou descarta os blocos que o modelo de destino não consegue ler. No Claude Fable 5.1 e no Claude Mythos 5.1 a direção importa: eles leem os blocos de pensamento de modelos anteriores, e apenas os dois leem os blocos um do outro, então trocar para eles mantém o raciocínio da conversa e trocar deles para qualquer outro modelo o descarta (consulte [como os blocos descartados são cobrados e relatados](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#switching-models)). O Claude Opus 5.5 lê os blocos de pensamento do Claude Opus 5 e os de modelos Opus, Sonnet e Haiku anteriores e, na Claude API e no Google Cloud, os do Claude Haiku 5.5, mas não os dos modelos Claude Fable e Claude Mythos; na Claude API, o Claude Fable 5.1 e o Claude Mythos 5.1 leem os blocos do Claude Opus 5.5. Uma troca do Claude Opus 5.5 para o Claude Fable 5.1 na Claude API mantém o raciocínio dos turnos anteriores; uma troca do Claude Fable 5.1 para o Claude Opus 5.5 o descarta. O Claude Sonnet 5.5 lê blocos de pensamento do Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 e modelos anteriores e, na Claude API e no Google Cloud, do Claude Haiku 5.5, mas não do Claude Opus 5, Claude Opus 5.5 ou de qualquer modelo Claude Fable ou Claude Mythos. Na Claude API e no Google Cloud, o Claude Opus 5.5 lê os blocos do Claude Sonnet 5.5 e nenhum outro modelo o faz: uma troca do Claude Sonnet 5.5 para o Claude Opus 5.5 na Claude API e no Google Cloud mantém o raciocínio dos turnos anteriores, e qualquer outra troca a partir do Claude Sonnet 5.5 o descarta. O Claude Haiku 5.5 lê blocos de pensamento do Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5 e modelos anteriores, mas não do Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5 ou de qualquer modelo Claude Fable ou Claude Mythos. Na Claude API e no Google Cloud, o Claude Opus 5.5 e o Claude Sonnet 5.5 leem os blocos do Claude Haiku 5.5 e nenhum outro modelo o faz. Remova você mesmo os blocos `thinking` e `redacted_thinking` anteriores apenas para economizar tokens de entrada em modelos que os ignoram em vez de descartá-los, e nunca ao resgatar um [crédito de fallback](https://platform.claude.com/docs/pt-BR/build-with-claude/fallback-credit), que exige o corpo inalterado. ## Pensamento preservado O [pensamento preservado](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking) determina se o modelo pode usar um bloco de pensamento que você envia de volta de um turno anterior. A partir do Claude Fable 5.1, a API verifica a `signature` de cada bloco `thinking` ou `redacted_thinking` em uma solicitação quanto a duas coisas: * **O modelo que o produziu.** Cada modelo lê seus próprios blocos de pensamento e os de um conjunto fixo de outros modelos. O Claude Fable 5.1 lê blocos do Claude Opus 5 e, na Claude API, do Claude Opus 5.5; nem o Claude Opus 5 nem o Claude Opus 5.5 leem blocos do Claude Fable 5.1. A API descarta um bloco que o modelo atual não consegue ler, sem erro e sem cobrá-lo. Consulte [Trocar de modelo no meio da conversa](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#switching-models). * **Tudo o que foi enviado antes dele.** Um bloco permanece válido apenas enquanto o prompt `system` de nível superior, as `tools` e as mensagens anteriores a ele permanecem inalterados. Se qualquer um deles mudar, esse bloco e todos os blocos de pensamento posteriores se tornam inválidos, e a API rejeita a solicitação com um erro 400 ou descarta os blocos inválidos, conforme sua escolha. Consulte [Manter o prefixo inalterado](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#prefix-check). Os blocos de pensamento do Claude Sonnet 5.5 e do Claude Haiku 5.5 também estão vinculados à conta que os produziu. Consulte [Os blocos de pensamento permanecem com a conta que os produziu](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#account-bound-thinking) para saber onde a API aplica isso. A verificação de modelo se aplica a todas as contas. A API aplica a verificação de prefixo por padrão para contas criadas em ou após 31 de agosto de 2026, 00:00 UTC. Em contas mais antigas, ela aplica a verificação apenas em solicitações que definem `thinking.block_binding.prefix_mismatch_behavior`. Torne sua integração somente de acréscimo (append-only), independentemente da idade da sua conta, para que o mesmo código funcione em todas as contas, incluindo contas mais novas com aplicação por padrão. Para manter o pensamento válido, envie cada turno do assistente de volta exatamente como você o recebeu e adicione novas mensagens apenas no final de `messages`. Se o seu código constrói o array `messages` por conta própria, a página de Pensamento preservado aborda: * [O que conta como uma edição](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#what-counts-as-an-edit) e [como verificar se o seu código faz uma](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted). * [O recurso da API que substitui cada edição comum](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#replace-prefix-edits): mensagens de sistema no meio da conversa para novas instruções e lembretes por turno, blocos `tool_addition` e `tool_removal` para alterações de ferramentas, `output_config` por mensagem para alterações de esforço, e compactação e edição de contexto no lado do servidor para redução. * [Compactação no lado do cliente](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#custom-compaction-on-the-client): quais padrões mantêm o pensamento válido e quais não. * [O cabeçalho beta `thinking-binding-controls-2026-08-01`](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#preserved-thinking-controls). Ele adiciona um campo `block_binding.prefix_mismatch_behavior` (`"error"` ou `"drop_block"`) à configuração de pensamento e um array `input_transformations` a cada resposta. O array lista cada bloco de pensamento que a API descartou, ou que falhou na verificação de prefixo e foi deixado passar. ## Pensamento e cache de prompt O ["prompt caching" (cache de prompt)](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching) interage com o pensamento de algumas maneiras específicas. As regras a seguir se aplicam em ambos os modos de pensamento. **Alterações de configuração invalidam o cache.** A configuração de pensamento e o nível de [`effort`](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) resolvido são renderizados no próprio prompt, portanto alterar qualquer um deles inicia um novo prefixo de cache. Alternar entre `adaptive`, `enabled` e `disabled`, alterar `budget_tokens` e alterar o valor de esforço invalidam os pontos de interrupção de cache: pontos de interrupção no nível de mensagem sempre falham, e pontos de interrupção de ferramentas e do prompt do sistema também podem falhar, dependendo de onde o modelo renderiza a configuração. Trate qualquer alteração de pensamento ou de esforço de nível superior como um reinício do cache. Em modelos que suportam [esforço por mensagem](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#change-effort-mid-conversation-beta), uma alteração de esforço transmitida em uma mensagem `role: "system"` dentro de `messages` mantém o prefixo em cache intacto. Solicitações consecutivas que mantêm a mesma configuração preservam o cache, e definir um parâmetro explicitamente com seu valor padrão equivale a omiti-lo. Um bloco de pensamento que a API descarta sob qualquer [condição de pensamento preservado](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserved-thinking) altera o prefixo em cache a partir da posição desse bloco. Blocos enviados de volta sem alterações mantêm o cache intacto. Uma demonstração prática com a saída de uso está na página [Direcionando o pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost#prompt-caching). **Blocos de pensamento são armazenados em cache com os resultados das ferramentas.** Durante um loop de uso de ferramentas, o cache ocorre quando você faz uma solicitação de acompanhamento que inclui resultados de ferramentas. Nesse ponto, o histórico de conversa anterior, incluindo seus blocos de pensamento, pode ser armazenado em cache, e esses blocos de pensamento em cache contam como tokens de entrada nas suas métricas de uso quando lidos do cache. Isso ocorre automaticamente, mesmo sem marcadores `cache_control` explícitos, e se comporta da mesma forma para pensamento regular e intercalado. A contrapartida: blocos de pensamento que você nunca mais vê nas respostas ainda contribuem para o uso de tokens de entrada quando lidos do cache. **Se os blocos anteriores estão no contexto depende do modelo.** O [padrão de preservação](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-block-preservation-by-model) rege isso. Em modelos que mantêm tudo, os blocos de pensamento dos turnos anteriores permanecem em cache e no contexto. Em modelos que mantêm apenas o último turno, assim que você envia uma mensagem de usuário que não é um resultado de ferramenta, todos os blocos de pensamento anteriores são removidos do contexto. Nesses modelos, uma conversa como esta: ```text wrap 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] ``` é processada como se os blocos de pensamento nunca tivessem existido: ```text wrap 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] ``` Em modelos que mantêm tudo, a mesma solicitação mantém `thinking_block_1` e `thinking_block_2` no contexto e no cache. **A degradação remove o pensamento do histórico armazenável em cache.** Se o pensamento for desativado no meio do turno e você enviar conteúdo de pensamento no turno atual de uso de ferramentas, o conteúdo de pensamento é removido e o pensamento permanece desativado para essa solicitação (consulte [degradação graciosa](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-with-tool-use)). O [pensamento intercalado](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#interleaved-thinking) amplifica os efeitos de invalidação de cache, porque blocos de pensamento podem ocorrer entre várias chamadas de ferramentas. Tarefas com muito pensamento frequentemente levam mais tempo para serem concluídas do que o tempo de vida padrão de 5 minutos do cache. Considere a [duração de cache de 1 hora](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#1-hour-cache-duration) para manter acertos de cache em sessões de pensamento mais longas e fluxos de trabalho de várias etapas. ## Pensamento e a janela de contexto `max_tokens`, que inclui todo o pensamento que Claude gera no turno atual, é aplicado como um limite estrito. Nos modelos Claude 4.5 e mais recentes, se os tokens de entrada mais `max_tokens` excederem o tamanho da "context window" (janela de contexto), a API aceita a solicitação. Se a geração então atingir o limite da janela de contexto, ela para com `stop_reason: "model_context_window_exceeded"` em vez de retornar um erro. Em modelos anteriores, a API retorna um erro de validação. Consulte [Lidando com motivos de parada](https://platform.claude.com/docs/pt-BR/build-with-claude/handling-stop-reasons). Como o pensamento conta na janela depende de quando ele foi gerado: * **O pensamento do turno atual** sempre conta para `max_tokens`, é cobrado como tokens de saída e ocupa espaço na janela de contexto durante o turno que o gerou. * **O pensamento de turnos anteriores** depende do [padrão de preservação](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-block-preservation-by-model). Em [modelos que mantêm todos os turnos anteriores](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-block-preservation-by-model), os blocos de pensamento anteriores permanecem no contexto, contam para a janela e são cobrados como tokens de entrada, como o restante do histórico da conversa. Em modelos que mantêm apenas o último turno, a API remove automaticamente os blocos de pensamento mais antigos quando você os envia de volta, de modo que eles não consomem espaço na janela nem tokens de entrada. Na prática: * Em modelos que mantêm tudo, planeje sua janela de contexto como se o pensamento fosse um histórico de conversa comum, porque ele é. Sessões agênticas longas acumulam pensamento no contexto. Use a [limpeza de blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing#thinking-block-clearing) se precisar recuperar espaço. * Em modelos que mantêm apenas o último turno, o pensamento é apenas um custo por turno: o pensamento de cada turno conta para o `max_tokens` desse turno e depois sai da janela. Os diagramas a seguir ilustram o regime de apenas o último turno (remoção). O primeiro mostra uma conversa de vários turnos: o bloco de pensamento de cada turno é gerado na saída, mas não é levado para a entrada dos turnos posteriores. ![Diagrama do "thinking" (pensamento) em um modelo que remove blocos de pensamento anteriores: o bloco de pensamento de cada turno é gerado na saída e não é levado para a entrada dos turnos posteriores](https://platform.claude.com/docs/pt-BR/images/context-window-thinking.svg) O segundo mostra o mesmo regime com uso de ferramentas: o pensamento permanece no contexto junto com seu resultado de ferramenta durante o turno do assistente e depois sai no próximo turno do usuário. ![Diagrama do "thinking" (pensamento) com "tool use" (uso de ferramentas) em um modelo que remove blocos de pensamento anteriores: o pensamento é mantido com seu resultado de ferramenta e depois descartado no próximo turno do usuário](https://platform.claude.com/docs/pt-BR/images/context-window-thinking-tools.svg) Use a [API de contagem de tokens](https://platform.claude.com/docs/pt-BR/build-with-claude/token-counting) para obter contagens precisas para o seu caso de uso específico, especialmente para conversas de vários turnos que incluem pensamento. ## Criptografia do pensamento O conteúdo completo do pensamento é criptografado e retornado no campo `signature` de cada bloco de pensamento. A API usa a assinatura para verificar se os blocos de pensamento foram gerados por Claude quando você os devolve. Tenha em mente o seguinte ao trabalhar com assinaturas: * Só é estritamente necessário devolver blocos de pensamento ao [usar ferramentas com pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-with-tool-use). Caso contrário, você pode omitir os blocos de pensamento de turnos anteriores. Se você os devolver, se a API os mantém ou os remove depende do modelo (consulte [Preservação de blocos de pensamento por modelo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-block-preservation-by-model)). Use a [edição de contexto](https://platform.claude.com/docs/pt-BR/build-with-claude/context-editing) para configurar isso. * Ao devolver blocos de pensamento, devolva tudo exatamente como recebeu, para manter a consistência e evitar possíveis problemas. * Ao fazer [streaming de respostas](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#streaming-thinking), a assinatura chega como um `signature_delta` dentro de um evento `content_block_delta` logo antes do evento `content_block_stop`. * Os valores de `signature` são significativamente mais longos no Claude 4 e em modelos posteriores do que em modelos anteriores. * O campo `signature` é opaco: não o interprete nem o analise. * Os valores de `signature` são compatíveis entre plataformas (a Claude API, [Amazon Bedrock](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-in-amazon-bedrock) e [Google Cloud](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-on-vertex-ai)). Valores gerados em uma plataforma funcionam em outra, exceto que os blocos de pensamento do Claude Sonnet 5.5 e do Claude Haiku 5.5 funcionam apenas na conta que os produziu ou em uma conta vinculada a ela. Consulte [Os blocos de pensamento permanecem com a conta que os produziu](https://platform.claude.com/docs/pt-BR/build-with-claude/preserved-thinking#account-bound-thinking). ## Blocos de pensamento redigidos Além dos blocos `thinking` regulares, a API pode retornar blocos `redacted_thinking` quando partes do raciocínio de Claude são redigidas por motivos de segurança. Um bloco `redacted_thinking` contém conteúdo de pensamento criptografado em um campo `data`, sem texto legível: ```json { "type": "redacted_thinking", "data": "..." } ``` O campo `data` é opaco e criptografado. Assim como o campo `signature` em blocos de pensamento regulares, devolva os blocos `redacted_thinking` à API sem alterações ao continuar uma conversa de vários turnos com [ferramentas](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-with-tool-use). Se o seu código filtra blocos de conteúdo por tipo (por exemplo, `block.type == "thinking"`) ao devolver respostas com uso de ferramentas, inclua também os blocos `redacted_thinking`. Filtrar apenas por `block.type == "thinking"` descarta silenciosamente os blocos `redacted_thinking` e quebra o protocolo de vários turnos descrito em [Preservando blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserving-thinking-blocks). Os blocos `redacted_thinking` são um tipo distinto de bloco de conteúdo retornado quando o pensamento é redigido por motivos de segurança. Isso é diferente da opção [`display: "omitted"`](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#controlling-thinking-display), que retorna blocos `thinking` regulares com um campo `thinking` vazio. ## Limites e compatibilidade de recursos ### Parâmetros de amostragem No Claude Fable 5.1, Claude Mythos 5.1, Claude Fable 5, Claude Mythos 5, Claude Mythos Preview, Claude Opus 5.5, Claude Opus 5, Claude Opus 4.8, Claude Opus 4.7, Claude Sonnet 5.5, Claude Sonnet 5 e Claude Haiku 5.5, valores não padrão de `temperature`, `top_p` ou `top_k` retornam um erro 400 em todas as solicitações, independentemente de o pensamento ser usado. Nesses modelos, o padrão de `top_p` é `0.99`, então um `top_p` de `1` retorna um erro 400, assim como uma solicitação que inclui tanto `temperature` quanto `top_p`, mesmo com seus valores padrão. Consulte [Remova os parâmetros de amostragem](https://platform.claude.com/docs/pt-BR/models/haiku-5-5/migration-guide#remove-sampling-parameters). Em modelos mais antigos, a restrição se aplica apenas enquanto o pensamento está ativado: `temperature` e `top_k` são incompatíveis com o pensamento, e `top_p` é permitido com valores entre 0,95 e 1. ### Preenchimento prévio da resposta e uso forçado de ferramentas Os modelos Claude 4.6 e posteriores e o Claude Mythos Preview rejeitam um turno final do assistente preenchido previamente com um erro 400, esteja o pensamento ativado ou não (consulte [Prefill não suportado](https://platform.claude.com/docs/pt-BR/api/errors#prefill-not-supported)). Em modelos anteriores, você não pode preencher previamente a resposta do assistente enquanto o pensamento está ativado. O uso forçado de ferramentas (`tool_choice: {"type": "any"}` ou `{"type": "tool", ...}`) é incompatível com o pensamento estendido manual, mas funciona com o pensamento adaptativo. As exceções são o Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.1 e Claude Mythos 5.1, que rejeitam o uso forçado de ferramentas em todas as solicitações com um erro 400. Nesses modelos, use `tool_choice: {"type": "auto"}` com [uso estrito de ferramentas](https://platform.claude.com/docs/pt-BR/agents-and-tools/tool-use/strict-tool-use) ou [saídas estruturadas](https://platform.claude.com/docs/pt-BR/build-with-claude/structured-outputs). Onde o uso forçado de ferramentas é aceito, a resposta começa com a chamada da ferramenta e não tem bloco `thinking`. Para permitir que o modelo pense antes de chamar uma ferramenta, use `tool_choice: {"type": "auto"}` e diga no prompt quando usar a ferramenta. Consulte [Pensamento com uso de ferramentas](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-with-tool-use). ### Limites de saída Cada modelo aceita `max_tokens` até o teto listado aqui. Na [Message Batches API](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing#extended-output-beta), o [cabeçalho beta](https://platform.claude.com/docs/pt-BR/api/beta-headers) `output-300k-2026-03-24` eleva esse teto para os modelos com um teto de lotes listado. | Model | Max output tokens | Batches beta ceiling | | :-------------------- | :---------------- | :------------------- | | Claude Fable 5.1 | 128K | — | | Claude Mythos 5.1 | 128K | — | | Claude Fable 5 | 128K | — | | Claude Mythos 5 | 128K | — | | Claude Mythos Preview | 128K | Not available | | Claude Opus 5.5 | 128K | 300K | | Claude Opus 5 | 128K | 300K | | Claude Opus 4.8 | 128K | 300K | | Claude Opus 4.7 | 128K | 300K | | Claude Opus 4.6 | 128K | 300K | | Claude Opus 4.5 | 64K | Not available | | Claude Sonnet 5.5 | 128K | 300K | | Claude Sonnet 5 | 128K | 300K | | Claude Sonnet 4.6 | 128K | 300K | | Claude Sonnet 4.5 | 64K | Not available | | Claude Haiku 5.5 | 128K | 300K | | Claude Haiku 4.5 | 64K | Not available | Consulte a [visão geral dos modelos](https://platform.claude.com/docs/pt-BR/models/overview) para ver os limites dos modelos legados. ### Solicitações longas O SDK exige streaming quando `max_tokens` é maior que 21.333, para evitar timeouts HTTP em solicitações de longa duração. Esta é uma validação no lado do cliente, não uma restrição da API. Se você não precisa processar eventos de forma incremental, use `.stream()` (java: `.createStreaming()`; csharp: `.CreateStreaming()`; go: `.NewStreaming()`; php: `->createStream()`) com `.get_final_message()` (typescript: `.finalMessage()`; ruby: `.accumulated_message`; csharp: `.Aggregate()`; go: `message.Accumulate(event)`; java, php: `MessageAccumulator`) para obter o objeto `Message` completo sem precisar montá-lo você mesmo a partir de eventos individuais. Consulte [Streaming de mensagens](https://platform.claude.com/docs/pt-BR/build-with-claude/streaming#get-the-final-message-without-handling-events). Espere tempos de resposta mais longos quando o pensamento estiver ativo, porque gerar blocos de pensamento adiciona tempo de processamento. Para cargas de trabalho que levam o pensamento acima de aproximadamente 32 mil tokens por solicitação, use o [processamento em lote](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing) para evitar problemas de rede: essas solicitações podem durar o suficiente para atingir timeouts do sistema e limites de conexões abertas. ## Próximos passos Direcione com que frequência e profundidade Claude pensa usando níveis de effort, orientações no prompt do sistema e direcionamento por mensagem, e entenda o custo e os preços do pensamento. Acompanhe um ciclo completo de uso de ferramentas em dois turnos que preserva corretamente os blocos de pensamento e veja como o pensamento intercalado altera o fluxo. Descubra se sua integração com a Messages API edita o histórico da conversa e substitua cada edição pelo recurso da API que mantém válidos os blocos de pensamento anteriores. Diagnostique e corrija as falhas de pensamento mais comuns: erros 400 de configuração, blocos de pensamento vazios ou ausentes, paradas por max\_tokens e falhas de cache. Controle quantos tokens Claude usa ao responder com o parâmetro effort, equilibrando a profundidade da resposta e a eficiência de tokens.