Installation Extras

Optional dependencies and feature packages for specialized PraisonAI functionality

PraisonAI provides optional dependency groups (extras) for specific features like bot integrations, gateway servers, and storage backends.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Be helpful.")
agent.start("Hello!")

The user installs optional extras, then runs agents with the features those extras unlock.

How It Works

Quick Start

1. Choose Your Use Case

   Select installation based on your requirements:

   # Basic agent development
   pip install praisonai
   
   # Bot integrations (Telegram, Discord, Slack)
   pip install "praisonai[bot]"
   
   # Gateway server with WebSocket/REST
   pip install "praisonai[api]"
   
   # Visual workflow builder (Langflow)
   pip install "praisonai[flow]"
   
   # Gateway + bots (most common)
   pip install "praisonai[bot,api]"
   
   # Everything included
   pip install "praisonai[all]"

2. Verify Installation

   Test that required dependencies are available:

   # Test core functionality
   from praisonaiagents import Agent
   agent = Agent(name="test", instructions="Hello")
   
   # Test bot integration (if [bot] installed)
   from praisonai.bots import TelegramBot
   
   # Test gateway (if [api] installed)
   from praisonai.gateway import WebSocketGateway

3. Handle Missing Dependencies

   If you encounter import errors, install the required extra:

   # Error: Gateway requires starlette and uvicorn
   pip install "praisonai[api]"
   
   # Error: No module named 'python-telegram-bot'
   pip install "praisonai[bot]"

Available Extras

Bot Integration ([bot])

Enables chat platform integrations:

pip install "praisonai[bot]"

Includes:

• python-telegram-bot – Telegram bot API
• discord.py – Discord bot integration
• slack-sdk – Slack app development
• twilio – WhatsApp Business API
• requests – HTTP client for webhooks

Use cases:

• Telegram bot deployment
• Discord server integration
• Slack workspace apps
• WhatsApp Business messaging
• Multi-platform chat bots

Example:

from praisonai.bots import TelegramBot, DiscordBot

telegram = TelegramBot(token="your_token")
discord = DiscordBot(token="your_token")

API Server ([api])

Enables gateway and web server functionality:

pip install "praisonai[api]"

Includes:

• uvicorn – ASGI server
• fastapi – Web framework
• starlette – WebSocket support
• python-multipart – File upload handling
• websockets – WebSocket protocol

Use cases:

• PraisonAI Gateway deployment
• REST API endpoints
• WebSocket real-time communication
• Agent-as-a-Service hosting
• Dashboard and UI backends

Example:

from praisonai.gateway import WebSocketGateway
from praisonaiagents import GatewayConfig

config = GatewayConfig(host="127.0.0.1", port=8765)
gateway = WebSocketGateway(config=config)

Tools Collection ([tools])

Specialized tools and integrations:

pip install "praisonai[tools]"

Includes:

• tavily-python – Web search API
• requests – HTTP requests
• beautifulsoup4 – HTML parsing
• PyPDF2 – PDF processing
• python-docx – Word document handling

Use cases:

• Web search capabilities
• Document processing
• File format conversion
• Data extraction and parsing
• Research and analysis

Storage Backends ([storage])

Database and vector store integrations:

pip install "praisonai[storage]"

Includes:

• chromadb – Vector database
• qdrant-client – Qdrant vector store
• pinecone-client – Pinecone vector database
• redis – Redis caching
• pymongo – MongoDB integration

Use cases:

• Knowledge base storage
• Vector similarity search
• Session state persistence
• Caching and performance
• Multi-agent coordination

Visual Flow Builder ([flow])

Launch Langflow with PraisonAI Agent and AgentTeam components pre-loaded:

pip install "praisonai[flow]"

Includes:

• langflow>=1.0.0 — visual workflow builder
• requests>=2.31.0 — Langflow REST client
• a2a-sdk[http-server]>=1.0.0 — Langflow transitive dep pinned for Python 3.13 (older versions ship without a2a.server.active_task)
• fastapi-pagination>=0.12.34 — pinned for FastAPI/Starlette compatibility (older versions fail with cannot import name 'EventSourceResponse')

Use cases:

• Launch the Langflow UI with PraisonAI components in the sidebar
• Import/export YAML ↔ Langflow JSON
• Visual multi-agent workflow design

Example:

praisonai flow
# Opens http://localhost:7860 with Agent + Agent Team components

See Flow CLI and Visual Workflow Builder.

Training (praisonai-train)

LLM fine-tuning and iterative agent training ship in the standalone praisonai-train package (Tier 2c).

# Agent training only (lightweight — pulls praisonaiagents + litellm, no CUDA/Unsloth)
pip install praisonai-train

# Adds the Unsloth/torch stack for LLM fine-tuning
pip install "praisonai-train[llm]"

# Full wrapper plus fine-tuning deps
pip install "praisonai[train]"

