Extended thinking

Extended thinking gives Claude enhanced reasoning capabilities for complex tasks, while providing varying levels of transparency into its step-by-step thought process before it delivers its final answer. Whenever you enable Claude’s thinking mode, you will need to set a budget for the maximum number of tokens that Claude can use for its internal reasoning process.

The supported models are as follows:

Best practices and considerations for extended thinking

Usage guidelines

Performance considerations

Feature compatibility

Working with thinking budgets

How extended thinking works

When extended thinking is turned on, Claude creates thinking content blocks where it outputs its internal reasoning. Claude incorporates insights from this reasoning before crafting a final response. The API response will include thinking content blocks, followed by text content blocks.

Here’s an example of the default response format:

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

For more information about the response format of extended thinking, see Anthropic’s Messages API Request and Response.

How to use extended thinking

To turn on extended thinking, add a thinking object, with the thinking parameter set to enabled and the budget_tokens set to a specified token budget for extended thinking.

The budget_tokens parameter determines the maximum number of tokens Claude is allowed to use for its internal reasoning process. In Claude 4 models, this limit applies to full thinking tokens, and not to the summarized output. Larger budgets can improve response quality by enabling more thorough analysis for complex problems, although Claude might not use the entire budget allocated, especially at ranges above 32K.

The value of budget_tokens must be set to a value less than max_tokens. However, when using Interleaved thinking (beta) with tools, you can exceed this limit because the token limit becomes your entire context window (200K tokens).

Summarized thinking

With extended thinking enabled, the Messages API for Claude 4 models returns a summary of Claude’s full thinking process. Summarized thinking provides the full intelligence benefits of extended thinking, while preventing misuse.

Here are some important considerations for summarized thinking:

Streaming thinking

You can stream extended thinking responses using server-sent events (SSE). When streaming is enabled for extended thinking, you receive thinking content via thinking_delta events. Streamed events are not guaranteed to return at a constant rate. There can be delays between streaming events. For more documentation on streaming via the Messages API, see Streaming messages.

Here’s how to handle streaming with thinking using InvokeModelWithResponseStream:

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

Response:

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"}

Extended thinking with tool use

Extended thinking can be used alongside Tool use allowing Claude to reason through tool selection and results processing. When using extended thinking with tool use, be aware of the following limitations:

Here is how context window management works with tools:

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

The first response is the following:

{
    "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"
            }
        }
    ]
}

Continuing the conversation with tool use will generate another response. Notice that the thinking_block is passed in as well as the tool_use_block. If this is not passed in, an error occurs.

{
  "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"
            }
          ]
        }
      ]
    }

The API response will now only include text

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

Preserve thinking blocks

During tool use, you must pass thinking blocks back to the API, and you must include the complete unmodified block back to the API. This is critical for maintaining the model’s reasoning flow and conversation integrity.

When Claude invokes tools, it is pausing its construction of a response to await external information. When tool results are returned, Claude will continue building that existing response. This necessitates preserving thinking blocks during tool use, for the following reasons:

Interleaved thinking (beta)

Claude 4 models support interleaved thinking, a feature that enables Claude to think between tool calls and run more sophisticated reasoning after receiving tool results. This allows for more complex agentic interactions where Claude can do the following:

To enable interleaved thinking, add the beta header interleaved-thinking-2025-05-14 to your API request.

Extended thinking with prompt caching

Prompt caching with thinking has several important considerations:

Thinking block context removal

Cache invalidation patterns

Understanding thinking block caching behavior

When using extended thinking with tool use, thinking blocks exhibit specific caching behavior that affects token counting. The following sequence demonstrates how this works.

Here is a detailed example flow:

Request 1:

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

Response 1:

[thinking_block 1] + [tool_use block 1]

Request 2:

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

Response 2:

[thinking_block 2] + [text block 2]

Request 2 writes a cache of the request content (not the response). The cache includes the original user message, the first thinking block, tool use block, and the tool result.

Request 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]

Because a non-tool-result user block was included, all previous thinking blocks are ignored. This request will be processed the same as the following request:

Request 3 Alternate:

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]

This behavior is consistent whether using regular thinking or interleaved thinking.

Max tokens and context window size with extended thinking

In older Claude models (prior to Claude 3.7 Sonnet), if the sum of prompt tokens and max_tokens exceeded the model’s context window, the system would automatically adjust max_tokens to fit within the context limit. This meant you could set a large max_tokens value and the system would silently reduce it as needed. With Claude 3.7 and 4 models, max_tokens (which includes your thinking budget when thinking is enabled) is enforced as a strict limit. The system now returns a validation error if prompt tokens + max_tokens exceeds the context window size.

The context window with extended thinking

When calculating context window usage with thinking enabled, there are some considerations to be aware of:

The effective context window is calculated as: context window = (current input tokens - previous thinking tokens) + (thinking tokens + encrypted thinking tokens + text output tokens).

Managing tokens with extended thinking and tool use

When using extended thinking with tool use, thinking blocks must be explicitly preserved and returned with the tool results. The effective context window calculation for extended thinking with tool use becomes the following:

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

Managing tokens with extended thinking

Given the context window and max_tokens behavior with extended thinking Claude 3.7 and 4 models, you might need to perform one of the following actions:

Extended thinking token cost considerations

The thinking process incurs charges for the following:

The budget_tokens parameter determines the maximum number of tokens Claude is allowed to use for its internal reasoning process. Larger budgets can improve response quality by enabling more thorough analysis for complex problems, although Claude may not use the entire budget allocated, especially at ranges above 32K.

With interleaved thinking, the budget_tokens can exceed the max_tokens parameter as it represents the total budget across all thinking blocks within one assistant turn.

When using summarized thinking, keep the following information in mind: