Skip to main content

​
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

FeatureAgentTeamAgentFlow
Mental Model”Who does what""What happens next”
Unit of WorkTask + AgentStep (Agent/function)
Sequentialprocess="sequential"Default behavior
Parallelprocess="parallel"parallel([...])
Conditionaltask.condition={...}route({...}), when()
Looptask.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

Branch based on output:
from praisonaiagents import AgentFlow, route

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

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

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

​
Shared Features

Both support the same consolidated parameters:
ParameterDescription
memoryMemory configuration
planningPlanning mode
contextContext management
outputOutput configuration
hooksLifecycle callbacks
autonomyAgent autonomy
knowledgeRAG configuration
guardrailsValidation
webWeb search/fetch
reflectionSelf-reflection
cachingCaching

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

AgentFlow

Deep dive into AgentFlow patterns

AgentTeam

Task-based orchestration details

Migration Guide

v1.0 naming changes

Agents

Agent configuration reference