Praison AI

Agent Planning

Enable agents to break down complex tasks into executable steps before acting

Planning enables agents to think before acting – decomposing complex tasks into manageable steps, then executing them systematically.

Diagram

Planning Flow

1. Analyze

2. Decompose

3. Execute

4. Complete

📋 Complex Task

🧠 Planner

📝 Steps

🤖 Agent

✅ Result

Quick Start

  1. Enable Planning
    python
    from praisonaiagents import Agent

agent = Agent(
    name="Planner Agent",
    instructions="You solve complex problems step by step",
    planning=True  # Enable planning
)

agent.start("Build a REST API with authentication")
  2. With Configuration
    python
    from praisonaiagents import Agent, PlanningConfig

agent = Agent(
    name="Advanced Planner",
    instructions="You are a strategic problem solver",
    planning=PlanningConfig(
        llm="gpt-4o",           # Use powerful model for planning
        reasoning=True,         # Show reasoning process
        auto_approve=False,     # Require approval before execution
    )
)

How Planning Works

Diagram
ExecutorPlannerAgentUserExecutorPlannerAgentUser1. Understand goal2. Identify subtasks3. Order dependenciesopt[Auto-approve disabled]loop[For each step]Complex taskAnalyze taskStep-by-step planShow plan for approvalApprove/modifyExecute stepStep resultFinal result

The Planning Process

PhaseWhat HappensOutput
AnalyzeUnderstand the task requirementsGoal definition
DecomposeBreak into subtasksList of steps
OrderDetermine dependenciesExecution order
ExecuteRun each stepIntermediate results
SynthesizeCombine resultsFinal output

Configuration Options

python
from praisonaiagents import PlanningConfig

config = PlanningConfig(
    llm="gpt-4o",           # LLM for planning (can differ from execution)
    tools=[search_tool],    # Tools available during planning
    reasoning=True,         # Enable reasoning display
    auto_approve=False,     # Require user approval
    read_only=False,        # Read-only mode (no modifications)
)
OptionTypeDefaultDescription
llmstrNoneLLM model for planning (uses agent’s LLM if not set)
toolslistNoneTools available during planning phase
reasoningboolFalseShow reasoning process
auto_approveboolFalseAuto-approve plans without confirmation. In non-interactive environments (no TTY on stdin), plans are auto-approved even when this is False.
read_onlyboolFalseOnly allow read operations

Non-interactive environments

Diagram

Yes

No

Plan ready

stdin is TTY?

Prompt user

Auto-approve

Execute plan

Force explicit approval everywhere (e.g. fail CI instead of auto-approving):

python
import sys
from praisonaiagents.planning import ApprovalCallback

def deny_non_interactive(plan):
    return sys.stdin is not None and sys.stdin.isatty()

handler = ApprovalCallback(approve_fn=deny_non_interactive)
# Pass handler into your planning flow where ApprovalCallback is accepted

Planning Modes

Diagram

Planning Modes

Default settings

Custom LLM, tools

No modifications

🎯 Simple
planning=True

⚙️ Configured
PlanningConfig

🔒 Read-Only
read_only=True

Execute Plan

Simple Planning

python
# Just enable it
agent = Agent(
    instructions="You are a helpful assistant",
    planning=True
)

Configured Planning

python
# With specific settings
agent = Agent(
    instructions="You are a code architect",
    planning=PlanningConfig(
        llm="gpt-4o",
        reasoning=True,
        auto_approve=True,
    )
)

Read-Only Planning

python
# Safe mode - no file modifications
agent = Agent(
    instructions="You analyze code",
    planning=PlanningConfig(
        read_only=True,  # Only read operations allowed
    )
)

Multi-Agent Planning

Enable planning for multi-agent workflows:

python
from praisonaiagents import Agent, Task, AgentTeam

researcher = Agent(name="Researcher", instructions="Research topics")
writer = Agent(name="Writer", instructions="Write content")

team = AgentTeam(
    agents=[researcher, writer],
    planning=True,  # Enable planning for the workflow
)

team.start("Write a blog post about AI trends")
Diagram

Multi-Agent Planning

📋 Task

🧠 Planner

📝 Plan

🤖 Agent 1

🤖 Agent 2

✅ Result

When to Use Planning

✅ Use Planning For
  • Complex multi-step tasks
  • Tasks requiring coordination
  • Code refactoring projects
  • Research and analysis
  • Content creation workflows
 ❌ Skip Planning For
  • Simple Q&A
  • Single-step operations
  • Real-time responses needed
  • Trivial tasks

Best Practices

Use a powerful model for planning

Planning benefits from stronger reasoning. Use gpt-4o or similar for planning even if using a smaller model for execution.

Enable reasoning for complex tasks

Set reasoning=True to see the agent’s thought process and catch issues early.

Review plans before execution

Keep auto_approve=False for critical tasks to review and modify plans.

Use read-only mode for analysis

When analyzing code or data, use read_only=True to prevent accidental modifications.

Related

Reflection

Self-evaluation after execution

 Autonomy

Control agent independence