<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/3.3-planning-system -->

# Planning System

- api.md
- src/praisonai-agents/praisonaiagents/agents/agents.py

## Purpose and Scope

The Planning System provides AI-driven task decomposition and structured execution orchestration in PraisonAI. When enabled, a specialized `PlanningAgent` analyzes complex requests, generates step-by-step implementation plans with dependency tracking, and coordinates execution through a `TodoList` mechanism. This enables multi-agent workflows to break down high-level goals into concrete, executable steps with automatic agent assignment and context propagation.

For autonomous agent execution patterns, see [Autonomy and Handoff](/MervinPraison/PraisonAI/2.6-autonomy-and-handoff). For workflow control structures (loops, conditionals), see [Workflow System](/MervinPraison/PraisonAI/3.1-workflow-system). For process orchestration strategies (sequential, parallel, hierarchical), see [Process Strategies](/MervinPraison/PraisonAI/3.2-process-strategies).

## Architecture Overview

The Planning System operates as a meta-layer above standard task execution, intercepting workflow initialization to generate optimized execution plans before any tasks run.

### Planning System Flow

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2228-2362](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2228-L2362)

## Core Components

### PlanningAgent

The `PlanningAgent` is a specialized agent that analyzes requests and generates structured implementation plans. It operates in read-only mode (cannot execute tools that modify state) and uses LLM reasoning to decompose tasks.

**Key Responsibilities:**

- Analyze user requests and existing task definitions
- Map requirements to available agents and their capabilities
- Generate ordered execution steps with dependencies
- Assign agents to steps based on role matching
- Provide reasoning for step decomposition

**Code Entity:** `praisonaiagents.PlanningAgent`

```

```

**Implementation Details:**

- Lazy-loaded in AgentTeam._get_planning_agent() to avoid overhead when planning disabled
- Default LLM: gpt-4o-mini (configurable via planning_llm parameter)
- Tool restrictions enforced via RESTRICTED_TOOLS and READ_ONLY_TOOLS constants
- Supports both async ( create_plan ) and sync ( create_plan_sync ) interfaces

**Sources:** [api.md146-152](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L146-L152) [src/praisonai-agents/praisonaiagents/agents/agents.py2068-2079](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2068-L2079)

### Plan and PlanStep

The `Plan` object represents a complete implementation plan with status tracking, while `PlanStep` represents individual executable steps with dependency management.

```

```

**Plan Lifecycle:**

1. pending - Initial state after generation
2. approved - After passing approval gate
3. executing - During execution
4. completed - All steps finished successfully
5. cancelled - Manually aborted

**PlanStep Dependencies:**

- Steps reference dependencies by step_id (e.g., "step_1" , "step_2" )
- Execution engine checks is_ready(completed_steps) before running each step
- Enables parallel execution when steps have no dependency conflicts

**Serialization:**

- Markdown format for human-readable display: plan.to_markdown()
- JSON format for programmatic access: plan.to_dict()
- Both formats support round-trip conversion

**Sources:** [api.md394-415](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L394-L415) [src/praisonai-agents/praisonaiagents/agents/agents.py2036-2043](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2036-L2043)

### TodoList and TodoItem

The `TodoList` provides execution tracking and progress monitoring for plan steps. It's generated from a `Plan` and maintains real-time status as tasks complete.

```

```

**TodoItem Status Flow:**

- pending -> in_progress -> completed
- reset() returns item to pending for retry scenarios

**Integration with AgentTeam:**

- Created via TodoList.from_plan(plan) in _run_with_planning()
- Synced with plan via sync_with_plan() to reflect step status changes
- Accessed via AgentTeam.todo_list property
- Progress displayed as markdown via get_todo_markdown()

**Sources:** [api.md428-454](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L428-L454) [src/praisonai-agents/praisonaiagents/agents/agents.py2112-2113](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2112-L2113) [src/praisonai-agents/praisonaiagents/agents/agents.py2280-2281](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2280-L2281)

### Approval System

The approval system provides a safety gate between plan generation and execution, allowing human review or automated validation of plans before they run.

```

```

**ApprovalCallback Strategies:**

**Configuration:**

- AgentTeam(planning=True, auto_approve_plan=True) - Skip approval gate
- MultiAgentPlanningConfig(auto_approve=False) - Require manual approval

**Implementation:**

- Synchronous: _request_approval_sync(plan) at agents.py 2169-2185
- Asynchronous: _request_approval(plan) for async workflows
- Integrates with _run_with_planning() before execution phase

