As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Raciocínio estendido

O pensamento estendido fornece recursos Claude aprimorados de raciocínio para tarefas complexas, ao mesmo tempo em que fornece níveis variados de transparência em seu processo de step-by-step pensamento antes de fornecer sua resposta final. Sempre que você habilitar o modo de raciocínio do Claude, precisará definir um orçamento para o número máximo de tokens que o Claude pode usar no processo de raciocínio interno.

Os modelos compatíveis são os seguintes:

Práticas recomendadas e considerações para raciocínio estendido

Diretrizes de uso

Considerações sobre a performance

Compatibilidade de recursos

Como trabalhar com orçamentos de raciocínio

Como funciona o raciocínio estendido

Quando o raciocínio estendido é ativado, o Claude cria blocos de conteúdo thinking nos quais ele produz seu raciocínio interno. O Claude incorpora insights desse raciocínio antes de elaborar uma resposta final. A resposta da API incluirá blocos de conteúdo thinking, seguidos de blocos de conteúdo text.

Veja um exemplo do formato de resposta padrão:

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

Para ter mais informações sobre o formato de resposta do raciocínio estendido, consulte a API Messages da Anthropic em Solicitação e reposta.

Como usar o raciocínio estendido

Para ativar o raciocínio estendido, adicione um objeto thinking, com o parâmetro thinking definido como habilitado e budget_tokens definido como um orçamento simbólico especificado para o raciocínio estendido.

O parâmetro budget_tokens determina o número máximo de tokens do Claude que podem ser usados no processo interno de raciocínio. No modelos Claude 4, esse limite se aplica aos tokens de raciocínio completo, e não à saída resumida. Orçamentos maiores podem melhorar a qualidade da resposta, permitindo uma análise mais completa de problemas complexos, embora exista a possibilidade de o Claude não usar todo o orçamento alocado, especialmente em limites acima de 32 mil.

O valor de budget_tokens deve ser definido como um valor menor que max_tokens. No entanto, ao usar o Raciocínio intercalado (beta) com ferramentas, você pode exceder esse limite porque o limite de tokens se torna a janela de contexto completa (200 mil tokens).

Raciocínio resumido

Com o raciocínio estendido habilitado, a API Messages para os modelos Claude 4 exibe um resumo do processo de raciocínio completo do Claude. O raciocínio resumido oferece todos os benefícios de inteligência do raciocínio estendido, ao mesmo tempo que evita o uso indevido.

Estas são algumas considerações importantes sobre o raciocínio resumido:

Streaming de raciocínio

É possível transmitir respostas de raciocínio estendido usando eventos enviados pelo servidor (SSE). Quando o streaming está habilitado para o raciocínio estendido, você recebe conteúdo de raciocínio por meio de eventos thinking_delta. Não é garantido que os eventos transmitidos sejam exibidos a uma taxa constante. Pode haver atrasos entre os eventos de streaming. Para ver outra documentação sobre streaming por meio da API Messages, consulte Streaming messages.

Veja como lidar com o streaming pensando usando InvokeModelWithResponseStream:

{
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": 10000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 4000
    },
    "messages": [
        {
            "role": "user",
            "content": "What is 27 * 453?"
        }
    ]
}

Resposta:

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

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

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "Let me solve this step by step:\n\n1. First break down 27 * 453"}}

event: content_block_delta
data: {"type": "content_block_delta", "index": 0, "delta": {"type": "thinking_delta", "thinking": "\n2. 453 = 400 + 50 + 3"}}

// Additional thinking deltas...

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

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

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

event: content_block_delta
data: {"type": "content_block_delta", "index": 1, "delta": {"type": "text_delta", "text": "27 * 453 = 12,231"}}

// Additional text deltas...

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

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

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

Raciocínio estendido com o uso de ferramentas

O raciocínio estendido pode ser usado com Uso de ferramentas, permitindo que o Claude raciocine por meio da seleção de ferramentas e do processamento de resultados. Ao usar o raciocínio estendido com o uso de ferramentas, esteja ciente das seguintes limitações:

