> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Multi-Agent Planning

> Add planning capabilities to multi-agent workflows for better task coordination

Multi-Agent Planning generates a high-level plan before distributing tasks across agents, improving coordination on complex workflows.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, PraisonAIAgents, MultiAgentPlanningConfig

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

tasks = [
    Task(description="Research the impact of AI on healthcare", agent=researcher),
    Task(description="Write a report on the research findings", agent=writer),
]

workflow = PraisonAIAgents(
    agents=[researcher, writer],
    tasks=tasks,
    planning=MultiAgentPlanningConfig(llm="gpt-4o", auto_approve=True),
)
workflow.start()
```

The user defines tasks; a planning LLM drafts a plan before agents execute.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Multi-Agent Planning"
        GOAL["🎯 Goal"] --> PLANNER["🧠 Planning\nLLM"]
        PLANNER --> PLAN["📋 Task Plan"]
        PLAN --> APPROVE{"✅ Auto\nApprove?"}
        APPROVE -- Yes --> EXEC["🤖 Execute\nAgents"]
        APPROVE -- No --> HUMAN["👤 Human\nReview"]
        HUMAN --> EXEC
        EXEC --> DONE["✅ Result"]
    end

    classDef goal fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef planner fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef plan fill:#189AB4,stroke:#7C90A0,color:#fff
    classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef success fill:#10B981,stroke:#7C90A0,color:#fff

    class GOAL goal
    class PLANNER planner
    class PLAN,APPROVE,HUMAN plan
    class EXEC agent
    class DONE success
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, Task, PraisonAIAgents, MultiAgentPlanningConfig

    agent = Agent(name="Analyst", instructions="Analyze data and provide insights.")
    task = Task(description="Analyze customer churn patterns", agent=agent)

    workflow = PraisonAIAgents(
        agents=[agent],
        tasks=[task],
        planning=MultiAgentPlanningConfig(auto_approve=True),
    )
    workflow.start()
    ```
  </Step>

  <Step title="With Reasoning">
    ```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    from praisonaiagents import Agent, Task, PraisonAIAgents, MultiAgentPlanningConfig

    researcher = Agent(name="Researcher", instructions="Research deeply.")
    analyst = Agent(name="Analyst", instructions="Analyze and summarize findings.")

    tasks = [
        Task(description="Research quantum computing use cases", agent=researcher),
        Task(description="Summarize key findings for a business audience", agent=analyst),
    ]

    workflow = PraisonAIAgents(
        agents=[researcher, analyst],
        tasks=tasks,
        planning=MultiAgentPlanningConfig(
            llm="gpt-4o",
            reasoning=True,
            auto_approve=True,
        ),
    )
    workflow.start()
    ```
  </Step>
</Steps>

***

## Single-Agent vs Multi-Agent Planning

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Q{Single agent or multi-agent workflow?}
    Q -->|Single agent| SA[PlanningConfig\nagent.start...]
    Q -->|Multiple agents| MA[MultiAgentPlanningConfig\nPraisonAIAgents...]

    SA -->|Enable| SAA["Agent(planning=PlanningConfig(...))"]
    MA -->|Enable| MAA["PraisonAIAgents(planning=MultiAgentPlanningConfig(...))"]

    classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef option fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef code fill:#10B981,stroke:#7C90A0,color:#fff

    class Q decision
    class SA,MA option
    class SAA,MAA code
```

`PlanningConfig` plans **within** a single agent's execution. `MultiAgentPlanningConfig` plans **across** multiple agents and tasks.

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Orchestrator
    participant PlanningLLM as Planning LLM
    participant Agents

    User->>Orchestrator: Start with goal
    Orchestrator->>PlanningLLM: Generate task plan
    PlanningLLM-->>Orchestrator: Structured plan (tasks, assignments)
    alt auto_approve = False
        Orchestrator->>User: Show plan for review
        User->>Orchestrator: Approve/Modify
    end
    Orchestrator->>Agents: Execute approved plan
    Agents-->>Orchestrator: Results
    Orchestrator-->>User: Final output
```

***

<Note>
  Multi-agent planning (`MultiAgentPlanningConfig`) generates plans at the orchestration level — it decides what tasks to run and which agents run them.

  This is different from single-agent `PlanningConfig` (see [Planning Mode](/docs/features/planning-mode)), which makes a single agent break down its own task into steps before acting.
</Note>

***

## Configuration Options

<Card icon="code" href="/docs/sdk/reference/python/MultiAgentPlanningConfig">
  Full list of options, types, and defaults — `MultiAgentPlanningConfig`
</Card>

| Option         | Type           | Default | Description                                 |
| -------------- | -------------- | ------- | ------------------------------------------- |
| `llm`          | `str \| None`  | `None`  | LLM for planning (defaults to workflow LLM) |
| `auto_approve` | `bool`         | `False` | Skip user confirmation of generated plans   |
| `tools`        | `list \| None` | `None`  | Tools available to the planner              |
| `reasoning`    | `bool`         | `False` | Enable extended reasoning during planning   |

***

## Common Patterns

### Pattern 1 — Automated multi-agent research pipeline

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, PraisonAIAgents, MultiAgentPlanningConfig

agents = [
    Agent(name="Searcher", instructions="Search for relevant information."),
    Agent(name="Analyst", instructions="Analyze and extract insights."),
    Agent(name="Writer", instructions="Write clear, structured reports."),
]

tasks = [
    Task(description="Search for recent AI breakthroughs", agent=agents[0]),
    Task(description="Analyze which breakthroughs are most impactful", agent=agents[1]),
    Task(description="Write an executive summary", agent=agents[2]),
]

result = PraisonAIAgents(
    agents=agents,
    tasks=tasks,
    planning=MultiAgentPlanningConfig(llm="gpt-4o", auto_approve=True, reasoning=True),
).start()
print(result)
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Use a capable model for planning">
    Planning requires understanding the goal and decomposing it into tasks. Use `gpt-4o`, `claude-3-5-sonnet`, or similar capable models. Smaller models often produce poor plans.
  </Accordion>

  <Accordion title="Enable auto_approve for CI/CD pipelines">
    In automated workflows where human review isn't possible, set `auto_approve=True`. In interactive applications, leave it `False` so users can review and adjust the plan before execution.
  </Accordion>

  <Accordion title="Enable reasoning for complex goals">
    `reasoning=True` adds chain-of-thought prompting to the planning step, helping the planning model think through dependencies and edge cases before producing the task list.
  </Accordion>

  <Accordion title="Multi-agent planning vs. single-agent planning">
    Use multi-agent planning when you have a team of specialized agents and a complex goal that needs task decomposition. Use single-agent planning (via `PlanningConfig`) when a single agent needs to break down its own sub-goal.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card title="Planning Mode" icon="list-check" href="/docs/features/planning-mode">
    Single-agent planning configuration
  </Card>

  <Card title="Multi-Agent Execution" icon="play" href="/docs/features/multi-agent-execution">
    Configure iteration and retry limits
  </Card>

  <Card title="Multi-Agent Hooks" icon="webhook" href="/docs/features/multi-agent-hooks">
    Intercept task lifecycle events
  </Card>

  <Card title="Autonomous Workflow" icon="robot" href="/docs/features/autonomous-workflow">
    Fully autonomous multi-agent pipelines
  </Card>
</CardGroup>