<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/2.5-multi-agent-orchestration -->

# Multi-Agent Orchestration

- api.md
- src/praisonai-agents/praisonaiagents/agents/agents.py

## Purpose and Scope

This document describes the multi-agent orchestration system in PraisonAI, which coordinates the execution of tasks across multiple Agent instances. The orchestration layer manages task delegation, execution flow, state management, and result aggregation for multi-agent workflows.

**Related Pages:**

- For single agent execution and lifecycle, see Agent Class
- For task definition and execution details, see Task System
- For workflow control structures, see Workflow System
- For process strategy patterns, see Process Strategies
- For planning-based orchestration, see Planning System

## Core Class: AgentTeam

The `AgentTeam` class (formerly `AgentManager`) is the primary orchestrator for multi-agent workflows. It manages multiple `Agent` instances, coordinates task execution, and provides shared infrastructure like memory, state management, and context handling.

**Key Responsibilities:**

- Delegate tasks to appropriate agents
- Manage execution flow (sequential, parallel, hierarchical, workflow)
- Maintain shared state across agents
- Provide session persistence
- Integrate planning mode
- Expose agents via HTTP and MCP APIs

**Class Hierarchy:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py172-246](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L172-L246)

## Initialization and Configuration

The `AgentTeam.__init__()` method uses a consolidated parameter system with canonical resolution for all features. Parameters support multiple input formats: booleans, strings (presets), lists, config objects, or dict configurations.

**Consolidated Parameters:**

**Parameter Resolution Flow:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py200-246](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L200-L246) [src/praisonai-agents/praisonaiagents/agents/agents.py256-394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L256-L394)

## Process Strategies

AgentTeam supports four execution patterns, each managed by the `Process` class:

### Sequential Process

Tasks execute one after another, with each task's output automatically passed as context to the next task.

```

```

**Implementation:** Tasks are executed sequentially with `process.sequential()` iterator. Each task's `result.raw` is appended to the next task's context.

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py839-863](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L839-L863) [src/praisonai-agents/praisonaiagents/agents/agents.py1190-1192](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1190-L1192)

### Parallel Process

Tasks execute concurrently using asyncio.gather for maximum throughput.

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py809-863](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L809-L863)

### Hierarchical Process

A manager agent delegates tasks to worker agents based on their capabilities.

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py864-875](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L864-L875) [src/praisonai-agents/praisonaiagents/agents/agents.py1193-1197](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1193-L1197)

### Workflow Process

Tasks execute with advanced control flow using `AgentFlow` constructs (route, parallel, loop, repeat).

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py819-838](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L819-L838) [src/praisonai-agents/praisonaiagents/agents/agents.py1187-1189](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1187-L1189)

## Task Execution Pipeline

The task execution pipeline processes each task through multiple stages, from context assembly to result storage.

### Execution Flow

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py1097-1175](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1097-L1175) [src/praisonai-agents/praisonaiagents/agents/agents.py930-1095](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L930-L1095)

### Context Processing

The `process_task_context()` helper function standardizes context item processing for both sync and async execution:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py111-170](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L111-L170) [src/praisonai-agents/praisonaiagents/agents/agents.py659-677](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L659-L677) [src/praisonai-agents/praisonaiagents/agents/agents.py983-1001](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L983-L1001)

### Multimodal Support

Tasks with `images` attribute support multimodal processing for images and videos:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py38-108](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L38-L108) [src/praisonai-agents/praisonaiagents/agents/agents.py684-694](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L684-L694) [src/praisonai-agents/praisonaiagents/agents/agents.py1021-1031](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1021-L1031)

## State Management

AgentTeam provides a flexible state management system via the `_state` dictionary with convenience methods for common operations.

### State Operations

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py1405-1473](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1405-L1473)

### Session Persistence

State can be persisted to shared memory for session recovery:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py1475-1518](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1475-L1518)

## Planning Mode

When `planning=True`, AgentTeam uses a `PlanningAgent` to generate an execution plan before running tasks. The plan is converted to a `TodoList` for progress tracking.

### Planning Workflow

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2228-2362](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2228-L2362) [src/praisonai-agents/praisonaiagents/agents/agents.py2068-2149](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2068-L2149) [src/praisonai-agents/praisonaiagents/agents/agents.py2151-2226](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2151-L2226)

### Plan-to-Task Conversion

The planning mode creates proper `Task` objects from `PlanStep` instances, preserving all features from original tasks:

**Preserved Features:**

- Memory integration ( task.memory )
- Callbacks ( on_task_complete )
- Guardrails ( task.guardrail )
- Structured output ( output_json , output_pydantic )
- Retry logic ( max_retries )
- Tools ( agent.tools )

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py2301-2360](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L2301-L2360)

## Memory Integration

AgentTeam provides shared memory accessible to all agents and tasks. Memory is configured once and propagated to all tasks.

### Shared Memory Architecture

```

```

**Memory Configuration Resolution:**

The memory parameter accepts multiple formats:

- bool : True enables with defaults, False disables
- str : Preset name (e.g., "chromadb") or database URL
- MultiAgentMemoryConfig : Full config object
- dict : Configuration dictionary
- db() instance: Direct database connection

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py341-368](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L341-L368) [src/praisonai-agents/praisonaiagents/agents/agents.py501-544](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L501-L544) [src/praisonai-agents/praisonaiagents/agents/agents.py1003-1013](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1003-L1013)