**Sources:** [api.md387-393](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L387-L393) [src/praisonai-agents/praisonaiagents/agents/agents.py2169-2185](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2169-L2185) [src/praisonai-agents/praisonaiagents/agents/agents.py2270-2277](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2270-L2277)

### Plan Storage

The `PlanStorage` class provides persistence for plans and todo lists, enabling session continuity and plan history tracking.

**Storage Locations:**

- Default directory: ~/.praison/plans/
- Plans: Stored as JSON files with timestamps
- TodoLists: Stored separately with custom names

**Key Operations:**

**File Naming:**

- Plans: plan_{timestamp}_{id}.json
- TodoLists: todo_{name}.json

**Usage Pattern:**

```

```

**Sources:** [api.md416-427](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L416-L427)

## Planning Workflow in AgentTeam

The `AgentTeam` class integrates planning mode as an optional execution strategy. When enabled, it replaces standard task execution with plan-driven orchestration.

### Initialization with Planning

```

```

**Configuration Resolution:**

- Input: planning parameter (bool, str, Config, or dict)
- Resolver: resolve() function with string_mode="llm_model"
- Default LLM: "gpt-4o-mini"
- Config class: MultiAgentPlanningConfig

**Extracted Values:**

- _planning_llm : LLM model for planning agent
- _auto_approve_plan : Skip approval gate if True
- _planning_tools : Tools available to planner
- _planning_reasoning : Enable reasoning mode

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py372-393](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L372-L393) [src/praisonai-agents/praisonaiagents/agents/agents.py492-499](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L492-L499)

### Plan Generation Process

The `_create_plan_sync()` method orchestrates plan generation with context from agents and tasks.

```

```

**Request Construction:**

- If request param is None, uses first task description
- Multiple task descriptions joined with " AND "
- Context parameter provides additional information for planner

**Agent Analysis:**

- Planner receives List[Agent] with roles, goals, backstories, tools
- Matches steps to agents based on role/goal alignment
- Falls back to first agent if no suitable match found

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2116-2149](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2116-L2149)

### Execution with Planning

The `_run_with_planning()` method replaces `run_all_tasks()` when planning is enabled, implementing a four-phase workflow: planning, approval, task creation, and execution.

```

```

**Phase 1: Plan Generation**

- Builds request from task descriptions
- Calls _create_plan_sync(request=request)
- Displays plan as Rich markdown panel
- Falls back to normal execution if planning fails

**Phase 2: Approval Gate**

- Calls _request_approval_sync(plan)
- If auto_approve_plan=True , automatically approves
- Otherwise, prompts user via ApprovalCallback.console_approval()
- Aborts if rejected

**Phase 3: Task Creation**

- Converts PlanStep instances to full Task objects
- Maps agent names to Agent instances
- Chains tasks via context (dependencies become context items)
- Inherits configuration from original tasks (memory, callbacks, guardrails)
- Replaces self.tasks dict with plan-generated tasks

**Phase 4: Execution**

- Executes tasks in dependency order
- Updates todo list status after each task
- Displays progress panels for each step
- Tracks completed steps for context propagation

**Task Creation Details:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2228-2362](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2228-L2362) [src/praisonai-agents/praisonaiagents/agents/agents.py1326-1328](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1326-L1328)

## Configuration

### PlanningConfig

The `PlanningConfig` class defines planning behavior for individual agents or tasks.

**Attributes:**

**Methods:**

- to_dict() : Serialize to dictionary

**Usage:**

```

```

**Sources:** [api.md382-383](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L382-L383) [api.md427](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L427-L427)

### MultiAgentPlanningConfig

The `MultiAgentPlanningConfig` class configures planning at the `AgentTeam` level, applying to all agents in the workflow.

**Attributes:**

**Resolution Logic:**

- String input: Treated as LLM model name
- Bool input: True enables with defaults, False disables
- Config instance: Used directly
- Dict input: Converted to config
- Array input: [preset, overrides] pattern

**Precedence:**

1. Explicit MultiAgentPlanningConfig instance
2. Dict from preset resolution
3. String as LLM model
4. Bool as enabled flag

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py372-393](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L372-L393)

### Parameter Resolution

The planning parameter supports multiple input formats for flexibility:

**Input Formats:**

**Resolution Implementation:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py372-393](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L372-L393)

## Integration Patterns

### Basic Planning Mode

Enable planning in `AgentTeam` with default configuration:

```

```

**Behavior:**

- PlanningAgent analyzes tasks and generates execution plan
- Plan includes steps, agent assignments, dependencies
- Plan auto-approved (no human gate)
- Tasks executed according to plan
- Progress tracked via TodoList

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py200-246](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L200-L246)

