Planning Mode

Enable agents to research and plan before executing — review and approve plans before any changes happen

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

Step	What Happens
1. Analyse	Agent reads the request and gathers context
2. Plan	A dedicated planning agent creates numbered steps
3. Review	Plan is presented to the user (or auto-approved)
4. Execute	Agent runs each step sequentially

---

Configuration Options

Option	Type	Default	Description
llm	str	None	LLM for planning (defaults to agent’s LLM)
tools	List	None	Tools available during planning research
reasoning	bool	False	Chain-of-thought reasoning during planning
auto_approve	bool	False	Skip user review and approve automatically
read_only	bool	False	Restrict 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

Use planning for complex multi-step tasks

Planning shines when the path to a solution is unclear. For simple one-step tasks, direct execution is faster.

Enable read_only for safe exploration

Set read_only=True when the agent should research code or documents without risk of modification.

Provide research tools during planning

Pass tools=[search_web, read_file] so the planning phase has relevant context.

Enable reasoning for complex requests

Set reasoning=True for chain-of-thought analysis in the plan.

---

Related

Workflows

Create reusable multi-step workflows

Hooks

Intercept agent behaviour at lifecycle points