## Context Management

AgentTeam supports unified context management via the `context` parameter, which lazily initializes a `MultiAgentContextManager` for per-agent context isolation.

### Context Manager Integration

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py569-612](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L569-L612) [src/praisonai-agents/praisonaiagents/agents/agents.py486-489](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L486-L489)

## Token Tracking

AgentTeam integrates with the telemetry system to track token usage across all agents. Token metrics are automatically collected per agent, model, and task.

### Token Collection Flow

```

```

**Token Metrics Structure:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py15-19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L15-L19) [src/praisonai-agents/praisonaiagents/agents/agents.py645-648](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L645-L648) [src/praisonai-agents/praisonaiagents/agents/agents.py968-971](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L968-L971) [src/praisonai-agents/praisonaiagents/agents/agents.py716-719](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L716-L719) [src/praisonai-agents/praisonaiagents/agents/agents.py1065-1068](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1065-L1068) [src/praisonai-agents/praisonaiagents/agents/agents.py1520-1589](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1520-L1589)

## API Deployment

AgentTeam provides two deployment modes via the `launch()` method: HTTP (FastAPI) and MCP (Model Context Protocol).

### HTTP API Mode

In HTTP mode, agents are exposed as REST endpoints. The system supports:

- Workflow endpoint : Sequential execution through all agents
- Per-agent endpoints : Direct access to individual agents
- Shared server : Multiple AgentTeam instances can share a single FastAPI server on the same port

```

```

**Endpoint Structure:**

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py1591-1882](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1591-L1882) [src/praisonai-agents/praisonaiagents/agents/agents.py33-36](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L33-L36)

### MCP Server Mode

In MCP mode, the workflow is exposed as a single MCP tool that executes all agents sequentially.

```

```

**MCP Tool Naming:**

The tool name is dynamically generated based on the `name` parameter:

- name="MyWorkflow" -> execute_myworkflow_workflow
- name=None -> execute_workflow

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py1884-2026](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1884-L2026)

## Execution Methods

AgentTeam provides multiple execution methods with different behaviors:

### start() vs run()

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py1223-1389](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1223-L1389) [src/praisonai-agents/praisonaiagents/agents/agents.py1391-1403](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1391-L1403)

### Async Support

Both sync and async execution methods are provided:

- Sync : start() , run() , run_all_tasks() , run_task() , execute_task()
- Async : astart() , arun_all_tasks() , arun_task() , aexecute_task()

Async methods properly handle mixed sync/async tasks using `asyncio.run_in_executor()` with context propagation via `copy_context_to_callable()`.

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py877-916](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L877-L916) [src/praisonai-agents/praisonaiagents/agents/agents.py809-876](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L809-L876) [src/praisonai-agents/praisonaiagents/agents/agents.py1177-1197](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1177-L1197)

## Lifecycle Hooks

AgentTeam supports lifecycle callbacks for workflow monitoring and custom logic:

### Hook Configuration

Hooks are configured via the `hooks` parameter:

```

```

### Hook Execution Points

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py322-337](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L322-L337) [src/praisonai-agents/praisonaiagents/agents/agents.py1107-1112](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1107-L1112) [src/praisonai-agents/praisonaiagents/agents/agents.py1151-1156](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1151-L1156) [src/praisonai-agents/praisonaiagents/agents/agents.py614-619](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L614-L619)

## Task Status Management

Tasks progress through a state machine with retries:

```

```

**Status Constants:**

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py22-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L22-L28) [src/praisonai-agents/praisonaiagents/agents/agents.py1118-1175](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1118-L1175) [src/praisonai-agents/praisonaiagents/agents/agents.py758-807](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L758-L807)

## Telemetry Integration

AgentTeam integrates with the telemetry system to track execution metrics:

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py545-550](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L545-L550) [src/praisonai-agents/praisonaiagents/agents/agents.py886-887](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L886-L887) [src/praisonai-agents/praisonaiagents/agents/agents.py1247-1249](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1247-L1249) [src/praisonai-agents/praisonaiagents/agents/agents.py1365-1372](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L1365-L1372)

## Configuration Resolution Details

AgentTeam uses the canonical `resolve()` function for all consolidated parameters. The resolution process follows this precedence:

**Resolution Precedence (Highest to Lowest):**

1. Direct instance (e.g., Memory object, ContextManager instance)
2. Config class instance (e.g., MultiAgentMemoryConfig)
3. Dictionary with config keys
4. List: [preset_name, override_dict]
5. String preset name or URL
6. Boolean (True = default config, False = disabled)
7. Default value

**Example Resolution:**

```

```

**Sources:** [src/praisonai-agents/praisonaiagents/agents/agents.py256-394](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/praisonaiagents/agents/agents.py#L256-L394)

## Summary

The `AgentTeam` class provides a comprehensive multi-agent orchestration layer with:

- Flexible Execution : Four process strategies (sequential, parallel, hierarchical, workflow)
- Shared Infrastructure : Memory, state, context management
- Advanced Features : Planning mode, session persistence, token tracking
- Multiple Interfaces : Python API, HTTP REST, MCP server
- Rich Monitoring : Lifecycle hooks, verbose output, telemetry integration

The consolidated parameter system with canonical resolution ensures consistent, type-safe configuration across all features while maintaining backward compatibility and zero-overhead when features are disabled.
