Extended Thinking
View original →Table of contents
- Setup
- Basic example
- Streaming with extended thinking
- Token counting and context window management
- Understanding redacted thinking
- Handling error cases
This notebook demonstrates how to use Claude's extended thinking feature on Claude Sonnet 5.5 with various examples and edge cases.
Extended thinking gives Claude enhanced reasoning capabilities for complex tasks, while also providing transparency into its step-by-step thought process before it delivers its final answer. 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.
On Claude Sonnet 5.5, thinking is adaptive: you pass thinking={"type": "adaptive"} (this is also the default when thinking is omitted) and the model decides how much to think for each request. You steer how hard it thinks with output_config={"effort": ...} ("low", "medium", "high", "xhigh", or "max"; the default is "high") rather than with a token budget. The older {"type": "enabled", "budget_tokens": N} form is not accepted on this model. For more information on extended thinking, see our documentation.
Setup
First, let's install the necessary packages and set up our environment.
%pip install anthropic
import anthropic
# Set your API key as an environment variable or directly
# os.environ["ANTHROPIC_API_KEY"] = "your-api-key-here"
# Initialize the client
client = anthropic.Anthropic()
# Helper functions
def print_thinking_response(response):
"""Pretty print a message response with thinking blocks."""
print("\n==== FULL RESPONSE ====")
for block in response.content:
if block.type == "thinking":
print("\n🧠 THINKING BLOCK:")
# Show truncated thinking for readability
print(block.thinking[:500] + "..." if len(block.thinking) > 500 else block.thinking)
print(f"\n[Signature available: {bool(getattr(block, 'signature', None))}]")
if hasattr(block, "signature") and block.signature:
print(f"[Signature (first 50 chars): {block.signature[:50]}...]")
elif block.type == "redacted_thinking":
print("\n🔒 REDACTED THINKING BLOCK:")
print(f"[Data length: {len(block.data) if hasattr(block, 'data') else 'N/A'}]")
elif block.type == "text":
print("\n✓ FINAL ANSWER:")
print(block.text)
print("\n==== END RESPONSE ====")
def count_tokens(messages):
"""Count tokens for a given message list."""
result = client.messages.count_tokens(model="claude-sonnet-5-5", messages=messages)
return result.input_tokens
Basic example
Let's start with a basic example to show extended thinking in action.
One detail to note before we start: on Claude Sonnet 5.5 the display setting for thinking defaults to "omitted", which returns thinking blocks with empty text (you still get the signature, and you are still billed for the thinking tokens). Because this notebook prints the reasoning, every request sets "display": "summarized" so the API returns a summary of Claude's thinking.
Adaptive also means Claude can decide a prompt needs no thinking at all, in which case the response simply has no thinking block. That is most likely on easy prompts and at lower effort. The examples below use a small constraint-satisfaction puzzle and "effort": "xhigh" so you reliably see thinking; the token-counting section later shows how the amount of thinking changes as you move effort from "low" to "xhigh".
def basic_thinking_example():
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=16000, # thinking tokens count toward max_tokens, so leave headroom
thinking={
"type": "adaptive",
"display": "summarized", # default is "omitted" (empty thinking text)
},
output_config={"effort": "xhigh"}, # low | medium | high (default) | xhigh | max
messages=[
{
"role": "user",
"content": "Five talks (A, B, C, D, E) must be scheduled in five consecutive slots. Constraints: A comes before C; B is not adjacent to D; E is neither first nor last; C is immediately before or after E; D comes before A. List every valid ordering and explain how you know there are no others.",
}
],
)
print_thinking_response(response)
basic_thinking_example()
Streaming with extended thinking
This example shows how to handle streaming with thinking:
def streaming_with_thinking():
with client.messages.stream(
model="claude-sonnet-5-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": "xhigh"},
messages=[
{
"role": "user",
"content": "Five talks (A, B, C, D, E) must be scheduled in five consecutive slots. Constraints: A comes before C; B is not adjacent to D; E is neither first nor last; C is immediately before or after E; D comes before A. List every valid ordering and explain how you know there are no others.",
}
],
) as stream:
# Track what we're currently building
current_block_type = None
current_content = ""
for event in stream:
if event.type == "content_block_start":
current_block_type = event.content_block.type
print(f"\n--- Starting {current_block_type} block ---")
current_content = ""
elif event.type == "content_block_delta":
if event.delta.type == "thinking_delta":
print(
event.delta.thinking, end="", flush=True
) # Just print dots for thinking to avoid clutter
current_content += event.delta.thinking
elif event.delta.type == "text_delta":
print(event.delta.text, end="", flush=True)
current_content += event.delta.text
elif event.type == "content_block_stop":
if current_block_type == "thinking":
# Just show a summary for thinking
print(f"\n[Completed thinking block, {len(current_content)} characters]")
elif current_block_type == "redacted_thinking":
print("\n[Redacted thinking block]")
print(f"--- Finished {current_block_type} block ---\n")
current_block_type = None
elif event.type == "message_stop":
print("\n--- Message complete ---")
streaming_with_thinking()
Token counting and context window management
This example demonstrates how to track token usage with extended thinking, and how the effort setting changes how much Claude thinks:
def token_counting_example():
# Define a function to create a sample prompt
def create_sample_messages():
messages = [
{
"role": "user",
"content": "Five talks (A, B, C, D, E) must be scheduled in five consecutive slots. Constraints: A comes before C; B is not adjacent to D; E is neither first nor last; C is immediately before or after E; D comes before A. List every valid ordering and explain how you know there are no others.",
}
]
return messages
# Count tokens without thinking
base_messages = create_sample_messages()
base_token_count = count_tokens(base_messages)
print(f"Base token count (input only): {base_token_count}")
# Make a request with thinking and check actual usage
max_tokens = 16000
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=max_tokens,
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": "xhigh"},
messages=base_messages,
)
# usage.output_tokens counts the *full* thinking plus the final answer,
# even though the thinking text we get back is only a summary.
summary_chars = sum(
len(block.thinking) for block in response.content if block.type == "thinking"
)
final_answer_tokens = sum(
len(block.text.split()) * 1.3 # Rough estimate
for block in response.content
if block.type == "text"
)
print(f"\nInput tokens (from usage): {response.usage.input_tokens}")
print(f"Output tokens (from usage, thinking + answer): {response.usage.output_tokens}")
print(f"Estimated final answer tokens: ~{int(final_answer_tokens)}")
print(
f"So roughly ~{response.usage.output_tokens - int(final_answer_tokens)} output tokens went to thinking"
)
print(f"Thinking summary returned: {summary_chars} characters")
print(
f"Input tokens + max_tokens = {base_token_count + max_tokens} (this total must fit in the model's context window)"
)
# Demo with escalating effort levels: same prompt, different effort.
# There is no token budget on current models; effort is the knob that
# trades thinking depth for latency and cost ("max" exists too). At the
# lower levels Claude may decide this problem needs no thinking at all,
# in which case the response has no thinking block.
for effort in ["low", "medium", "high", "xhigh"]:
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=max_tokens,
thinking={"type": "adaptive", "display": "summarized"},
output_config={"effort": effort},
messages=base_messages,
)
summary_chars = sum(len(b.thinking) for b in response.content if b.type == "thinking")
answer = " ".join(b.text for b in response.content if b.type == "text")
print(f"\nWith effort={effort!r}:")
print(f"Output tokens (thinking + answer): {response.usage.output_tokens}")
print(f"Thinking summary length: {summary_chars} characters")
print(f"Final answer preview: {answer[:120]}...")
# Uncomment to run the example
token_counting_example()
Understanding redacted thinking blocks
Occasionally Claude's internal reasoning will be flagged by safety systems. When this occurs, we encrypt some or all of the thinking block and return it to you as a redacted_thinking block. These redacted thinking blocks are decrypted when passed back to the API, allowing Claude to continue its response without losing context.
This example demonstrates working with redacted thinking blocks using a special test string that triggers them:
def redacted_thinking_example():
# Using the special test string that triggers redacted thinking
response = client.messages.create(
model="claude-sonnet-5-5",
max_tokens=16000,
thinking={"type": "adaptive", "display": "summarized"},
messages=[
{
"role": "user",
"content": "ANTHROPIC_MAGIC_STRING_TRIGGER_REDACTED_THINKING_46C9A13E193C177646C7398A98432ECCCE4C1253D5E2D82641AC0E52CC2876CB",
}
],
)
# Identify redacted thinking blocks
redacted_blocks = [block for block in response.content if block.type == "redacted_thinking"]
thinking_blocks = [block for block in response.content if block.type == "thinking"]
text_blocks = [block for block in response.content if block.type == "text"]
print(response.content)
print(f"Response includes {len(response.content)} total blocks:")
print(f"- {len(redacted_blocks)} redacted thinking blocks")
print(f"- {len(thinking_blocks)} regular thinking blocks")
print(f"- {len(text_blocks)} text blocks")
# Show data properties of redacted blocks
if redacted_blocks:
print("\nRedacted thinking blocks contain encrypted data:")
for i, block in enumerate(redacted_blocks[:3]): # Show first 3 at most
print(f"Block {i + 1} data preview: {block.data[:50]}...")
# Print the final text output
if text_blocks:
print("\nFinal text response:")
print(text_blocks[0].text)
# Uncomment to run the example
redacted_thinking_example()
Handling error cases
When using extended thinking, keep in mind:
- Effort, not budgets: Current models have no
budget_tokens. Useoutput_config={"effort": ...}to control how hard Claude thinks: start at the default ("high"), drop to"medium"or"low"when latency and cost matter more than depth, and reach for"xhigh"or"max"on the hardest problems. Sending the legacythinking={"type": "enabled", "budget_tokens": N}form to Claude Sonnet 5.5 returns a 400 error.
- Incompatible features: Non-default
temperature,top_p, ortop_kvalues are rejected on Claude Sonnet 5.5 (with or without thinking), and you cannot pre-fill assistant responses.
- Pricing and limits: Thinking tokens count towards
max_tokensand the context window, and are billed as output tokens (you are billed for the full thinking, not the summary you get back). They also count towards your rate limits. Keepmax_tokensgenerous and use streaming for very large values.
For more details on extended thinking with tool use, see the "Extended Thinking with Tool Use" notebook.
def demonstrate_common_errors():
# 1. Error from sending the legacy manual-budget form.
# Current models only accept {"type": "adaptive"}; non-default
# temperature / top_p / top_k values are rejected the same way.
try:
client.messages.create(
model="claude-sonnet-5-5",
max_tokens=4000,
thinking={
"type": "enabled", # Legacy form, not accepted on this model
"budget_tokens": 1024,
},
messages=[{"role": "user", "content": "Explain quantum computing."}],
)
except Exception as e:
print(f"\nError with legacy budget_tokens thinking config: {e}")
# 2. Error from exceeding context window
try:
# Create a very large prompt (large enough to overflow the context window)
long_content = "Please analyze this text. " + "This is sample text. " * 300000
client.messages.create(
model="claude-sonnet-5-5",
max_tokens=20000, # This plus the long prompt will exceed context window
thinking={"type": "adaptive"},
messages=[{"role": "user", "content": long_content}],
)
except Exception as e:
print(f"\nError from exceeding context window: {e}")
# Run the common error examples
demonstrate_common_errors()Related Articles
Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
A widespread practice in software development is to tailor coding agents to repositories using context files, such as AGENTS.md. Although this practice is strongly encouraged by agent developers,...
Agentic Context Engineering: Evolving Contexts for Self-Improving Language Models
Large language model (LLM) applications such as agents and domain-specific reasoning increasingly rely on context adaptation: modifying inputs with instructions, strategies, or evidence, rather than...
Tokalator: A Context Engineering Toolkit for Artificial Intelligence Coding Assistants
Artificial Intelligence (AI)-assisted coding environments operate within finite context windows of 128,000-1,000,000 tokens (as of early 2026), yet existing tools offer limited support for monitoring...
A Survey of Context Engineering for Large Language Models
The performance of Large Language Models (LLMs) is fundamentally determined by the contextual information provided during inference. This survey introduces Context Engineering, a formal discipline...