The bundled setup_conda_env.sh (used by praisonai-train[llm]) now probes the host for a GPU before picking pytorch-cuda=12.4. Nvidia hosts get the CUDA build; AMD hosts get a WARNING pointing at the official PyTorch ROCm instructions; CPU-only Linux hosts get a WARNING that praisonai-train llm refuses to run on CPU (the env is still usable for dataset work and exports). See Train → Conda setup for the decision table.

See Train and praisonai-train Package.

Complete Installation ([all])

All optional dependencies included:

pip install "praisonai[all]"

Includes: All extras above plus additional integrations.

Best for:

• Development environments
• Full-featured deployments
• Experimenting with all features
• Production systems using multiple capabilities

Common Use Cases

Gateway Deployment

Requirement: Multi-channel bot gateway with WebSocket support

pip install "praisonai[bot,api]"

Why both extras:

• [bot] provides Telegram, Discord, Slack integration
• [api] provides gateway WebSocket server and REST endpoints

Configuration:

# gateway.yaml
gateway:
  host: "127.0.0.1"
  port: 8765

channels:
  telegram:
    platform: telegram
    token: ${TELEGRAM_BOT_TOKEN}

Agent Development

Requirement: Basic agent creation and testing

pip install praisonai
# No extras needed for core agent functionality

Example:

from praisonaiagents import Agent

agent = Agent(
    name="researcher", 
    instructions="Research topics thoroughly",
    model="gpt-4o-mini"
)

Production Bot

Requirement: Robust bot with search, storage, and monitoring

pip install "praisonai[all]"

Features enabled:

• Bot platform integration
• Web search and document processing
• Vector knowledge storage
• REST API for monitoring
• All available tools and integrations

Installation Troubleshooting

Common Import Errors

ImportError: Gateway requires starlette and uvicorn.
Install with: pip install praisonai[api]

pip install "praisonai[api]"
# or
pip install "praisonai[bot,api]" # for bot + gateway

ModuleNotFoundError: No module named 'python-telegram-bot'

pip install "praisonai[bot]"

ModuleNotFoundError: No module named 'chromadb'

pip install "praisonai[storage]"
# or
pip install "praisonai[all]"

$env:PYTHONUTF8 = "1"
pip install "praisonai[bot,api]"

# Install Visual Studio Build Tools
# or use conda-forge
conda install -c conda-forge praisonai

Langflow is not installed. Install with: pip install praisonai[flow]

pip install "praisonai[flow]"

pip install --upgrade "praisonai[flow]"
# or, manually:
pip install "a2a-sdk[http-server]>=1.0.0"

pip install --upgrade "praisonai[flow]"
# or, manually:
pip install "fastapi-pagination>=0.12.34"

python -m pip show unclecode-litellm >/dev/null 2>&1 && echo "unclecode-litellm present"
python -c "from litellm.litellm_core_utils.env_utils import get_env_int_in_range" || echo "litellm files clobbered"

# pip
pip install --force-reinstall --no-deps "litellm==$(python -m pip show litellm | awk '/^Version:/{print $2}')"

# uv
uv pip install --reinstall --no-deps "litellm==$(uv pip show litellm | awk '/^Version:/{print $2}')"

python -c "import litellm"

Dependency Conflicts

Handle version conflicts between extras:

# Clean installation
pip uninstall praisonai
pip cache purge

# Reinstall with specific extras
pip install "praisonai[bot,api]==latest"

# Check for conflicts
pip check

Minimal Installation

For resource-constrained environments:

# Core only (smallest footprint)
pip install praisonai --no-deps
pip install openai  # Manual essential deps

# Specific platform only
pip install "praisonai[bot]" --no-deps
pip install python-telegram-bot openai

Extra Dependency Reference

Complete dependency listing by extra:

Platform-Specific Notes

Windows:

• Some packages may require Visual Studio Build Tools
• UTF-8 encoding setup recommended: $env:PYTHONUTF8 = "1"
• Consider using conda for complex dependencies

macOS:

• May require Xcode Command Line Tools
• Install via Homebrew Python for best compatibility

Linux:

• Usually installs without issues
• May need system packages for some features (e.g., libssl-dev)

Best Practices

# Create dedicated environment
python -m venv praisonai-env
source praisonai-env/bin/activate  # Linux/macOS
# or
praisonai-env\Scripts\activate     # Windows

# Install with extras
pip install "praisonai[bot,api]"

# requirements.txt
praisonai[bot,api]==1.2.3
python-telegram-bot==20.7
fastapi==0.104.1

# Development: everything
pip install "praisonai[all]"

# Production bot: minimal
pip install "praisonai[bot]"

# Gateway only: minimal  
pip install "praisonai[api]"

# Check for vulnerabilities
pip-audit

# Update safely
pip install --upgrade "praisonai[all]"
pip check  # Verify no conflicts

Related