### Custom Planning Configuration

Configure planning behavior with explicit settings:

```

```

**Custom LLM:**

- Planner uses specified model for plan generation
- Main agents use their own configured LLMs
- Useful for cost optimization (cheap planner, expensive executors)

**Manual Approval:**

- Displays plan in Rich panel
- Prompts: "Approve this plan? (y/n): "
- User can review and reject if plan is incorrect

**Reasoning Mode:**

- Enables chain-of-thought reasoning in planner
- Produces more detailed step decomposition
- Increases token usage but improves plan quality

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py372-393](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L372-L393)

### String Shorthand

Use string shorthand to specify only the LLM model:

```

```

Equivalent to:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py378](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L378-L378)

### Accessing Plan and TodoList

Retrieve plan and todo list for monitoring or custom logic:

```

```

**Properties:**

- team.current_plan : Returns Plan instance or None
- team.todo_list : Returns TodoList instance or None
- Both populated after _create_plan_sync() call

**Markdown Methods:**

- get_plan_markdown() : Human-readable plan with steps
- get_todo_markdown() : Checklist-style progress view

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2035-2043](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2035-L2043) [src/praisonai-agents/praisonaiagents/agents/agents.py2187-2207](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2187-L2207)

### Manual Plan Updates

Update plan step status programmatically:

```

```

**Status Values:**

- "pending" : Not started
- "in_progress" : Currently executing
- "completed" : Successfully finished
- "skipped" : Intentionally bypassed

**Synchronization:**

- Updating plan step triggers TodoList.sync_with_plan()
- Keeps todo list in sync with plan changes
- Useful for external orchestration or monitoring

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2209-2226](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2209-L2226)

## Planning System Internals

### Mapping Natural Language to Code Entities

```

```

**Key Code Mappings:**

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py172-2030](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L172-L2030) [api.md378-455](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L378-L455)

### Planning Agent Lazy Initialization

The `PlanningAgent` is lazy-loaded to avoid overhead when planning is disabled:

```

```

**Lazy Loading Benefits:**

- Zero overhead when planning=False (no import, no initialization)
- Deferred dependency loading (planning module only loaded if needed)
- Cached after first access for reuse

**Implementation:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2068-2079](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2068-L2079)

### Task Generation from Plan Steps

The `_run_with_planning()` method converts `PlanStep` instances into full `Task` objects with proper context chaining:

```

```

**Context Chaining Logic:**

```

```

**Configuration Inheritance:**

```

```

**Agent Mapping:**

- agent_map = {agent.display_name: agent for agent in self.agents}
- If step.agent not found, uses first available agent
- Enables plan to reference agents by name

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2294-2360](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2294-L2360)

### Planning Mode Detection and Execution

The `start()` method detects planning mode and routes to appropriate execution path:

```

```

**Detection Code:**

```

```

**Execution Differences:**

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py1223-1389](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1223-L1389) [src/praisonai-agents/praisonaiagents/agents/agents.py1359-1362](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1359-L1362)

## Advanced Patterns

### Custom Approval Logic

Implement custom approval callbacks for domain-specific validation:

```

```

**Note:** The exact integration point for custom approval callbacks in `AgentTeam` isn't explicitly documented in the provided code. The `ApprovalCallback` class exists but the wiring to `AgentTeam` may require additional configuration.

**Sources:** [api.md387-393](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L387-L393)

### Hybrid Planning

Combine planning mode with manual task configuration:

```

```

**Behavior:**

- Planner generates additional steps beyond manual tasks
- Manual task configuration preserved in generated tasks
- Approval gate allows review of hybrid plan
- Critical task features (guardrails, memory) inherited by generated steps

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2332-2354](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2332-L2354)

### Plan Persistence and Replay

Save plans for auditing or replay:

```

```

**Use Cases:**

- Compliance auditing (review what AI agents planned)
- Debugging (compare plans for similar requests)
- Learning (analyze successful plan patterns)
- Cost tracking (estimate before approval)

**Sources:** [api.md416-427](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/api.md?plain=1#L416-L427)

## Related Systems

The Planning System integrates with several other PraisonAI subsystems:

**Key Distinction:**

- Workflow System (#3.1): Developer-defined control flow (route, loop, parallel)
- Planning System (#3.3): AI-generated execution plans from natural language
- Process Strategies (#3.2): High-level orchestration patterns (sequential, hierarchical)

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py200-246](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L200-L246)
