Skip to main content
Planning makes agents create a step-by-step plan before executing, improving accuracy on complex multi-step tasks. 
from praisonaiagents import Agent

agent = Agent(
    name="Assistant",
    instructions="You help users with research and analysis tasks.",
    planning=True,
)

agent.start("Research the top 5 electric vehicle manufacturers and compare their market share.")
The user asks a multi-step question; the agent creates a plan first, then executes each step.

​
Quick Start

1

Simple Usage

Enable planning with a single parameter — the agent drafts a plan before acting.
from praisonaiagents import Agent

agent = Agent(
    name="Planner",
    instructions="You research before acting.",
    planning=True,
)
agent.start("Compare React and Vue for a dashboard.")
2

With Configuration

Use PlanningConfig to pick the planning LLM, tools, and approval behavior.
from praisonaiagents import Agent, PlanningConfig

agent = Agent(
    name="Planner",
    instructions="Research and write about topics.",
    planning=PlanningConfig(
        llm="gpt-4o",
        reasoning=True,
        auto_approve=False,
    ),
)
agent.start("Draft a migration plan from REST to GraphQL.")

​
How It Works

PhaseWhat happens
1. ResearchThe agent gathers context and drafts a step-by-step plan
2. ReviewWith auto_approve=False, the plan is shown for your approval before any action
3. ExecuteOnce approved (or auto-approved), the agent runs the plan step by step

​
Choosing Your Planning Mode

​
Configuration Options

Full list of PlanningConfig options, types, and defaults.
FieldTypeDefaultWhat it does
llmstr | NoneNonePlanning LLM when different from the agent’s main LLM
toolslist | NoneNoneTools available during the planning phase
reasoningboolFalseEnable reasoning while drafting the plan
auto_approveboolFalseRun the plan without asking for your approval
read_onlyboolFalseRestrict planning to read-only operations

​
Common Patterns

​
Pattern 1 — Auto-approve a safe task

For low-risk, repeatable tasks, skip the review step and run the plan straight through. 
from praisonaiagents import Agent, PlanningConfig

agent = Agent(
    name="Outliner",
    instructions="Turn notes into a structured outline.",
    planning=PlanningConfig(auto_approve=True),
)
outline = agent.start("Structure these meeting notes into an outline.")

​
Pattern 2 — Read-only research mode

Restrict the agent to reads during planning so it can investigate without side effects. 
from praisonaiagents import Agent, PlanningConfig

agent = Agent(
    name="Researcher",
    instructions="Investigate the codebase and report findings.",
    planning=PlanningConfig(read_only=True, reasoning=True),
)
report = agent.start("Find where auth tokens are validated.")

​
Pattern 3 — Separate planning LLM with tools

Use a cheaper model to draft the plan and give the planning phase its own tools. 
from praisonaiagents import Agent, PlanningConfig
from praisonaiagents.tools import duckduckgo

agent = Agent(
    name="Strategist",
    instructions="Plan a content calendar.",
    llm="anthropic/claude-sonnet-4-20250514",
    planning=PlanningConfig(llm="gpt-4o", tools=[duckduckgo]),
)
agent.start("Plan a month of blog posts on AI agents.")

​
Best Practices

Turn planning on with the default config before reaching for PlanningConfig. The default already separates drafting from execution, so you see the plan before it runs. Add config only when you need a different LLM or approval behavior.
Anything that writes files, sends messages, or makes API calls is hard to undo. Leave auto_approve=False for those tasks so the plan lands in front of you before any change happens. Reserve auto_approve=True for read-heavy or idempotent work.
Drafting a plan is lighter work than executing it. Set llm to a cheaper model (for example gpt-4o-mini) for the planning phase, and keep your stronger model on the agent for execution.
When you only need answers — not changes — set read_only=True. The agent can explore and report without the risk of writing or calling mutating tools during planning.

Planning Mode — the review and approval workflow in depth.

PlanningConfig — full options, types, and defaults.