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

# Planning

> Let agents think and plan before acting on complex requests

Planning makes agents create a step-by-step plan before executing, improving accuracy on complex multi-step tasks.

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

agent = Agent(
    name="Assistant",
    instructions="You help users with research and analysis tasks.",
    planning=True,
)

agent.start("Research the top 5 electric vehicle manufacturers and compare their market share.")
```

The user asks a multi-step question; the agent creates a plan first, then executes each step.

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
    subgraph "Planning Flow"
        Request[📋 User Request] --> Plan[🧠 Create Plan]
        Plan --> Execute[⚙️ Execute Steps]
        Execute --> Response[✅ Final Answer]
    end

    classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
    classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
    classDef output fill:#10B981,stroke:#7C90A0,color:#fff

    class Request input
    class Plan,Execute process
    class Response output
```

## Quick Start

<Steps>
  <Step title="Simple Usage">
    Enable planning with a single parameter — the agent drafts a plan before acting.

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

    agent = Agent(
        name="Planner",
        instructions="You research before acting.",
        planning=True,
    )
    agent.start("Compare React and Vue for a dashboard.")
    ```
  </Step>

  <Step title="With Configuration">
    Use `PlanningConfig` to pick the planning LLM, tools, and approval behavior.

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

    agent = Agent(
        name="Planner",
        instructions="Research and write about topics.",
        planning=PlanningConfig(
            llm="gpt-4o",
            reasoning=True,
            auto_approve=False,
        ),
    )
    agent.start("Draft a migration plan from REST to GraphQL.")
    ```
  </Step>
</Steps>

***

## How It Works

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
    participant User
    participant Agent
    participant Planner
    User->>Agent: "Draft a migration plan"
    Agent->>Planner: Research and draft steps
    alt auto_approve = False
        Planner-->>Agent: Plan for review
        Agent-->>User: Present plan
        User->>Agent: Approve
    else auto_approve = True
        Planner-->>Agent: Plan ready
    end
    Agent->>Agent: Execute the plan
    Agent-->>User: Result
```

| Phase       | What happens                                                                     |
| ----------- | -------------------------------------------------------------------------------- |
| 1. Research | The agent gathers context and drafts a step-by-step plan                         |
| 2. Review   | With `auto_approve=False`, the plan is shown for your approval before any action |
| 3. Execute  | Once approved (or auto-approved), the agent runs the plan step by step           |

***

## Choosing Your Planning Mode

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
    Start([Start]) --> Q1{Risky or<br/>irreversible actions?}
    Q1 -->|Yes| MA[Manual review<br/>auto_approve=False]
    Q1 -->|No| Q2{Research only,<br/>no writes?}
    Q2 -->|Yes| RO[Read-only<br/>read_only=True]
    Q2 -->|No| AP[Auto-approve<br/>auto_approve=True]

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

    class Q1,Q2 decision
    class MA,RO,AP action
    class Start start
```

***

## Configuration Options

<Card icon="code" href="/docs/configuration/planning-config">
  Full list of `PlanningConfig` options, types, and defaults.
</Card>

<AccordionGroup>
  <Accordion title="All PlanningConfig fields">
    | Field          | Type           | Default | What it does                                          |
    | -------------- | -------------- | ------- | ----------------------------------------------------- |
    | `llm`          | `str \| None`  | `None`  | Planning LLM when different from the agent's main LLM |
    | `tools`        | `list \| None` | `None`  | Tools available during the planning phase             |
    | `reasoning`    | `bool`         | `False` | Enable reasoning while drafting the plan              |
    | `auto_approve` | `bool`         | `False` | Run the plan without asking for your approval         |
    | `read_only`    | `bool`         | `False` | Restrict planning to read-only operations             |
  </Accordion>
</AccordionGroup>

***

## Common Patterns

### Pattern 1 — Auto-approve a safe task

For low-risk, repeatable tasks, skip the review step and run the plan straight through.

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

agent = Agent(
    name="Outliner",
    instructions="Turn notes into a structured outline.",
    planning=PlanningConfig(auto_approve=True),
)
outline = agent.start("Structure these meeting notes into an outline.")
```

### Pattern 2 — Read-only research mode

Restrict the agent to reads during planning so it can investigate without side effects.

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

agent = Agent(
    name="Researcher",
    instructions="Investigate the codebase and report findings.",
    planning=PlanningConfig(read_only=True, reasoning=True),
)
report = agent.start("Find where auth tokens are validated.")
```

### Pattern 3 — Separate planning LLM with tools

Use a cheaper model to draft the plan and give the planning phase its own tools.

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, PlanningConfig
from praisonaiagents.tools import duckduckgo

agent = Agent(
    name="Strategist",
    instructions="Plan a content calendar.",
    llm="anthropic/claude-sonnet-4-20250514",
    planning=PlanningConfig(llm="gpt-4o", tools=[duckduckgo]),
)
agent.start("Plan a month of blog posts on AI agents.")
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Start with planning=True">
    Turn planning on with the default config before reaching for `PlanningConfig`. The default already separates drafting from execution, so you see the plan before it runs. Add config only when you need a different LLM or approval behavior.
  </Accordion>

  <Accordion title="Keep auto_approve=False for irreversible actions">
    Anything that writes files, sends messages, or makes API calls is hard to undo. Leave `auto_approve=False` for those tasks so the plan lands in front of you before any change happens. Reserve `auto_approve=True` for read-heavy or idempotent work.
  </Accordion>

  <Accordion title="Use a cheaper planning LLM">
    Drafting a plan is lighter work than executing it. Set `llm` to a cheaper model (for example `gpt-4o-mini`) for the planning phase, and keep your stronger model on the agent for execution.
  </Accordion>

  <Accordion title="Reach for read_only on investigations">
    When you only need answers — not changes — set `read_only=True`. The agent can explore and report without the risk of writing or calling mutating tools during planning.
  </Accordion>
</AccordionGroup>

***

## Related

<CardGroup cols={2}>
  <Card icon="list-check" href="/docs/features/planning-mode">
    Planning Mode — the review and approval workflow in depth.
  </Card>

  <Card icon="code" href="/docs/configuration/planning-config">
    PlanningConfig — full options, types, and defaults.
  </Card>
</CardGroup>