Veja como o gerenciamento de janelas de contexto funciona com ferramentas:

{
    "anthropic_version": "bedrock-2023-05-31",
    "max_tokens": 10000,
    "thinking": {
        "type": "enabled",
        "budget_tokens": 4000
    },
  "tools": [
  {
    "name": "get_weather",
    "description": "Get current weather for a location",
    "input_schema": {
      "type": "object",
      "properties": {
        "location": {
          "type": "string"
        }
      },
      "required": [
        "location"
      ]
    }
  }
],
    "messages": [
        {
            "role": "user",
            "content": "What's the weather in Paris?"
        }
    ]
}

A primeira resposta é a seguinte:

{
    "content": [
        {
            "type": "thinking",
            "thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`...",
            "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxYsNrcs...."
        },
        {
            "type": "text",
            "text": "I can help you get the current weather information for Paris. Let me check that for you"
        },
        {
            "type": "tool_use",
            "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
            "name": "get_weather",
            "input": {
                "location": "Paris"
            }
        }
    ]
}

Se a conversa for continuada com o uso de ferramentas, será gerada outra resposta. Observe que thinking_block é transmitido, assim como tool_use_block. Se isso não for transmitido, ocorrerá um erro.

{
  "anthropic_version": "bedrock-2023-05-31",
  "max_tokens": 10000,
  "thinking": {
    "type": "enabled",
    "budget_tokens": 4000
  },
  "tools": [
    {
      "name": "get_weather",
      "description": "Get current weather for a location",
      "input_schema": {
        "type": "object",
        "properties": {
          "location": {
            "type": "string"
          }
        },
        "required": [
          "location"
        ]
      }
    }
  ],
      "messages": [
        {
          "role": "user",
          "content": "What's the weather in Paris?"
        },
        {
          "role": "assistant",
          "content": [
            {
              "type": "thinking",
              "thinking": "The user wants to know the current weather in Paris. I have access to a function `get_weather`…",
              "signature": "BDaL4VrbR2Oj0hO4XpJxT28J5TILnCrrUXoKiiNBZW9P+nr8XSj1zuZzAl4egiCCpQNvfyUuFFJP5CncdYZEQPPmLxY",
            },
            {
              "type": "tool_use",
              "id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
              "name": "get_weather",
              "input": {
                "location": "Paris"
              }
            }
          ]
        },
        {
          "role": "user",
          "content": [
            {
              "type": "tool_result",
              "tool_use_id": "toolu_01CswdEQBMshySk6Y9DFKrfq",
              "content": "Current temperature: 88°F"
            }
          ]
        }
      ]
    }

Agora a resposta da API incluirá apenas texto.

{
  "content": [
    {
      "type": "text",
      "text": "Currently in Paris, the temperature is 88°F (31°C)"
    }
  ]
}

Preservar blocos de raciocínio

Durante o uso da ferramenta, você deve transmitir os blocos de raciocínio de volta à API e incluir novamente o bloco completo não modificado na API. Isso é fundamental para manter o fluxo de raciocínio e a integridade da conversa do modelo.

Quando o Claude invoca ferramentas, ele pausa a criação de uma resposta para aguardar informações externas. Quando os resultados da ferramenta são exibidos, o Claude continua criando a resposta existente. Isso exige a preservação dos blocos de raciocínio durante o uso da ferramenta, pelos seguintes motivos:

Raciocínio intercalado (beta)

Os modelos Claude 4 oferecem raciocínio intercalado, um recurso que permite que o Claude reflita entre as chamadas de ferramenta e raciocine de uma maneira mais elaborada depois de receber os resultados da ferramenta. Isso permite interações agênticas mais complexas nas quais o Claude pode fazer o seguinte:

Para permitir o raciocínio intercalado, adicione o cabeçalho beta interleaved-thinking-2025-05-14 à solicitação de API.

Limpeza de blocos de pensamento (beta)

