<!-- source: https://deepwiki.com/MervinPraison/PraisonAI/9.4-api-server-launch -->

# API Server Launch

- docker/Dockerfile
- docker/Dockerfile.chat
- docker/Dockerfile.dev
- docker/Dockerfile.ui
- docker/README.md
- src/praisonai-agents/praisonaiagents/agents/agents.py
- src/praisonai-agents/pyproject.toml
- src/praisonai-agents/uv.lock
- 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 covers the `launch()` method and related infrastructure for exposing PraisonAI agents as network-accessible API servers. It details how agents can be served via FastAPI REST endpoints, MCP (Model Context Protocol) servers, and A2A (Agent-to-Agent) protocol servers.

For information about:

- Cloud deployment using CloudDeployer , see Cloud Deployment
- Docker container orchestration, see Docker Deployment
- Local development setup, see Development Environment

## Overview

The API server launch system provides three primary modes for exposing agents as network services:

1. FastAPI Mode - REST API with HTTP endpoints for agent execution
2. MCP Mode - Model Context Protocol server supporting SSE/WebSocket transports
3. A2A Mode - Agent-to-Agent discovery and task management protocol

## Server Management Architecture

**Diagram: Server Management and State Flow**

```

```

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

The launch system uses three global dictionaries to manage server lifecycle and prevent port conflicts:

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

## FastAPI Server Mode

### REST API Endpoints

The FastAPI server mode exposes agents through HTTP REST endpoints:

**Sources:** Diagram 3 from system architecture overview

### Endpoint Registration Flow

**Diagram: Endpoint Registration Sequence**

```

```

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

### Docker Deployment Configuration

The API server is deployed using Docker containers with standardized port mappings:

**Port Allocation:**

- API Service: 8080:8080
- UI Service: 8082:8082
- Chat Service: 8083:8083

**Environment Variables:**

```

```

**Sources:** [docker/Dockerfile1-46](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L1-L46) [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.md1-264](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L1-L264)

### Dockerfile Build Pipeline

**Diagram: API Service Dockerfile Configuration**

```

```

**Sources:** [docker/Dockerfile1-46](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L1-L46)

The Dockerfile automatically creates a health check endpoint if `api.py` doesn't exist:

```

```

**Sources:** [docker/Dockerfile32-43](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L32-L43)

## MCP Server Mode

### Model Context Protocol Transports

The MCP server mode enables agents to communicate using the Model Context Protocol with multiple transport mechanisms:

**Sources:** Diagram 3 from system architecture overview

### MCP Endpoint Architecture

**Diagram: MCP Server Endpoints and Client Connections**

```

```

**Sources:** Diagram 3 from system architecture overview

### MCP Dependencies

MCP server functionality requires the optional `mcp` package group:

**Installation:**

```

```

**Included Dependencies:**

**Sources:** [src/praisonai-agents/pyproject.toml22-28](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L22-L28)

## A2A Server Mode

### Agent-to-Agent Protocol Endpoints

The A2A server mode provides agent discovery and inter-agent communication through standardized endpoints:

**Sources:** Diagram 3 from system architecture overview

### A2A Communication Flow

**Diagram: A2A Discovery and Task Execution**

```

```

**Sources:** Diagram 3 from system architecture overview

## Global State Management

### State Dictionary Structure

The server launch system maintains three global dictionaries to coordinate server instances and prevent conflicts:

**State Variables:**

```

```

**Design Purpose:**

- _agents_server_started prevents duplicate server creation on the same port
- _agents_registered_endpoints tracks endpoint paths to detect conflicts
- _agents_shared_apps enables multiple agents to share a single server instance

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

### Port Allocation Strategy

**Diagram: Port Allocation Decision Flow**

```

```

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

## Configuration and Environment

### Environment Variable Configuration

**Core Environment Variables:**

**Sources:** [docker/Dockerfile.dev40-44](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L40-L44) [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)

### Directory Management

