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.

Quick Decision Guide

Comparison

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

from praisonaiagents import AgentFlow, route

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

from praisonaiagents import AgentFlow, parallel

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

from praisonaiagents import AgentFlow, loop

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

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

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

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:

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