Principle:Anthropics Anthropic sdk python Thinking Configuration
| Knowledge Sources | |
|---|---|
| Domains | Extended_Thinking, LLM, Reasoning |
| Last Updated | 2026-02-15 00:00 GMT |
Overview
Thinking Configuration is the principle of explicitly controlling how much computational budget a language model allocates to internal reasoning before producing a visible response. In the Anthropic Python SDK, this is expressed through a three-mode configuration system that governs chain-of-thought prompting at the API level.
The core insight is that complex problems benefit from allocating dedicated reasoning steps before the model commits to an answer. By exposing this as a configurable parameter, the SDK allows developers to trade off between response latency, token cost, and answer quality on a per-request basis.
Theory: Chain-of-Thought with Explicit Thinking Budgets
Chain-of-thought (CoT) prompting has been shown to improve language model performance on tasks requiring multi-step reasoning, arithmetic, logical deduction, and planning. Rather than relying on implicit internal reasoning, extended thinking makes this process explicit and controllable.
The key theoretical elements are:
- Reasoning Budget: A token-denominated budget that constrains how much internal reasoning the model performs before producing its final answer. Larger budgets allow more thorough analysis of complex problems but consume more tokens and increase latency.
- Separation of Concerns: The thinking process (internal reasoning) is separated from the text output (user-visible response). This allows the model to explore, backtrack, and self-correct during its thinking phase without polluting the final answer.
- Budget as Quality Lever: By adjusting the thinking budget, developers can tune the depth of analysis. Simple questions need minimal thinking; complex multi-step problems benefit from larger budgets.
The Three Thinking Modes
The SDK defines three distinct modes for thinking configuration, each serving a different use case:
Enabled Mode
In enabled mode, the developer explicitly specifies a token budget for thinking. The model will use up to that many tokens for its internal chain-of-thought reasoning before producing its answer.
Key constraints:
- The budget must be at least 1024 tokens (to ensure meaningful reasoning)
- The budget must be less than max_tokens (the overall response token limit)
- The model may use fewer tokens than the budget if the problem is simple
This mode gives the developer maximum control and predictability over reasoning costs.
Disabled Mode
In disabled mode, extended thinking is turned off entirely. The model produces its response without any explicit chain-of-thought reasoning. This is appropriate for:
- Simple, factual queries that do not require multi-step reasoning
- Latency-sensitive applications where thinking overhead is unacceptable
- Cost-sensitive applications where additional thinking tokens are unnecessary
Adaptive Mode
In adaptive mode, the model itself decides how much thinking budget to allocate based on the complexity of the input. This is the recommended default for most use cases because:
- The model can dynamically scale reasoning effort to match problem difficulty
- Simple questions get fast responses with minimal thinking
- Complex questions automatically receive deeper analysis
- It eliminates the need for developers to guess the right budget
Anthropic recommends adaptive mode as the preferred approach, particularly for newer models where it has been shown to produce better overall performance than a fixed budget.
The Budget Allocation Principle
The principle of budget allocation for reasoning follows a simple model:
- The developer sets a max_tokens ceiling for the entire response
- The developer optionally sets a budget_tokens ceiling for reasoning (enabled mode) or lets the model decide (adaptive mode)
- The model performs chain-of-thought reasoning within the budget
- The model produces its visible answer using the remaining token allocation
- The response contains both thinking blocks (reasoning trace) and text blocks (final answer)
This two-phase generation process -- reason first, then answer -- ensures that the model's final response is informed by its own explicit reasoning process.
Design Rationale
The three-mode design reflects a pragmatic approach to reasoning configuration:
- Union type pattern: The configuration is expressed as a discriminated union of three TypedDict variants, each identified by a
typefield. This makes the API self-documenting and type-safe. - Progressive complexity: Simple use cases (disabled, adaptive) require minimal configuration, while advanced use cases (enabled with specific budget) offer fine-grained control.
- Forward compatibility: The discriminated union pattern allows new thinking modes to be added in the future without breaking existing code.