Reasoning Effort

One graded knob (off → high) that maps to each provider's native reasoning control and persists across sessions

Set how hard the model thinks with one graded level; PraisonAI translates it to each provider’s native reasoning control.

from praisonaiagents import Agent

agent = Agent(
    instructions="Solve tricky problems step by step.",
    llm="openai/gpt-5",
    reasoning_effort="high",
)
agent.start("Design a load balancer for a spiky workload.")

Quick Start

1. Enable with a level

   Pass a graded level to the agent.

   from praisonaiagents import Agent
   
   agent = Agent(
       instructions="Solve tricky problems step by step.",
       llm="openai/gpt-5",
       reasoning_effort="high",
   )
   agent.start("Design a load balancer for a spiky workload.")

2. Switch provider, same level

   The same level works on Anthropic and produces an extended-thinking budget under the hood.

   from praisonaiagents import Agent
   
   agent = Agent(
       instructions="Solve tricky problems step by step.",
       llm="anthropic/claude-3-7-sonnet",
       reasoning_effort="high",
   )
   agent.start("Design a load balancer for a spiky workload.")

3. Turn it off

   off is a zero-overhead no-op.

   from praisonaiagents import Agent
   
   agent = Agent(
       instructions="Answer directly.",
       llm="openai/gpt-5",
       reasoning_effort="off",
   )
   agent.start("What is the capital of France?")

4. Change it after construction

   The setter keeps a cached LLM in sync.

   from praisonaiagents import Agent
   
   agent = Agent(instructions="Reason carefully.", llm="openai/gpt-5")
   agent.reasoning_effort = "low"
   agent.start("Summarise this in one line.")

   The setter also updates an already-built LLM in place, so a change after the instance materialises still lands on the next request.

   from praisonaiagents import Agent
   
   agent = Agent(instructions="Reason carefully.", llm="openai/gpt-5")
   
   # Force the LLM to materialise (as `.start()` would).
   _ = agent.llm_instance
   
   # Change effort after materialisation — the very next request emits `high`.
   agent.reasoning_effort = "high"
   agent.start("Design a load balancer for a spiky workload.")

   The CLI --thinking <level> flag uses this same setter path internally, so the flag takes effect even when it is applied after the LLM has been built.

How It Works

Streaming

start(stream=True) (and iter_stream()) honour reasoning_effort on both streaming branches.

Since PR #4780, streaming and non-streaming produce identical provider requests for reasoning-effort semantics. The same resolve_reasoning_params mapping runs on both paths, so "off" stays a zero-overhead no-op, unset stays absent, and a model without a native reasoning control is untouched. Tool follow-up turns inherit the knob.

from praisonaiagents import Agent

agent = Agent(
    instructions="Solve tricky problems step by step.",
    llm="o4-mini",
    reasoning_effort="high",
)

for chunk in agent.start("Design a load balancer for a spiky workload.", stream=True):
    print(chunk, end="", flush=True)

Levels

Each level maps to a native parameter per provider family.

Provider Coverage

Which model families the level affects.

Which Level Should I Pick?

Match the level to the task.

Four Ways to Set It

The same level is available in Python, YAML, the CLI, and the Desktop app.

from praisonaiagents import Agent

agent = Agent(instructions="Solve tricky problems.", llm="openai/gpt-5", reasoning_effort="high")
agent.start("Design a load balancer for a spiky workload.")

agent:
  reasoning_effort: high

praisonai run --thinking high "Design a load balancer for a spiky workload."

Desktop app: Open Settings → Models → Reasoning effort and pick a level. Off is the default and leaves the provider default in place; any other level is forwarded on the next turn (same rule as temperature / top_p). The choice round-trips through settings.json, so it persists across restarts. It is app-wide, not per-chat. See Desktop → Models & API Keys.

Session Persistence

The effort you were running is persisted on the session and restored on resume — you do not need to pass --thinking again.

praisonai run --thinking high "start work"
# later:
praisonai run --continue "keep going"     # still runs at high

Backward Compatibility

thinking_budget remains a supported alias that folds into reasoning_effort.

from praisonaiagents import Agent

# Graded string alias.
agent = Agent(instructions="x", llm="openai/gpt-5", thinking_budget="high")

# Legacy int budget — normalised to the nearest level (8000 -> medium).
agent = Agent(instructions="x", llm="openai/gpt-5", thinking_budget=8000)

# Post-construction int still routes through the effort setter.
agent.thinking_budget = 16000

The graded value is what gets persisted, so the effort stays provider-portable.

agent.thinking_budget reads back the last integer budget that was set (or None); the graded string level always lives on agent.reasoning_effort. Assigning a graded string (agent.thinking_budget = "high") still routes through the effort setter, but agent.thinking_budget continues to report None in that case — read agent.reasoning_effort for the current level.

Best Practices

Related