Use Extended Thinking

Giving Claude Room to Reason Before It Answers

Most of the answers in this course came straight from Claude's first pass at a problem. For many tasks that is enough. For harder ones, such as multi-step arithmetic, subtle code changes, or questions that require weighing several constraints, the quality of the answer improves when Claude reasons through the problem before writing its reply. Extended thinking is the feature that makes this reasoning available to your application.

When thinking is on, Claude produces a separate reasoning phase before its answer. That reasoning is returned as thinking blocks in the response content, ahead of the text blocks (Lesson 16). Your code can read those blocks, pass them back in later turns, and decide whether to show them to users. The reasoning is also billed as output tokens, which is the main cost to plan for.

This lesson explains the current configuration, the difference between adaptive and manual thinking, which models accept which setting, and how to validate a thinking configuration before sending it. Lesson 152 covers how to control the depth of thinking, and Lesson 153 covers how to read and preserve the blocks.

Two Modes: Adaptive and Manual

The API offers two ways to turn thinking on, and they differ in who decides how much to think:

The documentation describes adaptive thinking as the current mechanism. Claude determines how much reasoning a request needs, and the effort parameter steers that decision. Manual thinking is the earlier mechanism, in which a fixed budget is the ceiling for reasoning. Adaptive thinking is generally the better fit for current models, because the model allocates reasoning to the problem rather than to a number chosen in advance.

A minimal adaptive request looks like this:

response = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=4096,
    thinking={"type": "adaptive"},
    output_config={"effort": "medium"},
    messages=[{"role": "user", "content": "Is 1,001 prime? Show your reasoning briefly."}],
)

thinking decides whether reasoning happens. output_config.effort decides how much work the whole response receives, which in adaptive mode includes how deeply Claude thinks. The two are separate parameters, and they live in different places in the request.

Which Models Accept Which Mode

Not every model accepts every configuration, and the rules have changed across generations. Sending a configuration a model does not accept produces a 400 error, which is easy to avoid by checking before the request:

Two details in this table catch many teams. First, Claude Opus 5.5 thinks on every request, so a disabled setting is not valid there. Second, Claude Haiku 5.5 does not accept manual thinking at all, so code that worked on an earlier Haiku model will fail on it.

The documentation's advice for migration is direct: remove budget_tokens, set thinking to adaptive, and control depth with output_config.effort.

Validating the Configuration

Because the rules depend on the model, a small validator that checks the configuration before sending catches mistakes early. It does not replace the API's own checks, but it makes the rules visible and testable. The validator below encodes the groups from the table:

"""thinking_config.py: check a thinking configuration against the model's rules."""

LEGACY_MANUAL_ONLY = {"claude-sonnet-4-5", "claude-opus-4-5", "claude-haiku-4-5"}
TRANSITIONAL = {"claude-opus-4-6", "claude-sonnet-4-6"}
ADAPTIVE_ONLY = {"claude-opus-4-7", "claude-opus-4-8", "claude-opus-5", "claude-sonnet-5",
                 "claude-opus-5-5", "claude-sonnet-5-5", "claude-haiku-5-5", "claude-fable-5-1"}
ALWAYS_ON = {"claude-opus-5-5"}


def check_thinking(model: str, thinking: dict, max_tokens: int) -> list[str]:
    problems: list[str] = []
    kind = thinking.get("type")

    if model in ALWAYS_ON and kind == "disabled":
        problems.append(f"{model} always thinks; thinking cannot be disabled")
    if model in LEGACY_MANUAL_ONLY and kind == "adaptive":
        problems.append(f"adaptive thinking is not available on {model}; use enabled with budget_tokens")
    if model in ADAPTIVE_ONLY and kind == "enabled":
        problems.append(f"manual budget_tokens is not accepted on {model}; "
                        "use adaptive thinking with output_config.effort")
    if model in TRANSITIONAL and kind == "enabled":
        problems.append(f"budget_tokens is deprecated on {model}")

    if kind == "enabled":
        budget = thinking.get("budget_tokens")
        if budget is None:
            problems.append("enabled thinking needs budget_tokens")
        else:
            if budget < 1024:
                problems.append("budget_tokens must be at least 1024")
            if budget >= max_tokens:
                problems.append("budget_tokens must be less than max_tokens")
    return problems


