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

# Orchestration

> Choose the right orchestration pattern for your AI agents

# Agent Orchestration

PraisonAI provides two orchestration patterns for multi-agent systems. Choose based on your mental model.

<Note>
  **v1.0 Naming**: `AgentTeam` (formerly AgentTeam) and `AgentFlow` (formerly Workflow) are the new primary names. Old names still work as silent aliases. See [Migration Guide](/docs/concepts/migration-v1).
</Note>

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TD
    subgraph "AgentTeam"
        AM[AgentTeam] --> T1[Task 1]
        AM --> T2[Task 2]
        T1 --> A1[Agent A]
        T2 --> A2[Agent B]
    end
    
    subgraph "AgentFlow"
        WF[AgentFlow] --> S1[Step 1]
        S1 --> S2[Step 2]
        S2 --> S3[Step 3]
    end
    
    classDef manager fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef workflow fill:#189AB4,stroke:#7C90A0,color:#fff
    
    class AM,T1,T2,A1,A2 manager
    class WF,S1,S2,S3 workflow
```

## Quick Decision Guide

<CardGroup cols={2}>
  <Card title="Use AgentTeam" icon="users-gear">
    * Task-based DAG execution
    * Hierarchical with manager agent
    * Explicit task-agent assignment
    * Complex dependencies
  </Card>

  <Card title="Use AgentFlow" icon="diagram-project">
    * Simple sequential pipelines
    * Pattern-based (Route, Loop, Parallel)
    * Workflow composition
    * Cleaner syntax
  </Card>
</CardGroup>

## Comparison

| Feature          | AgentTeam                | AgentFlow                   |
| ---------------- | ------------------------ | --------------------------- |
| **Mental Model** | "Who does what"          | "What happens next"         |
| **Unit of Work** | `Task` + `Agent`         | `Step` (Agent/function)     |
| **Sequential**   | `process="sequential"`   | Default behavior            |
| **Parallel**     | `process="parallel"`     | `parallel([...])`           |
| **Conditional**  | `task.condition={...}`   | `route({...})`, `when()`    |
| **Loop**         | `task.loop_over="items"` | `loop(step, over="items")`  |
| **Hierarchical** | ✅ `manager_llm`          | ❌ Not available             |
| **Repeat Until** | ❌ Not available          | ✅ `repeat(step, until=...)` |
| **Composition**  | ❌ Not available          | ✅ `include(workflow=...)`   |

## AgentTeam

Best for **task-centric** workflows where you think in terms of "who does what task".

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

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

task1 = Task(description="Research AI trends", agent=researcher)
task2 = Task(description="Write article", agent=writer)

team = AgentTeam(
    agents=[researcher, writer],
    tasks=[task1, task2],
    process="sequential"  # or "parallel", "hierarchical"
)
result = team.start()
```

### Hierarchical Mode

Use a manager agent to validate and coordinate:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
team = AgentTeam(
    agents=[researcher, writer, editor],
    tasks=[task1, task2, task3],
    process="hierarchical",
    manager_llm="gpt-4o-mini"
)
```

```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TD
    M[Manager Agent] --> T1[Task 1]
    M --> T2[Task 2]
    M --> T3[Task 3]
    T1 --> |validate| M
    T2 --> |validate| M
    T3 --> |validate| M
    
    classDef manager fill:#8B0000,stroke:#7C90A0,color:#fff
    classDef task fill:#189AB4,stroke:#7C90A0,color:#fff
    
    class M manager
    class T1,T2,T3 task
```

## AgentFlow

Best for **flow-centric** pipelines where you think in terms of "what happens in sequence".

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

researcher = Agent(instructions="Research topics")
writer = Agent(instructions="Write content")
editor = Agent(instructions="Edit content")

flow = AgentFlow(steps=[researcher, writer, editor])
result = flow.start("Write about AI")
```

### Patterns

<Tabs>
  <Tab title="Route">
    Branch based on output:

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

    flow = AgentFlow(steps=[
        classifier,
        route({
            "positive": [celebrate],
            "negative": [escalate],
            "default": [log]
        })
    ])
    ```
  </Tab>

  <Tab title="Parallel">
    Execute concurrently:

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

    flow = AgentFlow(steps=[
        parallel([researcher1, researcher2, researcher3]),
        aggregator
    ])
    ```
  </Tab>

  <Tab title="Loop">
    Iterate over items:

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

    flow = AgentFlow(
        steps=[loop(processor, over="items")],
        variables={"items": ["a", "b", "c"]}
    )
    ```
  </Tab>

  <Tab title="Repeat">
    Repeat until condition:

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

    flow = AgentFlow(steps=[
        repeat(
            improver,
            until=lambda ctx: "done" in ctx.previous_result,
            max_iterations=5
        )
    ])
    ```
  </Tab>
</Tabs>

## Same Use Case, Different APIs

<Accordion title="Sequential: Research → Write → Edit">
  <CodeGroup>
    ```python AgentTeam theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    team = AgentTeam(
        agents=[researcher, writer, editor],
        tasks=[
            Task(description="Research AI", agent=researcher),
            Task(description="Write article", agent=writer),
            Task(description="Edit article", agent=editor),
        ],
        process="sequential"
    )
    result = team.start()
    ```

    ```python AgentFlow theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    flow = AgentFlow(steps=[researcher, writer, editor])
    result = flow.start("Research AI")
    ```
  </CodeGroup>
</Accordion>

<Accordion title="Parallel Execution">
  <CodeGroup>
    ```python AgentTeam theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    team = AgentTeam(
        agents=[a, b, c],
        tasks=[Task(..., agent=a), Task(..., agent=b), Task(..., agent=c)],
        process="parallel"
    )
    ```

    ```python AgentFlow theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
    flow = AgentFlow(steps=[
        parallel([a, b, c]),
        aggregator
    ])
    ```
  </CodeGroup>
</Accordion>

## Shared Features

Both support the same consolidated parameters:

| Parameter    | Description          |
| ------------ | -------------------- |
| `memory`     | Memory configuration |
| `planning`   | Planning mode        |
| `context`    | Context management   |
| `output`     | Output configuration |
| `hooks`      | Lifecycle callbacks  |
| `autonomy`   | Agent autonomy       |
| `knowledge`  | RAG configuration    |
| `guardrails` | Validation           |
| `web`        | Web search/fetch     |
| `reflection` | Self-reflection      |
| `caching`    | Caching              |

## Best Practices

<Steps>
  <Step title="Start Simple">
    Use `AgentFlow` for simple sequential pipelines. It's cleaner.
  </Step>

  <Step title="Add Patterns">
    Use `route()`, `parallel()`, `loop()` for complex flows.
  </Step>

  <Step title="Use AgentTeam for DAGs">
    When you need explicit task dependencies or hierarchical validation.
  </Step>

  <Step title="Don't Mix">
    Pick one pattern per workflow. Don't nest AgentTeam in AgentFlow.
  </Step>
</Steps>

## Related

<CardGroup cols={2}>
  <Card title="AgentFlow" icon="diagram-project" href="/docs/features/workflows">
    Deep dive into AgentFlow patterns
  </Card>

  <Card title="AgentTeam" icon="users-gear" href="/docs/features/agent-manager">
    Task-based orchestration details
  </Card>

  <Card title="Migration Guide" icon="arrow-right-arrow-left" href="/docs/concepts/migration-v1">
    v1.0 naming changes
  </Card>

  <Card title="Agents" icon="robot" href="/docs/concepts/agents">
    Agent configuration reference
  </Card>
</CardGroup>