> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Thinking Budgets
> Extended thinking token budgets for complex reasoning
Control how many tokens an agent spends on extended reasoning before producing a response.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.thinking import ThinkingBudget
agent = Agent(
name="DeepThinker",
instructions="Solve problems step by step.",
)
agent.thinking_budget = ThinkingBudget.high()
agent.start("Solve this optimisation problem...")
```
The user asks a hard reasoning question; the agent spends extended thinking tokens up to the configured ThinkingBudget before answering.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Thinking Budget Flow"
Task[📋 Complex Task] --> Budget[🧠ThinkingBudget]
Budget --> Agent[🤖 Agent]
Agent --> LLM[💠Extended Thinking]
LLM --> Response[✅ Final Answer]
end
classDef task fill:#6366F1,stroke:#7C90A0,color:#fff
classDef budget fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef llm fill:#189AB4,stroke:#7C90A0,color:#fff
classDef response fill:#10B981,stroke:#7C90A0,color:#fff
class Task task
class Budget budget
class Agent agent
class LLM llm
class Response response
```
## Quick Start
Use predefined levels via the `thinking_budget` property after creating the agent.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.thinking import ThinkingBudget
agent = Agent(name="Thinker", instructions="Reason carefully.")
agent.thinking_budget = ThinkingBudget.medium() # 8,000 tokens
agent.start("Explain quantum entanglement simply.")
```
Fine-tune token limits and adaptive scaling.
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
from praisonaiagents.thinking import ThinkingBudget
budget = ThinkingBudget(
max_tokens=12000,
min_tokens=1000,
adaptive=True,
max_time_seconds=120.0,
)
agent = Agent(name="CustomThinker", instructions="Solve complex problems.")
agent.thinking_budget = budget
agent.start("Design a load-balancing strategy.")
```
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant LLM
User->>Agent: Complex reasoning question
Agent->>LLM: Prompt + thinking budget (max_tokens)
LLM->>LLM: Extended thinking (up to budget)
LLM-->>Agent: Reasoned answer
Agent-->>User: Final response
```
| Phase | What happens |
| --------- | ------------------------------------------ |
| 1. Set | You assign a `ThinkingBudget` to the agent |
| 2. Think | The model reasons up to the token limit |
| 3. Answer | The agent returns the reasoned response |
## Budget Levels
Pre-configured levels for different task complexity:
| Level | Tokens | Use case |
| ----------- | ------ | ---------------- |
| `minimal()` | 2,000 | Quick answers |
| `low()` | 4,000 | Simple reasoning |
| `medium()` | 8,000 | Default balance |
| `high()` | 16,000 | Complex analysis |
| `maximum()` | 32,000 | Deep research |
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.thinking import ThinkingBudget
budget = ThinkingBudget.high()
tokens = budget.get_tokens_for_complexity(0.9) # scales with complexity
```
## CLI Usage
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai thinking status # Show current budget
praisonai thinking set high # Set budget level
praisonai thinking stats # Show usage statistics
```
### `praisonai run --thinking`
Pass `--thinking ` on the `praisonai run` command to set an exact token budget for a one-off prompt:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Use a numeric token budget
praisonai run --thinking 4096 "Explain quantum entanglement"
# Use a named level
praisonai run --thinking high "Solve this optimisation problem: ..."
# Use in --command mode
praisonai run --command my_agent.py --thinking 8000
```
`--thinking` is now correctly threaded through the direct-prompt path (`praisonai run`) in both `--command` and bare-prompt modes. Earlier releases raised a `NameError` on the direct-prompt path.
| Value | Tokens | Notes |
| --------- | ------ | --------------------------------- |
| `off` | 0 | Disable extended thinking |
| `minimal` | 2,000 | Quick answers |
| `low` | 4,000 | Simple reasoning |
| `medium` | 8,000 | Balanced |
| `high` | 16,000 | Complex analysis |
| `` | Exact | Any positive integer token budget |
For persistent sessions, use `praisonai thinking set ` instead.
***
## Usage Tracking
Track thinking utilisation across sessions:
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents.thinking import ThinkingBudget, ThinkingTracker
tracker = ThinkingTracker()
session = tracker.start_session(budget_tokens=8000)
tracker.end_session(session, tokens_used=5000, time_seconds=30.0)
summary = tracker.get_summary()
print(f"Average utilisation: {summary['average_utilization']:.1%}")
```
***
## Best Practices
Use `minimal()` or `low()` for quick lookups; reserve `high()` or `maximum()` for multi-step analysis where reasoning depth matters.
Assign `agent.thinking_budget` after creating the agent — budgets are applied lazily with zero overhead when unset.
Set `adaptive=True` so token allocation scales with task complexity via `get_tokens_for_complexity()`.
Use `praisonai thinking stats` to review utilisation before increasing budgets in production.
***
## Related
Manage overall token spend across agent runs
Self-review loops for higher-quality outputs