Praison AI

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.

python
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.

Diagram

Execution Phase

Review Phase

Planning Phase

🔍 Analyse Request

📝 Create Plan

👀 User Review

✅ Approve

⚡ Execute

✅ Result

Quick Start

  1. Simple Usage
    python
    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
    python
    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.

Diagram

Yes, review first

No, research only

No, trusted

How much control?

Risky or irreversible actions?

Manual review
auto_approve=False

Read-only
read_only=True

Auto-approve
auto_approve=True

How It Works

Diagram
ToolsPlanning AgentAgentUserToolsPlanning AgentAgentUserstart(task)create_plan(task)research (read-only)contextnumbered stepspresent planapproveexecute each stepfinal result
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

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

Diagram
Planning AgentAgentUserPlanning AgentAgentUserstart(tasks)create_plan(tasks)plan stepsexecute each steprestore original tasksfinal result

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.

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

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
python
agent = Agent(planning=True)                          # bool — safe defaults
agent = Agent(planning=PlanningConfig(llm="gpt-4o"))  # config — full control

Common Patterns

Read-only planning

python
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

python
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

python
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