Planning Mode - PraisonAI

The --planning flag enables planning mode where the agent creates a multi-step plan before execution.

Don’t confuse --planning with --plan. --planning enables the agent’s multi-step plan-then-execute workflow (this page). --plan on praisonai run / praisonai code is a completely different flag: it selects the read-only planning permission mode (PermissionMode.PLAN) so mutating tools are denied. Inside praisonai chat / praisonai code, the interactive /plan slash command toggles the same read-only permission mode on/off. See Slash Commands › /plan, Permissions, and Permission Modes.

Quick Start

praisonai "write poem" --planning

Usage

Basic Planning

praisonai "Research AI trends and write a summary" --planning

Expected Output:

📋 Planning Mode Enabled

╭─ Plan ───────────────────────────────────────────────────────────────────────╮
│  1. Research current AI trends from multiple sources                        │
│  2. Identify key themes and patterns                                        │
│  3. Organize findings into categories                                       │
│  4. Write executive summary                                                 │
│  5. Add conclusions and recommendations                                     │
╰──────────────────────────────────────────────────────────────────────────────╯

Approve plan? [Y/n]: y

╭─ Step 1/5 ───────────────────────────────────────────────────────────────────╮
│  🔍 Researching current AI trends...                                        │
╰──────────────────────────────────────────────────────────────────────────────╯

With Planning Tools

# Planning with tools for research
praisonai "Analyze market trends" --planning --planning-tools tools.py

With Reasoning

# Planning with chain-of-thought reasoning
praisonai "Complex analysis task" --planning --planning-reasoning

Auto-Approve Plans

# Auto-approve plans without confirmation
praisonai "Task" --planning --auto-approve-plan

Combine Options

# Full featured planning
praisonai "Research and write report" --planning --planning-tools tools.py --planning-reasoning

# Planning with metrics
praisonai "Complex task" --planning --metrics

How It Works

Plan Creation: Agent analyzes the task and creates a multi-step plan
User Approval: Plan is shown for approval (unless --auto-approve-plan)
Step Execution: Each step is executed sequentially
Context Passing: Results from each step inform the next
Final Result: Combined output from all steps

Planning Options

Flag	Description
`--planning`	Enable planning mode
`--planning-tools`	Tools file for planning research
`--planning-reasoning`	Enable chain-of-thought reasoning
`--auto-approve-plan`	Skip plan approval prompt

YAML Equivalent

Use planning: true inside an agent definition for YAML-based planning:

agents:
  planner:
    role: Task Planner
    instructions: "Create detailed plans before execution"
    planning: true
    planning_tools: ['search_tool', 'analysis_tool']

Examples

Research Task

praisonai "Research the impact of AI on healthcare and write a comprehensive report" \
  --planning --planning-reasoning

Code Project

praisonai "Create a REST API with authentication" \
  --planning --planning-tools tools.py

Analysis Task

praisonai "Analyze competitor products and create comparison matrix" \
  --planning --auto-approve-plan

Programmatic Usage

from praisonaiagents import Agent

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

agent = Agent(
    name="AI Assistant",
    instructions="Research and write about topics",
    planning=True,              # Enable planning mode
    planning_tools=[search_web], # Tools for planning research
    planning_reasoning=True      # Chain-of-thought reasoning
)

result = agent.start("Research AI trends in 2025 and write a summary")

What happens:

📋 Agent creates a multi-step plan
🚀 Executes each step sequentially
📊 Shows progress with context passing
✅ Returns final result

Best Practices

Use planning mode for complex, multi-step tasks that benefit from structured execution.

Planning mode adds overhead for simple tasks. Use it for complex tasks with multiple steps.

Use Planning For	Don’t Use For
Multi-step research	Simple questions
Complex analysis	Quick lookups
Project creation	Single-step tasks
Report writing	Conversational queries

​Quick Start

​Usage

​Basic Planning

​With Planning Tools

​With Reasoning

​Auto-Approve Plans

​Combine Options

​How It Works

​Planning Options

​YAML Equivalent

​Examples

​Research Task

​Code Project

​Analysis Task

​Programmatic Usage

​Best Practices

​Related

Quick Start

Usage

Basic Planning

With Planning Tools

With Reasoning

Auto-Approve Plans

Combine Options

How It Works

Planning Options

YAML Equivalent

Examples

Research Task

Code Project

Analysis Task

Programmatic Usage

Best Practices

Related