if __name__ == "__main__":
    cases = [
        ("claude-opus-5-5", {"type": "adaptive"}, 4096),
        ("claude-opus-5-5", {"type": "enabled", "budget_tokens": 4096}, 8192),
        ("claude-sonnet-4-5", {"type": "enabled", "budget_tokens": 2048}, 4096),
        ("claude-sonnet-4-5", {"type": "adaptive"}, 4096),
        ("claude-sonnet-4-5", {"type": "enabled", "budget_tokens": 512}, 4096),
        ("claude-sonnet-4-6", {"type": "enabled", "budget_tokens": 4096}, 4096),
        ("claude-opus-5-5", {"type": "disabled"}, 4096),
    ]
    for number, (model, thinking, max_tokens) in enumerate(cases, start=1):
        print(f"case {number}:", check_thinking(model, thinking, max_tokens) or "ok")

Output:

case 1: ok
case 2: ['manual budget_tokens is not accepted on claude-opus-5-5; use adaptive thinking with output_config.effort']
case 3: ok
case 4: ['adaptive thinking is not available on claude-sonnet-4-5; use enabled with budget_tokens']
case 5: ['budget_tokens must be at least 1024']
case 6: ['budget_tokens is deprecated on claude-sonnet-4-6', 'budget_tokens must be less than max_tokens']
case 7: ['claude-opus-5-5 always thinks; thinking cannot be disabled']

How It Works

1. The model sets are the rules. Each set corresponds to a row of the table, so a new model is added in one place, and the checks follow.
2. The always-on check comes first for disabled, because that is the only configuration that can be rejected for every thinking-capable model in the ALWAYS_ON set.
3. Adaptive is rejected on legacy models, and manual is rejected on the adaptive-only models. The messages name the correct alternative, so the fix is obvious.
4. Manual budgets have their own rules. The budget must be at least 1024 and below max_tokens, because the reasoning and the answer share the output space. Case 6 shows both the deprecation and the size rule at once.
5. Problems are collected, not raised one at a time, so a configuration with several faults is fixed in one pass.

What Thinking Costs

Thinking tokens count toward max_tokens, so a limit set too low can leave no room for the answer. The reasoning is billed as output tokens, which is usually the more expensive side of the bill. A request with a small visible answer can still be costly if Claude reasoned at length, and that is why effort is worth tuning (Lesson 152). Budgeting for thinking means budgeting for output, not only for the text users see.

Thinking also affects caching. Changing the thinking configuration, or the effort level, invalidates cached message prefixes, as Lesson 127 described. A feature that switches between thinking settings on each request will not benefit from prompt caching on those requests.

Using Thinking in an Application

Enabling thinking changes the shape of the response. The content list now contains thinking blocks before the text. Code that reads content[0].text breaks, because the first block is the reasoning. The correct habit, from Lesson 42, is to select text blocks by type. Lesson 153 covers the thinking blocks themselves, including how to keep them intact across tool calls.

Thinking is most useful for tasks where a wrong answer is costly and the reasoning can be checked: analysis, planning, code review, and problems with several steps. For simple lookups, classification, and formatting, it adds cost and latency without improving the result, which is why the effort level should match the task.

Summary

Extended thinking gives Claude a reasoning phase before its answer. Current models use adaptive thinking, steered by effort, and older models use a manual token budget. Each model accepts only some configurations, so validation prevents avoidable errors. Thinking is billed as output, counts toward max_tokens, and invalidates cache prefixes when its settings change. The next lesson shows how to choose the effort level and, where it still applies, the manual budget.