Claude Extended Thinking in Practice: Migrating from budget_tokens to Adaptive Thinking (2026)

Extended thinking is Claude API's deep-reasoning mechanism: the model produces internal thinking blocks before answering, trading tokens for correctness. The defining change of 2026 is adaptive thinking — on Claude Sonnet 5 / Opus 5 and other newest models, the manual budget_tokens gearbox is replaced by a self-regulating one where the model decides how much to think. The migration window is dense with compatibility traps. Based on the AWS Bedrock official documentation as of September 2026 (the Anthropic API behaves identically), this guide covers the mechanics, a migration matrix, and tuning decisions.

TL;DR

• Old way: thinking: { type: "enabled", budget_tokens: N } — minimum 1,024, must be below max_tokens
• New way: thinking: { type: "adaptive" } plus output_config.effort (low / medium / high / xhigh / max)
• Fable 5 / Mythos 5 models are adaptive-only — the old syntax returns a 400; on Opus 4.6 / Sonnet 4.6 the old syntax is deprecated
• The biggest migration trap: on Sonnet 5 / Opus 5, omitting the thinking parameter turns adaptive thinking on by default — unchanged request bodies silently add a thinking bill billed as output tokens
• effort must live inside output_config — putting it inside the thinking object throws a ValidationException

Mechanics and billing: what budget_tokens actually counts

The manual gearbox adds a thinking object to the request:

{
  "thinking": {
    "type": "enabled",
    "budget_tokens": 8000
  },
  "max_tokens": 16000
}

Three hard rules: budget_tokens minimum is 1,024; it must be smaller than max_tokens (thinking counts against the output budget); the one exception is Interleaved thinking (beta) with tools, where the ceiling becomes the whole context window (200K tokens).

One billing detail trips people up — summarized thinking: on Claude 4 models the API returns a summary of the full thinking process, but you are billed for the full thinking tokens generated, not the summary's token count. "The thinking block in the response looks short" and "the bill is small" are different claims.

Other numbers worth knowing:

• Streaming requirement: streaming is required when max_tokens exceeds 21,333.
• Parameter exclusivity: thinking is incompatible with temperature / top_p / top_k modifications and forced tool use; you also cannot prefill the assistant response while thinking is enabled.
• No cleanup needed: the API automatically ignores thinking blocks from previous turns, and they don't count toward context usage.

The 2026 shift: what adaptive thinking is

Adaptive thinking lets Claude evaluate each request's complexity and decide whether and how much to think, instead of requiring a fixed budget. The official wording is blunt: adaptive reliably outperforms extended thinking with a fixed budget_tokens, and no beta header is needed.

The model support matrix (Bedrock docs, September 2026):

| Model | Adaptive | Manual extended thinking (budget_tokens) | Notes | |---|---|---|---| | Fable 5.1 / Mythos 5.1 / Mythos 5 / Fable 5 / Mythos Preview | ✅ only option | ❌ 400 | adaptive-only — even disabled is rejected | | Opus 5 / Sonnet 5 | ✅ (on by default) | ❌ ValidationException | disabled must be explicit; Opus 5 caps effort at high when disabled | | Opus 4.7 | ✅ | ❌ 400 | supports adaptive + disabled | | Opus 4.6 / Sonnet 4.6 | ✅ | ⚠️ deprecated | old syntax works but will be removed in a future model release | | Sonnet 4.5 / Opus 4.5 and older | ❌ | ✅ | manual only |

Migration: three syntaxes, one table

// Old: manual extended thinking (Sonnet 4.5 and earlier)
{ "thinking": { "type": "enabled", "budget_tokens": 8000 } }

// New: adaptive + effort (5-series / 4.6+)
{ "thinking": { "type": "adaptive" }, "output_config": { "effort": "high" } }

// New: turn thinking fully off (5-series / Opus 4.7 only)
{ "thinking": { "type": "disabled" } }

Three migration traps, ranked by how likely you are to hit them:

Trap 1: on Sonnet 5 / Opus 5, "pass nothing" means thinking is on. The docs call this out in bold: in the 4.6 era, omitting the thinking field ran without thinking; on 5-series the identical body runs adaptive and bills the thinking tokens as output tokens. Applications that only swapped the model ID will see cost and latency rise with no warning. The inverse trap: expressing "no thinking" as a tiny budget (budget_tokens) throws a ValidationException on Sonnet 5 — the only off switch is an explicit disabled. Recalibrate max_tokens too: it is now a hard cap over thinking plus answer.

Trap 2: effort in the wrong object. Effort belongs in a separate output_config object; nesting it inside thinking throws a ValidationException. The two objects look deceptively similar — this is the most common slip in migrated code.

Trap 3: still writing budget_tokens against 4.6. It doesn't error (deprecated-but-compatible), but it's technical debt: when a future model release removes it, that's a production incident. The 4.6 migration costs nothing — do it in the same pass.

