Agent Orchestration

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

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.

Quick Decision Guide

Use AgentTeam

Task-based DAG execution
Hierarchical with manager agent
Explicit task-agent assignment
Complex dependencies

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

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:

team = AgentTeam(
    agents=[researcher, writer, editor],
    tasks=[task1, task2, task3],
    process="hierarchical",
    manager_llm="gpt-4o-mini"
)

AgentFlow

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

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

Route
Parallel
Loop
Repeat

Branch based on output:

from praisonaiagents import AgentFlow, route

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

Execute concurrently:

from praisonaiagents import AgentFlow, parallel

flow = AgentFlow(steps=[
    parallel([researcher1, researcher2, researcher3]),
    aggregator
])

Iterate over items:

from praisonaiagents import AgentFlow, loop

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

Repeat until condition:

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

Sequential: Research → Write → Edit

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

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

Parallel Execution

team = AgentTeam(
    agents=[a, b, c],
    tasks=[Task(..., agent=a), Task(..., agent=b), Task(..., agent=c)],
    process="parallel"
)

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

Start Simple

Use AgentFlow for simple sequential pipelines. It’s cleaner.

Add Patterns

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

Use AgentTeam for DAGs

When you need explicit task dependencies or hierarchical validation.

Don't Mix

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

AgentFlow

Deep dive into AgentFlow patterns

AgentTeam

Task-based orchestration details

Migration Guide

v1.0 naming changes

Agents

Agent configuration reference

Getting Started

Install

Core Concepts

Guides

Features

Models

Databases

Observability

Memory

Telemetry & Analytics

Knowledge

RAG

Persistence

Tools

Other Features

Developers

Configuration

Best Practices

Getting Started (No Code)

Orchestration

Agent Orchestration

Quick Decision Guide

Use AgentTeam

Use AgentFlow

Comparison

AgentTeam

Hierarchical Mode

AgentFlow

Patterns

Same Use Case, Different APIs

Shared Features

Best Practices

AgentFlow

AgentTeam

Migration Guide

Agents

​Agent Orchestration

​Quick Decision Guide

Use AgentTeam

Use AgentFlow

​Comparison

​AgentTeam

​Hierarchical Mode

​AgentFlow

​Patterns

​Same Use Case, Different APIs

​Shared Features

​Best Practices

​Related

AgentFlow

AgentTeam

Migration Guide

Agents

Agent Orchestration

Quick Decision Guide

Comparison

AgentTeam

Hierarchical Mode

AgentFlow

Patterns

Same Use Case, Different APIs

Shared Features

Best Practices

Related