Skip to main content
Planning Mode separates research from execution so agents create a reviewable plan before taking action. 
from praisonaiagents import Agent

agent = Agent(
    name="Planner",
    instructions="Research and write about topics",
    planning=True,
)
agent.start("Research AI trends in 2025 and write a summary")
The user requests complex work; the agent drafts a reviewable plan before executing changes.

​
Quick Start

1

Simple Usage

from praisonaiagents import Agent

agent = Agent(
    name="Planner",
    instructions="Research and write about topics",
    planning=True,
)
agent.start("Research AI trends in 2025 and write a summary")
2

With Configuration

from praisonaiagents import Agent, PlanningConfig

def search_web(query: str) -> str:
    return f"Search results for: {query}"

agent = Agent(
    name="Planner",
    instructions="Research and write about topics",
    planning=PlanningConfig(
        llm="gpt-4o",
        tools=[search_web],
        reasoning=True,
        auto_approve=True,
    ),
)
agent.start("Research AI trends in 2025 and write a summary")

​
Which Approval Mode Should I Use?

Pick how much control you keep over the plan before it runs.

​
How It Works

StepWhat Happens
1. AnalyseAgent reads the request and gathers context
2. PlanA dedicated planning agent creates numbered steps
3. ReviewPlan is presented to the user (or auto-approved)
4. ExecuteAgent runs each step sequentially

​
Configuration Options

OptionTypeDefaultDescription
llmstrNoneLLM for planning (defaults to agent’s LLM)
toolsListNoneTools available during planning research
reasoningboolFalseChain-of-thought reasoning during planning
auto_approveboolFalseSkip user review and approve automatically
read_onlyboolFalseRestrict planning to read-only tools
agent = Agent(planning=True)                          # bool — safe defaults
agent = Agent(planning=PlanningConfig(llm="gpt-4o"))  # config — full control

​
Common Patterns

​
Read-only planning

from praisonaiagents import Agent, PlanningConfig

agent = Agent(
    name="SafeResearcher",
    instructions="Investigate and report findings",
    planning=PlanningConfig(read_only=True, reasoning=True),
)
agent.start("Analyse the codebase and suggest improvements")

​
Auto-approved pipeline

agent = Agent(
    name="AutoPlanner",
    planning=PlanningConfig(llm="gpt-4o", auto_approve=True),
)
agent.start("Write and test a Python script to sort files by date")

​
Multi-agent with planning

from praisonaiagents import Agent, AgentTeam, Task

researcher = Agent(name="Researcher", instructions="Research topics thoroughly")
writer = Agent(name="Writer", instructions="Write clear articles")

team = AgentTeam(
    agents=[researcher, writer],
    tasks=[
        Task(description="Research AI in healthcare", agent=researcher),
        Task(description="Write a summary article", agent=writer),
    ],
    planning=True,
)
team.start()

​
Best Practices

Planning shines when the path to a solution is unclear. For simple one-step tasks, direct execution is faster.
Set read_only=True when the agent should research code or documents without risk of modification.
Pass tools=[search_web, read_file] so the planning phase has relevant context.
Set reasoning=True for chain-of-thought analysis in the plan.

Workflows

Create reusable multi-step workflows

Hooks

Intercept agent behaviour at lifecycle points