TL;DR:
- Extended thinking gives Claude an internal scratchpad (hidden from the user) to reason through complex problems before answering — useful for multi-step agent tasks
- You control the token budget for thinking; larger budgets improve performance on hard tasks at the cost of latency and tokens
- It’s most valuable for planning, complex code generation, and disambiguation — not for fast retrieval or simple tool calls
Anthropic’s extended thinking mode is one of those features that looks like a nice-to-have until you hit the class of problems where it matters — and then it becomes essential. For agent workflows specifically, it unlocks a category of task quality that standard completions struggle with: coherent multi-step planning, accurate complex code generation, and reliable disambiguation when instructions are underspecified.
Here’s how to use it effectively.
What Extended Thinking Actually Does
When you enable extended thinking, Claude gets to write internal reasoning in <thinking> blocks before producing its final response. These blocks are returned in the API response but flagged as type: "thinking" — your application can display or discard them, but the model uses them to work through the problem.
The key parameter is budget_tokens — the maximum number of tokens Claude can spend on thinking. A budget of 1,024 is the minimum; 10,000–16,000 works well for most complex tasks; 32,000+ is for genuinely hard problems (long context analysis, complex multi-constraint code).
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
model="claude-opus-4-7", # Extended thinking requires Opus 4+
max_tokens=16000,
thinking={
"type": "enabled",
"budget_tokens": 10000
},
messages=[{
"role": "user",
"content": "Analyse this customer support transcript and identify: "
"1) the root cause of the complaint 2) what actions the agent "
"should have taken 3) a revised response. Transcript: ..."
}]
)
# Separate thinking blocks from response content
for block in response.content:
if block.type == "thinking":
print(f"[Internal reasoning: {len(block.thinking)} chars]")
elif block.type == "text":
print(block.text)The max_tokens parameter must be set high enough to accommodate both thinking and the actual response — a common mistake is setting max_tokens to 2,048 and wondering why the thinking budget isn’t being used.
Where It Makes the Biggest Difference in Agent Pipelines
1. Planning steps with ambiguous instructions
When a user prompt is underspecified — “refactor this codebase to improve maintainability” — standard completions produce the first reasonable interpretation. Extended thinking lets the model explicitly enumerate possible interpretations, weigh them against context, and commit to one before acting. This means fewer clarification loops and more coherent multi-file changes.
# Planning node in a LangGraph or similar pipeline
def planning_node(state):
response = client.messages.create(
model="claude-opus-4-7",
max_tokens=8000,
thinking={
"type": "enabled",
"budget_tokens": 5000 # Enough to reason through a plan
},
system="You are a software architect creating implementation plans. "
"Think carefully through trade-offs before committing to an approach.",
messages=[{
"role": "user",
"content": f"Create a step-by-step implementation plan for: {state['task']}\n"
f"Codebase context: {state['codebase_summary']}"
}]
)
plan_text = next(b.text for b in response.content if b.type == "text")
return {**state, "plan": plan_text}2. Complex code generation
For code tasks that require holding multiple constraints simultaneously — type safety, error handling, API contracts, performance — extended thinking substantially reduces the “looks right but breaks on edge cases” failure mode. The model works through each constraint explicitly rather than generating plausibly-correct code.
In practice, budget_tokens of 8,000–12,000 is the sweet spot for code generation tasks. Above that, you’re paying for increasingly marginal improvements.
3. Multi-document analysis
When an agent needs to synthesise information across several long documents before responding, extended thinking allows genuine cross-document reasoning rather than pattern-matching from the most recent context. Particularly useful for legal document review, financial analysis, and research summarisation agents.
When Not to Use Extended Thinking
Extended thinking adds latency and token cost to every call where it’s enabled. Don’t use it for:
- Simple retrieval: If the agent is just extracting a named entity or formatting data, thinking tokens are wasted
- Tool selection in tight loops: When an agent is cycling through tool calls, the overhead per call compounds quickly
- Fast streaming interfaces: Extended thinking produces a worse UX for real-time streaming applications where users expect near-instant first tokens
A pattern that works well is conditional thinking activation — routing to a thinking-enabled model only when a classifier determines the task is complex enough to benefit:
def should_use_extended_thinking(task: str, context_length: int) -> bool:
"""Simple heuristic — replace with a trained classifier in production"""
complex_indicators = [
"design", "architect", "analyse", "refactor", "compare",
"optimise", "debug complex", "explain why"
]
has_complex_indicator = any(kw in task.lower() for kw in complex_indicators)
is_long_context = context_length > 5000
return has_complex_indicator or is_long_context
def generate_response(task: str, context: str):
thinking_config = None
if should_use_extended_thinking(task, len(context)):
thinking_config = {"type": "enabled", "budget_tokens": 8000}
model = "claude-opus-4-7"
max_tokens = 12000
else:
model = "claude-haiku-4-5-20251001" # Faster and cheaper for simple tasks
max_tokens = 2000
params = {
"model": model,
"max_tokens": max_tokens,
"messages": [{"role": "user", "content": f"{task}\n\nContext: {context}"}]
}
if thinking_config:
params["thinking"] = thinking_config
return client.messages.create(**params)Streaming with Extended Thinking
Extended thinking is compatible with streaming, but the thinking blocks arrive as a stream of events before the text content. Handle them separately:
with client.messages.stream(
model="claude-opus-4-7",
max_tokens=8000,
thinking={"type": "enabled", "budget_tokens": 5000},
messages=[{"role": "user", "content": task}]
) as stream:
thinking_buffer = []
for event in stream:
if hasattr(event, 'type'):
if event.type == 'content_block_start':
if hasattr(event.content_block, 'type'):
current_block_type = event.content_block.type
elif event.type == 'content_block_delta':
if current_block_type == 'thinking':
thinking_buffer.append(event.delta.thinking)
elif current_block_type == 'text':
print(event.delta.text, end='', flush=True)Pricing and Cost Management
Extended thinking tokens are billed at the same input rate as the rest of the prompt. A budget_tokens of 10,000 on a task that actually uses 6,000 thinking tokens costs you 6,000 input tokens — the budget is a ceiling, not a flat charge.
For agent pipelines running at volume, track actual thinking token usage per task type over a week, then set budget_tokens to the 90th percentile of actual usage rather than a generous round number. Most tasks don’t hit their budget, and setting it accurately reduces the rare worst-case tail latency.
Extended thinking is a precision tool rather than a default setting. Identify the specific steps in your agent workflow where quality matters most — the planning phase, the final synthesis, the code generation node — and enable it selectively there. That’s where you’ll see the best return on the additional token spend.