---
title: Pensamento estendido
url: https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking
description: Configure o pensamento estendido manual com um orçamento fixo de budget_tokens nos modelos Claude que o suportam e migre para o pensamento adaptativo.
---

<Note>
  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).
</Note>

<Warning>
  O "extended thinking" (pensamento estendido) (`thinking.type: "enabled"` com `budget_tokens`) está descontinuado nos modelos Claude 4.6 (requisições que o utilizam ainda são bem-sucedidas). Os modelos Claude 4.7 e posteriores não o suportam e rejeitam requisições que o utilizam, retornando um erro 400. Nos modelos Claude 4.5 e anteriores que suportam pensamento, o pensamento estendido é o único modo de pensamento disponível. O Claude Mythos Preview suporta ambos os modos. Onde ambos os modos estiverem disponíveis, use o [pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) em vez disso.

  Consulte [Migrando para o pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking#migrating-to-adaptive-thinking) para mudar para o pensamento adaptativo. Se o seu modelo suporta apenas pensamento estendido, esta página descreve a configuração suportada; nenhuma alteração é necessária até que você mude para um modelo mais recente.
</Warning>

<Note>
  Se uma requisição falhar com um erro 400 cuja mensagem começa com `"thinking.type.enabled" is not supported`, seu modelo usa pensamento adaptativo em vez disso. Consulte [Solução de problemas do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#error-thinking-type-enabled) ou vá direto para [Migrando para o pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking#migrating-to-adaptive-thinking).
</Note>

O "extended thinking" (pensamento estendido) no modo manual dá a você controle direto sobre quanto Claude pensa. Você define um orçamento de tokens de pensamento em cada requisição com `thinking: {type: "enabled", budget_tokens: N}`, e Claude pensa dentro desse orçamento antes de começar sua resposta final. O modo manual continua útil quando sua carga de trabalho exige latência previsível ou controle preciso sobre os custos de pensamento. Esta página aborda como definir e ajustar o orçamento, como o modo manual interage com o pensamento intercalado e o "prompt caching" (cache de prompt), e como migrar para o pensamento adaptativo.

Para aprender como o pensamento em si funciona, incluindo blocos de pensamento e o formato da resposta, o parâmetro `display`, streaming, pensamento com "tool use" (uso de ferramentas) e criptografia, consulte a [visão geral do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking).

## Modelos suportados

A disponibilidade do pensamento estendido por modelo, incluindo os modelos em que o pensamento estendido é o único modo, está listada na [tabela de configuração por modelo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#supported-models).

## Como usar o pensamento estendido

Aqui está um exemplo de uso do pensamento estendido na Messages API:

<CodeGroup>
  ```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-4-6",
      "max_tokens": 16000,
      "thinking": {
        "type": "enabled",
        "budget_tokens": 10000
      },
      "messages": [
        {
          "role": "user",
          "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?"
        }
      ]
    }'
  ```

  ```bash CLI
  ant messages create \
    --format yaml <<'YAML'
  model: claude-sonnet-4-6
  max_tokens: 16000
  thinking:
    type: enabled
    budget_tokens: 10000
  messages:
    - role: user
      content: Are there an infinite number of prime numbers such that n mod 4 == 3?
  YAML
  ```

  ```python Python
  client = anthropic.Anthropic()

  response = client.messages.create(
      model="claude-sonnet-4-6",
      max_tokens=16000,
      thinking={"type": "enabled", "budget_tokens": 10000},
      messages=[
          {
              "role": "user",
              "content": "Are there an infinite number of prime numbers such that n mod 4 == 3?",
          }
      ],
  )

  # A resposta contém blocos de pensamento resumidos e blocos de texto
  for block in response.content:
      match block.type:
          case "thinking":
              print(f"\nThinking summary: {block.thinking}")
          case "text":
              print(f"\nResponse: {block.text}")
  ```

  ```typescript TypeScript
  const client = new Anthropic();

  const response = await client.messages.create({
    model: "claude-sonnet-4-6",
    max_tokens: 16000,
    thinking: {
      type: "enabled",
      budget_tokens: 10000
    },
    messages: [
      {
        role: "user",
        content: "Are there an infinite number of prime numbers such that n mod 4 == 3?"
      }
    ]
  });

  // A resposta contém blocos de pensamento resumidos e blocos de texto
  for (const block of response.content) {
    switch (block.type) {
      case "thinking":
        console.log(`\nThinking summary: ${block.thinking}`);
        break;
      case "text":
        console.log(`\nResponse: ${block.text}`);
        break;
    }
  }
  ```

  ```csharp C#
  AnthropicClient client = new();

  var response = await client.Messages.Create(new()
  {
      Model = Model.ClaudeSonnet4_6,
      MaxTokens = 16000,
      Thinking = new ThinkingConfigEnabled(budgetTokens: 10000),
      Messages =
      [
          new()
          {
              Role = Role.User,
              Content = "Are there an infinite number of prime numbers such that n mod 4 == 3?",
          },
      ],
  });

  // A resposta contém blocos de pensamento resumidos e blocos de texto
  foreach (var block in response.Content)
  {
      if (block.TryPickThinking(out var thinking))
      {
          Console.WriteLine($"\nThinking summary: {thinking.Thinking}");
      }
      else if (block.TryPickText(out var text))
      {
          Console.WriteLine($"\nResponse: {text.Text}");
      }
  }
  ```

  ```go Go
  client := anthropic.NewClient()

  response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{
  	Model:     anthropic.ModelClaudeSonnet4_6,
  	MaxTokens: 16000,
  	Thinking:  anthropic.ThinkingConfigParamOfEnabled(10000),
  	Messages: []anthropic.MessageParam{
  		anthropic.NewUserMessage(anthropic.NewTextBlock("Are there an infinite number of prime numbers such that n mod 4 == 3?")),
  	},
  })
  if err != nil {
  	log.Fatal(err)
  }

  // A resposta contém blocos de pensamento resumidos e blocos de texto
  for _, block := range response.Content {
  	switch block := block.AsAny().(type) {
  	case anthropic.ThinkingBlock:
  		fmt.Printf("\nThinking summary: %s", block.Thinking)
  	case anthropic.TextBlock:
  		fmt.Printf("\nResponse: %s", block.Text)
  	}
  }
  ```

  ```java Java
  import com.anthropic.client.okhttp.AnthropicOkHttpClient;
  import com.anthropic.models.messages.MessageCreateParams;
  import com.anthropic.models.messages.Model;

  void main() {
      var client = AnthropicOkHttpClient.fromEnv();

      var params = MessageCreateParams.builder()
          .model(Model.CLAUDE_SONNET_4_6)
          .maxTokens(16_000)
          .enabledThinking(10_000)
          .addUserMessage("Are there an infinite number of prime numbers such that n mod 4 == 3?")
          .build();

      var response = client.messages().create(params);

      // A resposta contém blocos de pensamento resumidos e blocos de texto
      for (var block : response.content()) {
          block.thinking().ifPresent(thinkingBlock ->
              IO.println("\nThinking summary: " + thinkingBlock.thinking())
          );
          block.text().ifPresent(textBlock ->
              IO.println("\nResponse: " + textBlock.text())
          );
      }
  }
  ```

  ```php PHP
  $client = new Client();

  $response = $client->messages->create(
      model: 'claude-sonnet-4-6',
      maxTokens: 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?',
          ],
      ],
  );

  // A resposta contém blocos de pensamento resumidos e blocos de texto
  foreach ($response->content as $block) {
      echo match (true) {
          $block instanceof \Anthropic\Messages\ThinkingBlock => "\nThinking summary: {$block->thinking}",
          $block instanceof \Anthropic\Messages\TextBlock => "\nResponse: {$block->text}",
          default => '',
      };
  }
  ```

  ```ruby Ruby
  client = Anthropic::Client.new

  response = client.messages.create(
    model: "claude-sonnet-4-6",
    max_tokens: 16_000,
    thinking: {
      type: :enabled,
      budget_tokens: 10_000
    },
    messages: [
      {
        role: :user,
        content: "Are there an infinite number of prime numbers such that n mod 4 == 3?"
      }
    ]
  )

  # A resposta contém blocos de pensamento resumidos e blocos de texto
  response.content.each do |block|
    case block
    when Anthropic::Models::ThinkingBlock
      puts "\nThinking summary: #{block.thinking}"
    when Anthropic::Models::TextBlock
      puts "\nResponse: #{block.text}"
    end
  end
  ```
</CodeGroup>

Para ativar o pensamento estendido manual, adicione um objeto `thinking` com `type` definido como `enabled` e um valor de `budget_tokens`.

O parâmetro `budget_tokens` define uma meta de quantos tokens Claude pode usar em seu processo de raciocínio interno. Orçamentos maiores podem melhorar a qualidade da resposta ao permitir uma análise mais completa de problemas complexos.

## Regras e ajuste do orçamento

`budget_tokens` deve satisfazer estas restrições:

* **Mínimo de 1.024 tokens.** A API rejeita valores menores.
* **Menor que `max_tokens`.** Os tokens de pensamento contam para o limite de `max_tokens` do turno, portanto o orçamento deve deixar espaço para a resposta final. A única exceção é o [pensamento intercalado](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking#interleaved-thinking), em que `budget_tokens` pode exceder `max_tokens` porque o orçamento abrange todos os blocos de pensamento dentro de um turno do assistente.
* **Sem pré-aquecimento de cache.** Como `budget_tokens` deve ser menor que `max_tokens`, o pensamento estendido não pode ser combinado com `max_tokens: 0` ([pré-aquecimento do cache](https://platform.claude.com/docs/pt-BR/build-with-claude/prompt-caching#pre-warming-the-cache)).

O orçamento é uma meta, não um limite rígido. O uso real de tokens varia com a tarefa, e Claude pode parar de raciocinar bem antes de o orçamento se esgotar; `max_tokens` continua sendo o teto rígido da saída total.

No Claude Opus 4.5, o único modelo exclusivo de pensamento estendido que suporta [effort](https://platform.claude.com/docs/pt-BR/build-with-claude/effort), o effort molda a resposta geral enquanto `budget_tokens` define a profundidade do pensamento; defina ambos.

Para ajustar o orçamento:

* Adeque o ponto de partida à tarefa. Para tarefas simples, comece perto do mínimo de 1.024 tokens e aumente gradualmente para encontrar a faixa ideal para o seu caso de uso. Para tarefas complexas, comece com um orçamento maior, de 16.000 tokens ou mais, e ajuste conforme suas necessidades de latência e qualidade. Orçamentos maiores permitem um raciocínio mais abrangente, com retornos decrescentes que dependem da tarefa, e ao custo de maior latência. Para tarefas críticas, teste diferentes configurações para encontrar o equilíbrio certo.
* Para orçamentos de pensamento acima de 32k, use o [processamento em lote](https://platform.claude.com/docs/pt-BR/build-with-claude/batch-processing) para evitar problemas de rede. Forçar o modelo a pensar além de 32k tokens produz requisições de longa duração que podem atingir timeouts do sistema e limites de conexões abertas.

Para acompanhar quanto um orçamento realmente custa a você, monitore o campo `usage.output_tokens_details.thinking_tokens` na resposta, que informa quantos dos tokens de saída cobrados foram raciocínio interno. Ao usar streaming, esse detalhamento aparece apenas no evento final `message_delta`.

Quando você estiver pronto para deixar os orçamentos manuais, consulte [Migrando para o pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking#migrating-to-adaptive-thinking).

## Pensamento intercalado no modo manual

O "interleaved thinking" (pensamento intercalado) permite que Claude pense entre chamadas de ferramentas dentro de um único turno do assistente, raciocinando sobre cada resultado de ferramenta antes de determinar o que fazer em seguida. Para o conceito, a estrutura do turno e como ele se comporta em modelos com pensamento adaptativo, consulte [pensamento intercalado](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#interleaved-thinking) na visão geral do pensamento. Esta seção aborda como ativá-lo quando você usa o pensamento manual `type: "enabled"`.

No Claude Opus 4.5, no Claude Sonnet 4.5 (descontinuado) e em modelos Claude 4 anteriores, adicione o [cabeçalho beta](https://platform.claude.com/docs/pt-BR/api/beta-headers) `interleaved-thinking-2025-05-14` à sua requisição de API.

A geração 4.6 se divide no modo manual:

* **Claude Sonnet 4.6**: o cabeçalho beta com `type: "enabled"` manual ainda funciona, mas está descontinuado. Prefira o [pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking), que intercala automaticamente sem cabeçalho.
* **Claude Opus 4.6**: o modo manual não tem pensamento intercalado algum. Apenas seu modo adaptativo intercala, então mude para `thinking: {type: "adaptive"}` se você precisar de raciocínio entre chamadas de ferramentas neste modelo.

O Claude Haiku 4.5 não suporta pensamento intercalado. Na Claude API, o cabeçalho beta é aceito, mas ignorado.

Mais duas considerações sobre o pensamento intercalado no modo manual:

* `budget_tokens` pode exceder `max_tokens` aqui; as [regras do orçamento](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking#budget-rules-and-tuning) explicam essa exceção.
* 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).

A forma como as plataformas tratam o cabeçalho beta difere. A Claude API e a [Claude Platform on AWS](https://platform.claude.com/docs/pt-BR/build-with-claude/claude-platform-on-aws) aceitam `interleaved-thinking-2025-05-14` em qualquer modelo e o ignoram onde não é suportado. Aceitação não é o mesmo que efeito: em modelos que rejeitam `type: "enabled"` (4.7 e posteriores) ou que não têm intercalação no modo manual (Claude Opus 4.6), o cabeçalho não tem efeito no modo manual; o pensamento adaptativo intercala automaticamente nesses casos.

Plataformas operadas por parceiros ([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)) também aceitam o cabeçalho em qualquer modelo sem retornar erro e o ignoram em modelos que não suportam pensamento intercalado.

## Estrutura de turnos no modo manual

As regras gerais de estrutura de turnos, incluindo o loop de uso de ferramentas em um único turno, o tratamento de conflitos no meio do turno e a alternância do pensamento entre turnos, estão em [Pensamento com uso de ferramentas](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-with-tool-use).

O modo manual adiciona um requisito: o turno final do assistente em uma requisição com pensamento ativado deve começar com um bloco de pensamento (o [pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking) elimina esse requisito). Alterar a configuração de pensamento entre turnos também invalida o cache de prompt; consulte a seção a seguir.

## Cache de prompt no modo manual

O modo manual adiciona uma regra além do comportamento de cache neutro em relação ao modo descrito em [pensamento e cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-prompt-caching): alterar `budget_tokens` entre requisições invalida os pontos de interrupção do cache, assim como alternar modos de pensamento, porque o valor do orçamento é renderizado no prompt. Pontos de interrupção no nível de mensagem sempre falham após uma mudança de orçamento; se os pontos de interrupção de ferramentas e do prompt do sistema também falham depende de onde o modelo renderiza a configuração.

Na prática, escolha um orçamento e mantenha-o estável durante toda a vida de uma conversa em cache. Executar uma conversa de vários turnos com cache no nível de mensagem no Claude Sonnet 4.6 e alterar o orçamento na terceira requisição de 4.000 para 8.000 tokens mostra a invalidação diretamente:

```text Output wrap
First request - establishing cache
First response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 17, output_tokens: 700 }

Second request - same thinking parameters (cache hit expected)
Second response usage: { cache_creation_input_tokens: 0, cache_read_input_tokens: 1370, input_tokens: 303, output_tokens: 874 }

Third request - different thinking budget (cache miss expected)
Third response usage: { cache_creation_input_tokens: 1370, cache_read_input_tokens: 0, input_tokens: 747, output_tokens: 619 }
```

A terceira requisição recria o cache (`cache_creation_input_tokens=1370`, `cache_read_input_tokens=0`) porque o orçamento mudou entre as requisições. Para uma versão executável do mesmo experimento no modo adaptativo, em que o nível de effort desempenha o papel de cache que `budget_tokens` desempenha aqui, consulte [Cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost#prompt-caching) na página de direcionamento.

## Mecânicas compartilhadas

A maior parte do comportamento do pensamento é neutra em relação ao modo e está documentada uma única vez na página [Pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking). Tudo o que está lá também se aplica ao modo manual:

* [Controlando a exibição do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#controlling-thinking-display)
* [Streaming do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#streaming-thinking)
* [Pensamento com uso de ferramentas](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-with-tool-use), incluindo [preservação de blocos de pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#preserving-thinking-blocks)
* [Pensamento e cache de prompt](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-prompt-caching)
* [Pensamento e a janela de contexto](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-and-the-context-window)
* [Criptografia do pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking#thinking-encryption)
* [Preços](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost#pricing) (na página [Direcionando o pensamento](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost))

## Migrando para o pensamento adaptativo

Se o seu modelo suporta apenas o pensamento estendido (Claude Sonnet 4.5 (descontinuado), Claude Opus 4.5, Claude Haiku 4.5 e modelos Claude 4 anteriores), nenhuma ação é necessária agora: o pensamento adaptativo não está disponível nesses modelos, e `type: "adaptive"` [retorna um erro 400](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-troubleshooting#error-thinking-type-adaptive). Mantenha `budget_tokens` até passar para um modelo que suporte o pensamento adaptativo e, então, aplique o mapeamento a seguir.

Você precisa migrar de `type: "enabled"` se:

* Você usa o Claude Opus 4.6 ou o Claude Sonnet 4.6, em que `budget_tokens` está descontinuado.
* Você usa o Claude 4.7 ou um modelo posterior, como Claude Opus 5.5, Claude Sonnet 5, Claude Sonnet 5.5, Claude Fable 5.1 ou Claude Haiku 5.5, em que `type: "enabled"` retorna um erro 400.

O mapeamento é pequeno: remova `budget_tokens`, defina `thinking: {type: "adaptive"}` e controle a profundidade do raciocínio com `output_config: {effort: ...}` em vez de um orçamento de tokens.

```json
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 10000
  }
}
```

torna-se:

```json
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 16000,
  "thinking": {
    "type": "adaptive"
  },
  "output_config": {
    "effort": "high"
  }
}
```

`effort: "high"` é o padrão no Claude Sonnet 4.6, portanto omiti-lo aqui produz um comportamento idêntico; ele aparece apenas para mostrar onde fica o controle de profundidade no modo adaptativo. O Claude Opus 5.5 e o Claude Haiku 5.5 têm `"medium"` como padrão, e outros modelos que suportam effort têm `"high"` como padrão (consulte [Níveis de esforço](https://platform.claude.com/docs/pt-BR/build-with-claude/effort#effort-levels)).

Espere uma diferença de comportamento, não apenas uma mudança de sintaxe. Com um orçamento fixo, Claude pensa em todas as requisições. Com o pensamento adaptativo, Claude determina se e quanto pensar em cada requisição e, em configurações de [effort](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) mais baixas, pode pular o pensamento completamente em entradas fáceis. Você também pode remover o cabeçalho beta `interleaved-thinking-2025-05-14` após a migração: o pensamento adaptativo intercala automaticamente, e a Claude API ignora o cabeçalho nesses modelos. A preservação de blocos de pensamento também muda: o Claude Opus 4.5 e os modelos numerados 4.6 e superiores mantêm os blocos de pensamento de turnos anteriores no contexto e os cobram como entrada, enquanto o Claude Sonnet 4.5 (descontinuado), o Claude Haiku 4.5 e modelos anteriores os removiam; 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).

Alternar modos é uma mudança de configuração de pensamento, portanto a primeira requisição após a troca invalida os pontos de interrupção do cache, conforme descrito em [Cache de prompt no modo manual](https://platform.claude.com/docs/pt-BR/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching).

Para orientação completa, consulte [pensamento adaptativo](https://platform.claude.com/docs/pt-BR/build-with-claude/thinking), [effort](https://platform.claude.com/docs/pt-BR/build-with-claude/effort) e o [guia de migração de modelos](https://platform.claude.com/docs/pt-BR/about-claude/models/migration-guide).

## Próximos passos

<CardGroup cols={3}>
  <Card title="Pensamento" icon="brain" href="https://platform.claude.com/docs/pt-BR/build-with-claude/thinking">
    Saiba como o pensamento funciona: blocos, exibição, streaming e uso de ferramentas.
  </Card>

  <Card title="Direcionando o pensamento" icon="compass" href="https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-steering-and-cost">
    Deixe Claude determinar quando e quanto pensar em cada requisição.
  </Card>

  <Card title="Pensamento em fluxos de trabalho com ferramentas e vários turnos" icon="wrench" href="https://platform.claude.com/docs/pt-BR/build-with-claude/thinking-tool-workflows">
    Preserve blocos de pensamento e gerencie o pensamento entre chamadas de ferramentas e turnos.
  </Card>
</CardGroup>