Installation

Get OpenAgents running on your system with these simple installation steps. OpenAgents requires Python 3.10 or higher and works on Linux, macOS, and Windows.

System Requirements

Python Version

Python 3.10+ (recommended: Python 3.11 or 3.12)
- We test the package nightly with Python 3.10, 3.11 and 3.12.
pip package manager (included with Python)
Git (for development installation)

Node.js Version (for OpenAgents Studio)

Node.js 20+

Quick Installation

Setup Python environment

We recommend using Conda to create a new environment for OpenAgents.

# Create new environment
conda create -n openagents python=3.12
conda activate openagents

You might also use pyenv or venv to create a new environment for OpenAgents depending on your preference.

Install OpenAgents package

Install OpenAgents through PyPI (strongly recommended)

# Install OpenAgents
pip install openagents
 
# Verify installation
openagents --version

Important: As OpenAgents is under active development, please make sure you have the latest version at this point. Please run pip install --upgrade openagents to get the latest version.

Install with Docker (optional): Alternatively, if you want to quickly spin up a network and test the studio locally, you can use Docker to run OpenAgents.

# Pull the latest image
docker pull ghcr.io/openagents-org/openagents:latest
 
# Run with Docker Compose
docker-compose up
 
# Or run directly
docker run -p 8700:8700 -p 8600:8600 -p 8050:8050 ghcr.io/openagents-org/openagents:latest

Please note even you run the network with docker, you might still need to install the openagents package through pip for using the agent client interfaces to connect your agents to the network.

Development Installation from source

It is also beneficial to install the package from source for the latest features or to contribute to the development. Running the code with the repository gives you easy debug access to the code and also pre-built examples.

# Create a new virtual environment
conda create -n openagents python=3.12
conda activate openagents
 
# Clone the repository
git clone https://github.com/openagents-org/openagents.git
cd openagents
 
# Install in development mode
pip install -e .
 
# Verify installation
openagents --version

Next, let's also install the dependencies for OpenAgents Studio.

# Starting from the root of the repository
cd studio
npm install

💡 Tip: If you are installing the package from source, rather than using openagents studio command to launch both the network and the studio jointly, we strongly recommend to run them separately in two terminal tabs.

In your first terminal tab, run the following command to start the network:

openagents network start examples/default_workspace

In your second terminal tab, run the following command to start the studio:

cd studio
npm start

Troubleshooting: Common Installation Issues

Permission Errors

# Use --user flag for local installation
pip install --user openagents
 
# Or create virtual environment
python -m venv venv
source venv/bin/activate
pip install openagents

Python Version Issues

# Check Python version
python --version
 
# Install specific Python version with pyenv
pyenv install 3.11.7
pyenv global 3.11.7
 
# Or use conda
conda install python=3.11

Network/Firewall Issues

# Use different package index
pip install -i https://pypi.org/simple/ openagents
 
# Or download and install offline
pip download openagents
pip install openagents-*.whl

Missing Dependencies

# Update pip
pip install --upgrade pip
 
# Install with verbose output
pip install -v openagents
 
# Install dependencies separately
pip install pydantic fastapi uvicorn websockets
pip install openagents

Platform-Specific Issues

Windows Specific

# Use Windows Subsystem for Linux (WSL2)
wsl --install
 
# Or install with Windows-specific options
pip install openagents --prefer-binary
 
# Set environment variables
$env:PYTHONPATH="C:\path\to\openagents"

macOS Specific

# Install Xcode command line tools
xcode-select --install
 
# Use Homebrew Python
brew install python@3.11
pip3.11 install openagents
 
# Fix SSL issues
pip install --upgrade certifi

Linux Specific

# Install system dependencies
sudo apt-get update
sudo apt-get install python3-dev python3-pip build-essential
 
# Or on RHEL/CentOS
sudo yum install python3-devel python3-pip gcc
 
# Install OpenAgents
pip3 install openagents

Getting Help

If you encounter issues:

Check Requirements: Verify Python version and dependencies
Search Issues: Check GitHub Issues
Community Support: Ask on Discord
Report Bugs: Create a new issue with details

Next Steps

Once OpenAgents is installed:

Quick Start Guide - Create your first network
Core Concepts - Learn the fundamentals
Start a Network - Set up a collaborative network
Connect Agents - Build your first agent

Installation Complete! OpenAgents is now ready to use. Start with the Quick Start Guide to create your first agent network.

Need Help? Join our Discord community for support, or check the troubleshooting section above for common issues.