Docker containers use a centralized configuration directory to avoid cluttering the root filesystem:

**Directory Structure:**

```
~/.praison/
|-- database.sqlite      # Chainlit database
|-- chainlit.md         # Chainlit configuration
|-- .chainlit/          # Chainlit runtime files
`-- config/             # PraisonAI configuration
```

**Benefits:**

- Single location for all configuration and runtime files
- Easy volume mounting for persistent data
- Clean container root directory
- Simplified backup and migration workflows

**Sources:** [docker/README.md54-73](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L54-L73)

## Cloud Deployment Integration

### CloudDeployer Architecture

**Diagram: CloudDeployer Deployment Pipeline**

```

```

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

### CloudDeployer Class Methods

**Generated Dockerfile Template:**

```

```

**Sources:** [src/praisonai/praisonai/deploy.py56-62](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L56-L62)

### Deployment Pipeline Steps

**1. Configure Docker Authentication**

```

```

**2. Create Artifact Repository**

```

```

**3. Build Multi-Architecture Image**

```

```

**4. Tag and Push to Registry**

```

```

**5. Deploy to Cloud Run**

```

```

**Sources:** [src/praisonai/praisonai/deploy.py136-149](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/deploy.py#L136-L149)

## Health Checks and Monitoring

### Health Check Implementation

All Docker services include automatic health check endpoints:

**Health Check Configuration:**

```

```

**Service-Specific Ports:**

**Sources:** [docker/README.md110-119](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L110-L119)

### Default Health Endpoint

If no `api.py` file exists, the Docker container automatically creates a basic health check:

```

```

**Sources:** [docker/Dockerfile32-43](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L32-L43)

## Multi-Service Orchestration

### Docker Compose Architecture

**Diagram: Multi-Service Docker Compose Deployment**

```

```

**Sources:** [docker/README.md36-51](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L36-L51)

### Service Startup Commands

**Sources:** [docker/Dockerfile46](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile#L46-L46) [docker/Dockerfile.ui33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L33-L33) [docker/Dockerfile.chat33](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.chat#L33-L33) [docker/Dockerfile.dev47](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L47-L47)

## Package Dependencies

### Optional API Package Groups

The API server functionality is split into optional installation groups:

**PraisonAI API Dependencies (pip install "praisonai[api]"):**

```

```

**PraisonAI Agents API Dependencies (pip install "praisonaiagents[api]"):**

```

```

**Sources:** [src/praisonai/pyproject.toml37-42](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/pyproject.toml#L37-L42) [src/praisonai-agents/pyproject.toml54-58](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L54-L58)

### Core Version Constraints

**Sources:** [docker/Dockerfile.dev23](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.dev#L23-L23) [docker/Dockerfile.ui19](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/Dockerfile.ui#L19-L19) [src/praisonai/praisonai/version.py1](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai/praisonai/version.py#L1-L1) [src/praisonai-agents/pyproject.toml7](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/src/praisonai-agents/pyproject.toml#L7-L7)

## Production Deployment Best Practices

### Resource Limits

Configure resource limits in Docker Compose for production stability:

```

```

**Sources:** [docker/README.md240-246](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L240-L246)

### Load Balancer Configuration

Example nginx configuration for multiple API instances:

```

```

**Sources:** [docker/README.md249-262](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L249-L262)

### Security Configuration

**Environment Security:**

- Store API keys in .env file or secrets manager (never in source code)
- Use non-root user execution where applicable
- Implement authentication middleware for public endpoints
- Configure HTTPS/TLS termination at load balancer or reverse proxy

**Docker Security:**

- Use minimal base image ( python:3.11-slim ) to reduce attack surface
- Remove unnecessary packages and build tools from production images
- Implement read-only root filesystem where feasible
- Regular security updates for base images and dependencies

**Sources:** [docker/README.md129-135](https://github.com/MervinPraison/PraisonAI/blob/ab80807b/docker/README.md?plain=1#L129-L135)
