<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/1.1-architecture-overview -->

# Architecture Overview

- README.md
- docker/Dockerfile
- docker/Dockerfile.chat
- docker/Dockerfile.dev
- docker/Dockerfile.ui
- docker/README.md
- src/praisonai-agents/pyproject.toml
- src/praisonai-agents/uv.lock
- src/praisonai/README.md
- src/praisonai/praisonai.rb
- src/praisonai/praisonai/cli/main.py
- src/praisonai/praisonai/deploy.py
- src/praisonai/praisonai/version.py
- src/praisonai/pyproject.toml
- src/praisonai/uv.lock

## Purpose and Scope

This document provides a high-level architectural overview of the PraisonAI system, describing the major components, their interactions, and the overall system structure. It serves as an entry point for understanding how PraisonAI orchestrates multi-agent AI systems across different frameworks and deployment targets.

For detailed information about specific subsystems:

- Agent execution and lifecycle -> Agent Class
- Multi-agent coordination -> Multi-Agent Orchestration
- Tool integration -> Tool Integration
- Deployment procedures -> Docker Deployment and Cloud Deployment
- Package internals -> praisonaiagents Package and praisonai Package

## System Layers

PraisonAI is structured as a **10-layer architecture** that separates concerns from user interaction down to infrastructure:

```

```

**Sources:** Diagram 1 from system diagrams, [src/praisonai/praisonai/cli/main.py214-254](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L214-L254) [src/praisonai-agents/pyproject.toml1-102](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L1-L102)

## Package Architecture

PraisonAI consists of **two core packages** with distinct responsibilities:

```

```

**Sources:** [src/praisonai-agents/pyproject.toml1-102](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L1-L102) [src/praisonai/pyproject.toml1-160](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L1-L160) Diagram 5 from system diagrams

### Package Separation

**Dependency Direction**: `praisonai` depends on `praisonaiagents`, never the reverse. This allows users to use the lightweight core library (`praisonaiagents`) without the overhead of framework integrations.

**Sources:** [src/praisonai/pyproject.toml11-22](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L11-L22) [src/praisonai-agents/pyproject.toml6-20](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L6-L20)

### Optional Dependencies

Both packages use **feature groups** for modular installation:

```

```

**Sources:** [src/praisonai-agents/pyproject.toml22-97](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L22-L97) [src/praisonai/pyproject.toml29-145](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L29-L145)

## Core Components

### PraisonAI Orchestrator

The `PraisonAI` class in [src/praisonai/praisonai/cli/main.py214-254](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L214-L254) serves as the **main orchestrator** that:

1. Parses command-line arguments via parse_args() main.py 299
2. Loads agent configurations from YAML via AgentsGenerator main.py 87-90
3. Routes to framework adapters (AutoGen, CrewAI, or native) based on framework parameter main.py 244
4. Manages config_list for LLM provider configuration main.py 223-242

```

```

**Sources:** [src/praisonai/praisonai/cli/main.py214-254](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L214-L254)

### Agent Class

The `Agent` class in `praisonaiagents` is the **fundamental execution unit**:

- Lazy initialization : Features only load when used via __getattr__ mechanism
- Configuration resolution : Converts presets (e.g., memory=True ) to full config objects
- Tool registration : Via @tool decorator or tools=[] parameter
- Memory integration : Short-term, long-term, entity, episodic tiers
- LLM abstraction : Single LLM class supporting 100+ providers via LiteLLM

**Sources:** References to Agent class throughout the diagrams, [src/praisonai-agents/pyproject.toml14-20](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L14-L20)

### AgentManager (AgentTeam)

Coordinates **multi-agent execution** with:

- Task distribution : Sequential, parallel, hierarchical, workflow processes
- State management : Shared context across agents
- Session persistence : Save/resume via session IDs
- MCP/A2A servers : Expose agents as services

**Sources:** Diagram 2 (Multi-Agent Orchestration section), references in README.md

### Workflow Engine

Provides **deterministic execution patterns**:

- route() : Conditional branching based on classifier output
- parallel() : Concurrent agent execution
- loop() : Iteration over lists/CSVs
- repeat() : Evaluator-optimizer pattern with max iterations