A eliminação de blocos de pensamento é uma capacidade do modelo Anthropic Claude (em versão beta). Com esse recurso, Claude pode eliminar automaticamente os bloqueios de pensamento mais antigos dos turnos anteriores. Para usar a limpeza de blocos do Thinking, você precisa adicionar context-management-2025-06-27 à lista de cabeçalhos beta no parâmetro de solicitação anthropic_beta. Você também precisará especificar o uso clear_thinking_20251015 e escolher entre as seguintes opções de configuração.

Esses são os controles disponíveis para a estratégia de gerenciamento de contexto clear_thinking_20251015. Todos são opcionais ou têm padrões:

Request

{
      "anthropic_version": "bedrock-2023-05-31",
      "max_tokens": 10000,
      "anthropic_beta": [
        "context-management-2025-06-27"
      ],
      "thinking": {
        "type": "enabled",
        "budget_tokens": 4000
      },
      "tools": [
        {
          "name": "get_weather",
          "description": "Get current weather for a location",
          "input_schema": {
            "type": "object",
            "properties": {
              "location": {
                "type": "string"
              }
            },
            "required": [
              "location"
            ]
          }
        }
      ],
      "messages": [
        {
          "role": "user",
          "content": "What's the weather in Paris?"
        },
        {
          "role": "assistant",
          "content": [
            {
              "type": "thinking",
              "thinking": "The user is asking for the weather in Paris. I have access to a get_weather function that takes a location as a parameter. I have all the information I need to make this call - the location is \"Paris\".\n\nLet me call the get_weather function with \"Paris\" as the location.",
              "signature": "ErgDCkgIChABGAIqQC/Ccv8GC+5VfcMEiq78XmpU2Ef2cT+96pHKMedKcRNuPz1x0kFlo5HBpW0r1NcQFVQUPuj6PDmP7jdHY7GsrUwSDKNBMogjaM7wYkwfPhoMswjlmfF09JLjZfFlIjB03NkghGOxLbr3VCQHIY0lMaV9UBvt7ZwTpJKzlz+mulBysfvAmDfcnvdJ/6CZre4qnQJsTZaiXdEgASwPIc5jOExBguerrtYSWVC/oPjSi7KZM8PfhP/SPXupyLi8hwYxeqomqkeG7AQhD+3487ecerZJcpJSOSsf0I1OaMpmQEE/b7ehnvTV/A4nLhxIjP4msyIBW+dVwHNFRFlpJLBHUJvN99b4run6YmqBSf4y9TyNMfOr+FtfxedGE0HfJMBd4FHXmUFyW5y91jAHMWqwNxDgacaKkFCAMaqce5rm0ShOxXn1uwDUAS3jeRP26Pynihq8fw5DQwlqOpo7vvXtqb5jjiCmqfOe6un5xeIdhhbzWddhEk1Vmtg7I817pM4MZjVaeQN02drPs8QgDxihnP6ZooGhd6FCBP2X3Ymdlj5zMlbVHxmSkA4wcNtg4IAYAQ=="
            },
            {
              "type": "tool_use",
              "id": "toolu_bdrk_01U7emCvL5v5z5GT7PDr2vzc",
              "name": "get_weather",
              "input": {
                "location": "Paris"
              }
            }
          ]
        },
        {
          "role": "user",
          "content": [
            {
              "type": "tool_result",
              "tool_use_id": "toolu_bdrk_01U7emCvL5v5z5GT7PDr2vzc",
              "content": "Current temperature: 88°F"
            }
          ]
        }
      ],
      "context_management": {
        "edits": [
          {
            "type": "clear_thinking_20251015",
            "keep": {
              "type": "thinking_turns",
              "value": 1
            }
          }
        ]
      }
    }

Response

{
      "model": "claude-haiku-4-5-20251001",
      "id": "msg_bdrk_01KyTbyFbdG2kzPwWMJY1kum",
      "type": "message",
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "The current weather in Paris is **88°F** (approximately 31°C). It's quite warm! If you need more detailed information like humidity, wind conditions, or a forecast, please let me know."
        }
      ],
      "stop_reason": "end_turn",
      "stop_sequence": null,
      "usage": {
        "input_tokens": 736,
        "cache_creation_input_tokens": 0,
        "cache_read_input_tokens": 0,
        "cache_creation": {
          "ephemeral_5m_input_tokens": 0,
          "ephemeral_1h_input_tokens": 0
        },
        "output_tokens": 47
      },
      "context_management": {
        "applied_edits": [...]
      }
    }

