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.

Quick Start

1. Enable Planning

   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

   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

The Planning Process

Phase	What Happens	Output
Analyze	Understand the task requirements	Goal definition
Decompose	Break into subtasks	List of steps
Order	Determine dependencies	Execution order
Execute	Run each step	Intermediate results
Synthesize	Combine results	Final output

---

Configuration Options

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

Option	Type	Default	Description
llm	str	None	LLM model for planning (uses agent’s LLM if not set)
tools	list	None	Tools available during planning phase
reasoning	bool	False	Show reasoning process
auto_approve	bool	False	Auto-approve plans without confirmation. In non-interactive environments (no TTY on stdin), plans are auto-approved even when this is False.
read_only	bool	False	Only allow read operations

Non-interactive environments

Plans auto-approve in non-interactive environments. When stdin is not a TTY — CI runners, cron jobs, Docker containers, GitHub Actions, or piped scripts — the default approval handler automatically approves every plan and execution continues. In an interactive terminal, the agent still prompts as before.

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

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

Simple Planning

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

Configured Planning

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

Read-Only Planning

# 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:

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

---

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