> ## 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](https://praison.ai/docs/concepts/migration-v1.md).

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

> [card] Use AgentTeam
>
> * Task-based DAG execution
> * Hierarchical with manager agent
> * Explicit task-agent assignment
> * Complex dependencies

> [card] Use AgentFlow
>
> * Simple sequential pipelines
> * Pattern-based (Route, Loop, Parallel)
> * Workflow composition
> * Cleaner syntax

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

> [tab] 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] 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] 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] 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
>     )
> ])
> ```

## Same Use Case, Different APIs

> [accordion] Sequential: Research → Write → Edit
>
> ```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")
> ```

> [accordion] Parallel Execution
>
> ```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
> ])
> ```

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

**1. Start Simple**

Use `AgentFlow` for simple sequential pipelines. It's cleaner.

**2. Add Patterns**

Use `route()`, `parallel()`, `loop()` for complex flows.

**3. Use AgentTeam for DAGs**

When you need explicit task dependencies or hierarchical validation.

**4. Don't Mix**

Pick one pattern per workflow. Don't nest AgentTeam in AgentFlow.

## Related

> [card] [AgentFlow](https://praison.ai/docs/features/workflows.md)
>
> Deep dive into AgentFlow patterns

> [card] [AgentTeam](https://praison.ai/docs/features/agent-manager)
>
> Task-based orchestration details

> [card] [Migration Guide](https://praison.ai/docs/concepts/migration-v1.md)
>
> v1.0 naming changes

> [card] [Agents](https://praison.ai/docs/concepts/agents.md)
>
> Agent configuration reference


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.