Core Components

Compare Agent, AgentTeam, AgentFlow, and AgentOS

PraisonAI provides four core components for building AI applications. Each serves a distinct purpose in the architecture.

Naming Convention: AgentFlow is the class name (code), Workflow is the concept category. Similarly, AgentOS is the class, App is the concept.

Quick Reference

Component	Category	Purpose	Use When
Agent	Single Agent	Single autonomous unit	Simple tasks, single-purpose automation
AgentTeam	Team	Multi-agent coordinator	Task delegation, hierarchical teams
AgentFlow	Workflow	Deterministic pipelines	Step-by-step flows, loops, conditionals
AgentOS	App	Production deployment	Web APIs, production services

---

Agent

The fundamental building block. A single AI entity with instructions and tools.

from praisonaiagents import Agent

agent = Agent(
    name="Researcher",
    instructions="You research topics thoroughly",
    tools=[search_tool]
)

result = agent.start("What is quantum computing?")

Key Features

• Single purpose, focused execution
• Direct tool access
• Memory and context support
• Works standalone or within orchestrators

---

AgentTeam

Coordinates multiple agents through task assignment. Think: “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", agent=researcher)
task2 = Task(description="Write article", agent=writer, context=[task1])

manager = AgentTeam(
    agents=[researcher, writer],
    tasks=[task1, task2],
    process="sequential"
)
result = manager.start()

Key Features

• Task-based delegation with explicit agent assignment
• Sequential, parallel, or hierarchical execution
• Task dependencies via context
• Manager LLM for hierarchical validation

---

AgentFlow

Executes deterministic step sequences with advanced patterns. Think: “What happens in order.”

from praisonaiagents import Agent
from praisonaiagents import AgentFlow, route, loop

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

workflow = AgentFlow(
    steps=[
        researcher,
        route({
            "positive": [writer],
            "default": [fallback]
        })
    ]
)
result = workflow.run("Research AI trends")

Key Features

• Pattern-based: route(), parallel(), loop(), repeat(), when()
• Steps can be agents OR functions
• CSV/file iteration with loop(from_csv="data.csv")
• Recipe composition with include()

---

AgentOS

Deploys agents, managers, or workflows as production web services.

from praisonai import AgentOS
from praisonaiagents import Agent, AgentTeam, AgentFlow

assistant = Agent(name="assistant", instructions="Be helpful")
manager = AgentTeam(agents=[...], tasks=[...])
workflow = AgentFlow(steps=[...])

app = AgentOS(
    name="My AI API",
    agents=[assistant],
    managers=[manager],
    workflows=[workflow]
)
app.serve(port=8000)

Key Features

• FastAPI-based REST endpoints
• WebSocket support
• Auto-generated API docs (/docs)
• CORS configuration
• Health checks (/health)

Endpoints

Endpoint	Method	Description
/	GET	App status and component list
/health	GET	Health check
/api/agents	GET	List all agents
/api/chat	POST	Chat with an agent

---

Comparison Matrix

Capability	Agent	AgentTeam	AgentFlow	AgentOS
Single Task	✅ Primary	❌	⚠️ Via step	✅ Wraps
Multi-Agent	❌	✅ Primary	✅ Via steps	✅ Wraps
Sequential	N/A	✅	✅ Default	N/A
Parallel	N/A	✅	✅ parallel()	N/A
Hierarchical	N/A	✅	❌	N/A
Conditional	❌	⚠️ condition={}	✅ route(), when()	N/A
Looping	❌	⚠️ loop_over	✅ loop()	N/A
Repeat Until	❌	❌	✅ repeat()	N/A
Web API	❌	❌	❌	✅ Primary
Functions as Steps	❌	❌	✅	N/A

---

When to Use What

1. Simple single task

   Use Agent directly:

   Agent(instructions="...").start("prompt")
   
2. Multi-agent with task delegation

   Use AgentTeam:

   AgentTeam(agents=[...], tasks=[...]).start()
   
3. Deterministic pipeline with patterns

   Use AgentFlow:

   AgentFlow(steps=[...]).run("input")
   
4. Production deployment

   Wrap in AgentOS:

   AgentOS(agents=[...]).serve(port=8000)
   

---

Shared Parameters

All orchestrators (AgentTeam, AgentFlow) support identical feature parameters:

Parameter	Type	Description
memory	bool / MemoryConfig	Enable memory
planning	bool / PlanningConfig	Planning mode
context	bool / ContextConfig	Context management
output	str / OutputConfig	Output settings
hooks	HooksConfig	Lifecycle callbacks
autonomy	bool / AutonomyConfig	Agent autonomy
knowledge	bool / KnowledgeConfig	RAG configuration
guardrails	bool / GuardrailConfig	Validation
web	bool / WebConfig	Web search
reflection	bool / ReflectionConfig	Self-reflection
caching	bool / CachingConfig	Caching

---

Best Practices

Start with Agent, scale up

Begin with a single Agent. Only add orchestration when you need multiple agents or complex flows.

Choose one orchestrator per project

Don’t mix AgentTeam and AgentFlow for the same task. Pick based on your mental model:

• AgentTeam = “Who does what” (task assignment)
• AgentFlow = “What happens when” (step sequence)

Use AgentOS for all production deployments

Even for single agents, AgentOS provides proper API structure, CORS, and health checks.

Prefer AgentFlow for deterministic processes

If you need guaranteed execution order, conditional branching, or loops, use AgentFlow.

---

Related

Agents

Agent configuration reference

Tasks

Task configuration reference

Process Types

Sequential, parallel, hierarchical

AgentFlow

Workflow patterns deep dive

AgentOS

Production deployment