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.

Package split. Framework integrations (CrewAI, AutoGen, AG2) are now distributed through a separate package:

# Native runtime (recommended)
pip install praisonaiagents

# Framework integrations (CrewAI, AutoGen, AG2)
pip install praisonai-frameworks[crewai]
pip install praisonai-frameworks[autogen]
pip install praisonai-frameworks[ag2]

# Legacy (deprecated) — still works but will be removed
# pip install 'praisonai[crewai]'  # use praisonai-frameworks[crewai] instead

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]"
   

   praisonaiagents[all] also installs the [autonomy] and [os] optional groups (verification hooks, OS/gateway helpers). The wrapper extra praisonai[all] focuses on bots, gateway, and tools — add pip install "praisonaiagents[autonomy]" or "praisonaiagents[os]" when you need only those slices.

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

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]"

pip install "praisonai[train]" previously installed nothing (empty extra). It now pulls praisonai-train[llm], so it installs the Unsloth stack.

Command	Gets you	When to use
pip install praisonai-train	praisonai-train agents/list/show/apply/benchmark, no CUDA/Unsloth; litellm included for LLM-as-Judge grading	Fastest way to try LLM-as-Judge / human-feedback agent training, or benchmark deployments before you fine-tune
pip install "praisonai-train[llm]"	Above + Unsloth/torch stack for praisonai-train llm	Fine-tuning a base model
pip install praisonai	Full stack: praisonai train ... routes through the code tier	Standard PraisonAI install
pip install "praisonai[train]"	Now equivalent to praisonai + praisonai-train[llm]	Full stack plus fine-tuning deps

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

Gateway requires starlette and uvicorn

Error:

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

Solution:

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

No module named 'python-telegram-bot'

Error:

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

Solution:

pip install "praisonai[bot]"

This happens when trying to use Telegram integration without the bot extra.

No module named 'chromadb'

Error:

ModuleNotFoundError: No module named 'chromadb'

Solution:

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

Vector storage requires the storage extra.

Cannot install on Windows

Symptoms: Package installation fails on Windows

Solutions:

For encoding issues:

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

For build errors:

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

Langflow is not installed

Error:

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

Solution:

pip install "praisonai[flow]"

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:

Extra	Key Dependencies	Size	Use Case
[bot]	python-telegram-bot, discord.py, slack-sdk	~50MB	Chat platform integration
[api]	uvicorn, fastapi, starlette	~30MB	Web server and WebSocket
[tools]	tavily-python, beautifulsoup4, PyPDF2	~25MB	Document and web processing
[storage]	chromadb, qdrant-client, pymongo	~100MB	Databases and vector stores
[flow]	langflow, requests	~500MB	Visual workflow builder (Langflow)
praisonai-train	praisonaiagents, litellm	~5MB	Iterative agent training (no CUDA/Unsloth)
praisonai-train[llm]	unsloth, torch	~2GB	LLM fine-tuning via Unsloth
[all]	All of the above + additional	~200MB	Complete functionality

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

Use virtual environments

Always isolate PraisonAI installations:

# 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]"

Pin versions in production

Use specific versions for reproducible builds:

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

Install only needed extras

Minimize dependency footprint:

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

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

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

Monitor dependency security

Keep dependencies updated:

# Check for vulnerabilities
pip-audit

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

---

Related

Gateway Overview

Gateway requires [api] extra

Bot Integrations

Bot platforms require [bot] extra

praisonai-train Package

Training ships in praisonai-train

Package Tiers

How the six packages stack