Raciocínio estendido com o armazenamento em cache de prompts

Há várias considerações importantes sobre o armazenamento em cache de prompts com raciocínio:

Remoção do contexto do bloco de raciocínio

Padrões de invalidação de cache

Noções básicas sobre o comportamento do armazenamento em cache de blocos de raciocínio

Ao usar o raciocínio estendido com o uso de ferramentas, os blocos de raciocínio exibem um comportamento específico de armazenamento em cache que afeta a contagem de tokens. A sequência a seguir demonstra como isso funciona.

Veja aqui um exemplo detalhado de fluxo:

Solicitação 1:

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

Resposta 1:

[thinking_block 1] + [tool_use block 1]

Solicitação 2:

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

Resposta 2:

[thinking_block 2] + [text block 2]

A solicitação 2 grava o conteúdo da solicitação em cache (não da resposta). O cache inclui a mensagem original do usuário, o primeiro bloco de raciocínio, o bloco de uso da ferramenta e o resultado da ferramenta.

Solicitação 3:

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

Como um bloco de non-tool-result usuário foi incluído, todos os blocos de pensamento anteriores são ignorados. Essa solicitação será processada da mesma forma que a seguinte solicitação:

Alternativa à solicitação 3:

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]

Esse comportamento é consistente, seja usando o raciocínio regular ou o raciocínio intercalado.

Máximo de tokens e tamanho da janela de contexto com raciocínio estendido

Nos modelos Claude mais antigos (anteriores ao Claude 3.7 Sonnet), se a soma de tokens de prompt e max_tokens excedesse a janela de contexto do modelo, o sistema ajustava automaticamente max_tokens de acordo com o limite de contexto. Isso significava que, embora você pudesse definir um grande valor para max_tokens, o sistema o reduziria silenciosamente conforme a necessidade. Com os modelos Claude 3.7 e 4, max_tokens (que inclui seu orçamento de raciocínio quando o raciocínio está habilitado), é imposto como um limite estrito. O sistema agora exibirá um erro de validação se tokens de prompts + max_tokens exceder o tamanho da janela de contexto.

A janela de contexto com raciocínio estendido

Ao calcular o uso da janela de contexto com o raciocínio habilitado, é necessário considerar o seguinte:

A janela de contexto efetiva é calculada como: janela de contexto = (tokens de entrada atuais - tokens de raciocínio anteriores) + (tokens de raciocínio + tokens de raciocínio criptografados + tokens de saída de texto).

Gerenciar tokens com raciocínio estendido e uso de ferramentas

Ao usar o raciocínio estendido com o uso de ferramentas, os blocos de raciocínio devem ser explicitamente preservados e exibidos com os resultados da ferramenta. O cálculo efetivo da janela de contexto para o raciocínio estendido com uso de ferramentas torna-se o seguinte:

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

Gerenciar tokens com raciocínio estendido

Considerando a janela de contexto e o comportamento de max_tokens dos modelos de raciocínio estendido Claude 3.7 e 4, talvez seja necessário realizar uma das seguintes ações:

Considerações sobre o custo de tokens de raciocínio estendido

O processo de raciocínio incorre em cobranças para o seguinte:

O parâmetro budget_tokens determina o número máximo de tokens do Claude que podem ser usados no processo interno de raciocínio. Orçamentos maiores podem melhorar a qualidade da resposta, permitindo uma análise mais completa de problemas complexos, embora o Claude possa não usar todo o orçamento alocado, especialmente em limites acima de 32 mil.

Com o raciocínio intercalado, budget_tokens pode exceder o parâmetro max_tokens, pois representa o orçamento total em todos os blocos de raciocínio em um turno do assistente.

Ao usar o raciocínio resumido, lembre-se das seguintes informações: