Planning Mode

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

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")

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

The final step restores your original tasks so team.tasks is exactly what you passed in.

Inspecting the plan after execution

Your original tasks stay canonical after a planned run — the plan-derived steps are kept separately for introspection. When planning=True on PraisonAIAgents(...), the original tasks you passed in are preserved and remain the canonical team.tasks after .start() returns. The plan-derived intermediate steps are kept for introspection under team._plan_tasks, and task_id_counter is advanced past the max original id so any later team.add_task(...) calls do not collide.

from praisonaiagents import Agent, Task, PraisonAIAgents

researcher = Agent(name="Researcher", role="Research Analyst")
writer = Agent(name="Writer", role="Content Writer")

t1 = Task(description="Research AI trends", agent=researcher)
t2 = Task(description="Write summary", agent=writer)

team = PraisonAIAgents(
    agents=[researcher, writer],
    tasks=[t1, t2],
    planning=True,
)
team.start()

# Your original tasks are still there:
assert team.tasks[0].description == "Research AI trends"
assert len(team.tasks) == 2

# The auto-generated plan steps are here if you want to see what the planner did:
for step in team._plan_tasks.values():
    print(step.description)

# Follow-up work gets a fresh id, no collision with t1/t2:
team.add_task(Task(description="Follow-up", agent=researcher))

Fixed in PraisonAI PR #4034 — previously team.tasks was overwritten with the plan-derived tasks and the originals were lost. If you have code that reached into team.tasks[0] after a planned run expecting to see the auto-plan, that code needs to read team._plan_tasks now.

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.

Workflows

Create reusable multi-step workflows

Hooks

Intercept agent behaviour at lifecycle points

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Quick Start

Which Approval Mode Should I Use?

How It Works

Inspecting the plan after execution

Configuration Options

Common Patterns

Read-only planning

Auto-approved pipeline

Multi-agent with planning

Best Practices

Workflows

Hooks

​Quick Start

​Which Approval Mode Should I Use?

​How It Works

​Inspecting the plan after execution

​Configuration Options

​Common Patterns

​Read-only planning

​Auto-approved pipeline

​Multi-agent with planning

​Best Practices

​Related

Workflows

Hooks

Quick Start

Which Approval Mode Should I Use?

How It Works

Inspecting the plan after execution

Configuration Options

Common Patterns

Read-only planning

Auto-approved pipeline

Multi-agent with planning

Best Practices

Related