Choosing among the five effort levels

| Level | Behavior | Available on | |---|---|---| | max | always thinks, no depth constraint | Opus 4.6 / Sonnet 4.6 / Opus 5 only | | xhigh | always thinks, extended depth | Opus 5 / Opus 4.6 only | | high (default) | always thinks, deep reasoning on complex tasks | all adaptive models | | medium | moderate thinking, may skip trivial queries | all | | low | minimal thinking, skips simple tasks | all |

Rules of thumb: start at high, tune down for cost and latency. The value of low / medium is that the model may skip — for simple tasks like ticket classification, skipping thinking is the win. max / xhigh are scarce: reserve them for genuine needs such as proofs, hard debugging, deep analysis; note that Opus 5 caps effort at high when thinking is disabled.

A hidden dividend: adaptive mode automatically enables Interleaved thinking (beta) — the model can think between tool calls, which is a real upgrade for agentic workflows (no more one-shot budget shredded by tool use).

Interaction with prompt caching

The caching deep dive covered thinking-and-caching once; here is the adaptive-era update:

• Changing thinking parameters invalidates message-prefix caches — the cache key includes the thinking configuration. Keep thinking config stable within a session, or place cache breakpoints at the system / tool layer.
• System prompt and tool caches survive thinking changes, so cache them independently with confidence.
• The cost-saving combo is unchanged: stable prefix + cache_control + an effort level chosen per task — not flip-flopping thinking configuration.

Decision framework: when to enable, and how much

Distilled from official guidance and practice:

• Worth it: multi-step math, architecture decisions, complex debugging, long analysis chains — any task where a wrong intermediate step guarantees a wrong answer.
• Not worth it: format conversion, classification, light rewriting — thinking only adds latency and cost; low lets the model skip on its own.
• Default on for agents: interleaved thinking makes between-tool-call reasoning a free upgrade, unless the task is purely mechanical.
• If unsure, start at high and watch success rate and unit cost before stepping down — the savings of a lower level are immediate; the benefit of a higher one depends on your task-difficulty distribution.

Related guides

• The full caching billing model: Claude Prompt Caching Deep Dive
• Messages API from zero: Claude API Getting Started
• Thinking inside agents: Claude Agent SDK Deep Dive
• Prompt-side reasoning techniques: Claude Prompt Engineering Guide

Frequently asked questions

What is the minimum budget_tokens, and how does it relate to max_tokens?

The minimum is 1,024, and it must be smaller than max_tokens — thinking counts against the output budget. The one exception is Interleaved thinking (beta) with tools, where the ceiling becomes the full 200K context window. Above roughly 32K, returns diminish and the model often leaves budget unused.

Which models are adaptive-only, and what happens with the old syntax?

Claude Fable 5.1, Mythos 5.1, Mythos 5, Fable 5, and Mythos Preview are adaptive-only — thinking.type: "enabled" or "disabled" returns a 400. Opus 4.7 supports adaptive + disabled (manual thinking is a 400); on Opus 4.6 / Sonnet 4.6 the manual syntax is deprecated; Sonnet 4.5 and older support the manual syntax only.

Why did my bill go up after migrating to Claude Sonnet 5?

On Sonnet 5 / Opus 5, omitting the thinking parameter means adaptive thinking runs by default — the opposite of Sonnet 4.6, where omitting it meant no thinking. Migrated applications pay for thinking tokens (billed as output) with a byte-identical request body. To turn it off you must explicitly send thinking: { type: "disabled" }, and recalibrate max_tokens while you're there.

Where does the effort parameter go in the request body?

Inside a separate output_config object — for example output_config: { effort: "high" } — never inside the thinking object, which returns a ValidationException. This is the most common mistake in migrated code.

Does changing thinking parameters invalidate the prompt cache?

It invalidates message-prefix caches that include the thinking configuration in the key; system prompt and tool caches are unaffected. The engineering answer: keep the thinking config stable within a session and design cache breakpoints at the system / tool layer.

Can extended thinking run with temperature or forced tool use?

No. Thinking is incompatible with temperature / top_p / top_k modifications and forced tool use, and responses cannot be prefilled while thinking is on. The agentic compensation is that adaptive mode automatically enables Interleaved thinking (beta) — the model can think between tool calls.

Official references

• AWS Bedrock — Adaptive thinking (model matrix and the five effort levels; primary source for this guide)
• AWS Bedrock — Extended thinking (budget_tokens and billing semantics)
• Anthropic — Extended thinking (first-party API docs)
• Anthropic — Thinking, steering, and cost

This article reflects the AWS Bedrock official documentation as of September 3, 2026 (the Anthropic API behaves identically). Adaptive thinking is evolving fast — the official docs win.