**Sources:** Diagram 2 (Orchestration Patterns), README.md workflow examples

## Entry Points and Interfaces

### Command-Line Interface

```

```

Main commands defined in [src/praisonai/praisonai/cli/main.py289-493](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L289-L493):

**Sources:** [src/praisonai/praisonai/cli/main.py328-493](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L328-L493)

### Python SDK

```

```

**Sources:** README.md Python examples section

### REST API

Exposed via FastAPI when using `praisonai[api]`:

- POST /agents - Execute sequential workflow
- POST /agents/:id - Execute individual agent
- GET /health - Health check endpoint
- GET /list - List available agents

**Sources:** Diagram 3 (API Exposure section), [docker/Dockerfile32-46](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L32-L46)

### Web UI

Chainlit-based interfaces served on:

- UI service : Port 8082 (standard agent execution)
- Chat service : Port 8083 (conversational interface)

Configuration centralized in `~/.praison/` to avoid root directory clutter.

**Sources:** [docker/Dockerfile.ui1-33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L1-L33) [docker/Dockerfile.chat1-33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L1-L33) [docker/README.md26-33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L26-L33)

## Deployment Architecture

### Docker Services

```

```

**Directory Management**: All configuration files stored in `~/.praison/` instead of root directory to prevent clutter. Set via environment variables:

```

```

**Sources:** [docker/Dockerfile.ui26-30](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L26-L30) [docker/Dockerfile.chat26-30](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L26-L30) [docker/README.md55-74](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L55-L74)

### Cloud Deployment

The `CloudDeployer` class in [src/praisonai/praisonai/deploy.py6-186](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L6-L186) automates deployment to **Google Cloud Run**:

1. Creates Dockerfile deploy.py 36-63 with Flask/Gunicorn
2. Builds Docker image for linux/amd64 platform deploy.py 140-141
3. Pushes to Google Container Registry deploy.py 144-145
4. Deploys to Cloud Run with environment variables deploy.py 146-149

```

```

**Sources:** [src/praisonai/praisonai/deploy.py1-186](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L1-L186) [src/praisonai/praisonai/cli/main.py422-493](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L422-L493)

## Integration Patterns

### Model Context Protocol (MCP)

PraisonAI supports **4 MCP transports**:

Agents can act as **MCP clients** (consume tools) or **MCP servers** (expose tools).

**Sources:** Diagram 3 (Protocol Integration section), README.md MCP examples

### Agent-to-Agent Protocol (A2A)

Enables **inter-agent communication**:

- /.well-known/agent.json - Agent discovery endpoint
- Task lifecycle API - Create, update, cancel tasks
- Shared task context - Agents coordinate via shared state

**Sources:** Diagram 3 (A2A Server section)

### Framework Adapters

PraisonAI provides **transparent adapters** for existing frameworks:

```

```

All three produce agents backed by the same `praisonaiagents.Agent` class.

**Sources:** [src/praisonai/praisonai/cli/main.py244](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/cli/main.py#L244-L244) [src/praisonai/pyproject.toml91-99](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L91-L99)

## Performance Optimizations

### Lazy Loading

The `_lazy.py` module implements `__getattr__` hooks to defer imports:

- Startup time : Reduced from ~420ms to ~20ms in silent mode
- 186+ symbols mapped to lazy-loaded modules
- Module caching via _lazy_cache prevents re-imports

```

```

**Sources:** Diagram 5 (Lazy Loading Architecture), README.md performance benchmarks

### Configuration Presets

The `resolve()` function converts simple inputs to typed configs:

```

```

**Sources:** Diagram 5 (Configuration Resolution), README.md configuration examples

## Data Flow Example

```

```

**Sources:** Diagram 2 (Task Execution section), code flow analysis

## Key Design Principles

1. Modularity : Optional dependencies, feature groups, lazy loading
2. Multi-framework : Single agent model, multiple framework adapters
3. Protocol-first : MCP and A2A enable ecosystem integration
4. Zero-overhead : Features only load when used
5. Deployment flexibility : Local, Docker, Cloud Run support
6. Configuration layering : Presets -> Dicts -> Config objects -> Instances

**Sources:** Analysis across all diagrams and code files
