> ## Documentation Index
> Fetch the complete documentation index at: https://docs.praison.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Building Multi-Agent Systems

> Learn how to orchestrate multiple AI agents working together

# Building Multi-Agent Systems

This guide shows you how to create systems where multiple agents collaborate to complete complex tasks.

## Prerequisites

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
pip install praisonaiagents
```

## Basic Multi-Agent Setup

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Task, AgentTeam

# Create agents
researcher = Agent(
    name="Researcher",
    role="Research Specialist",
    goal="Find accurate information on topics",
    instructions="Search for and compile relevant information."
)

writer = Agent(
    name="Writer",
    role="Content Writer",
    goal="Write clear and engaging content",
    instructions="Write well-structured content based on research."
)

# Create tasks
research_task = Task(
    description="Research the latest AI developments",
    expected_output="A summary of key AI developments",
    agent=researcher
)

writing_task = Task(
    description="Write a blog post based on the research",
    expected_output="A 500-word blog post",
    agent=writer
)

# Run the agents
agents = AgentTeam(
    agents=[researcher, writer],
    tasks=[research_task, writing_task]
)

result = agents.start()
print(result)
```

## Process Types

### Sequential Process

Agents execute tasks one after another:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import AgentTeam

agents = AgentTeam(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process="sequential"  # Default
)
```

### Hierarchical Process

A manager agent delegates to worker agents:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import AgentTeam

agents = AgentTeam(
    agents=[researcher, writer, editor],
    tasks=[research_task, writing_task, editing_task],
    process="hierarchical",
    manager_llm="gpt-4o"
)
```

## Agent Handoffs

Enable agents to hand off tasks to each other:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent

# Define which agents can hand off to which
researcher = Agent(
    name="Researcher",
    instructions="Research topics. Hand off to Writer when done.",
    handoff=["Writer"]
)

writer = Agent(
    name="Writer",
    instructions="Write content. Hand off to Editor for review.",
    handoff=["Editor"]
)

editor = Agent(
    name="Editor",
    instructions="Edit and finalize content."
)
```

## Shared Memory

Agents can share memory for context:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent, Memory, AgentTeam

# Create shared memory
shared_memory = Memory()

researcher = Agent(name="Researcher", memory=shared_memory)
writer = Agent(name="Writer", memory=shared_memory)

# Both agents can access shared context
```

## Task Dependencies

Define task dependencies for complex workflows:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Task

research_task = Task(
    description="Research the topic",
    agent=researcher
)

analysis_task = Task(
    description="Analyze the research",
    agent=analyst,
    context=[research_task]  # Depends on research
)

writing_task = Task(
    description="Write based on analysis",
    agent=writer,
    context=[research_task, analysis_task]  # Depends on both
)
```

## Parallel Execution

Run independent tasks in parallel:

```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import AgentTeam

# These tasks have no dependencies, so they run in parallel
agents = AgentTeam(
    agents=[researcher1, researcher2, researcher3],
    tasks=[
        Task(description="Research AI", agent=researcher1),
        Task(description="Research ML", agent=researcher2),
        Task(description="Research NLP", agent=researcher3)
    ],
    process="parallel"
)
```

## YAML Configuration

Define multi-agent systems in YAML:

```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# agents.yaml
agents:
  - name: Researcher
    role: Research Specialist
    goal: Find accurate information
    tools:
      - web_search
      
  - name: Writer
    role: Content Writer
    goal: Write engaging content
    
  - name: Editor
    role: Content Editor
    goal: Polish and finalize content

tasks:
  - description: Research the topic
    agent: Researcher
    expected_output: Research summary
    
  - description: Write a blog post
    agent: Writer
    expected_output: Draft blog post
    context:
      - Research the topic
      
  - description: Edit the blog post
    agent: Editor
    expected_output: Final blog post
    context:
      - Write a blog post
```

Run with:

```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai agents agents.yaml
```

## Best Practices

1. **Clear Roles**: Give each agent a distinct role and goal
2. **Specific Instructions**: Provide detailed instructions for each agent
3. **Task Dependencies**: Use `context` to define task dependencies
4. **Appropriate Tools**: Give agents only the tools they need
5. **Error Handling**: Use try/catch for robust execution

## Next Steps

* [Workflows](/docs/guides/workflows/routing) - Advanced workflow patterns
* [Handoff](/docs/concepts/handoff) - Agent handoff concepts
* [Agents Module Reference](/docs/sdk/praisonaiagents/agents/agents) - Full API reference