Development Setup

Prerequisites

Before you begin, ensure you have the following installed:

Python 3.10+: Swarms requires Python 3.10 or higher
Git: For version control
pip, uv, or poetry: For package management

Installation Methods

Using pip

The simplest way to install Swarms for development:

pip3 install -U swarms

Using uv (Recommended)

uv is a fast Python package installer and resolver, written in Rust.

# Install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install swarms using uv
uv pip install swarms

Using poetry

# Install poetry if you haven't already
curl -sSL https://install.python-poetry.org | python3 -

# Add swarms to your project
poetry add swarms

From Source (For Contributors)

If you’re planning to contribute to Swarms, you should install from source:

# Clone the repository
git clone https://github.com/kyegomez/swarms.git
cd swarms

# Install with pip in editable mode
pip install -e .

# Or install dependencies directly
pip install -r requirements.txt

Environment Configuration

Create a .env file in your project root with the necessary API keys and configuration:

OPENAI_API_KEY="your-openai-api-key"
WORKSPACE_DIR="agent_workspace"
ANTHROPIC_API_KEY="your-anthropic-api-key"
GROQ_API_KEY="your-groq-api-key"

Learn more about environment configuration in the Environment Configuration Guide.

API Keys

You’ll need API keys from various providers depending on which models you plan to use:

OpenAI: Get API Key
Anthropic (Claude): Get API Key
Groq: Get API Key

Project Structure

Understanding the project structure will help you navigate and contribute effectively:

swarms/: Contains all the source code for the library
- agents/: Agent implementations and base classes
- structs/: Swarm orchestration structures (SequentialWorkflow, AgentRearrange, etc.)
- tools/: Tool implementations and base classes
- prompts/: System prompts and prompt templates
- utils/: Utility functions and helpers
examples/: Includes example scripts and notebooks demonstrating how to use the library
tests/: Unit tests for the library
docs/: Documentation files and guides

Development Workflow

1. Fork and Clone

First, fork the repository on GitHub and clone your fork:

git clone https://github.com/YOUR_USERNAME/swarms.git
cd swarms

2. Create a Branch

Create a new branch for your feature or bug fix:

git checkout -b feature/your-feature-name

3. Make Changes

Make your changes to the codebase. Ensure you follow the coding standards.

4. Run Tests

Before submitting your changes, run the test suite to ensure everything works:

# Run all tests
pytest tests/

# Run specific test file
pytest tests/test_agent.py

# Run with coverage
pytest --cov=swarms tests/

5. Lint Your Code

Ensure your code follows PEP 8 standards:

# Using flake8
flake8 swarms/

# Using black (auto-formatter)
black swarms/

# Using pylint
pylint swarms/

6. Commit Your Changes

Write clear and descriptive commit messages:

git add .
git commit -m "Add feature: descriptive message about your changes"

7. Push to Your Fork

git push origin feature/your-feature-name

8. Create a Pull Request

Go to the original repository on GitHub and create a pull request from your fork.

Testing Guidelines

Writing Tests

All new features and bug fixes must include appropriate tests:

import pytest
from swarms import Agent

def test_agent_creation():
    """Test that an agent can be created successfully."""
    agent = Agent(
        agent_name="TestAgent",
        model_name="gpt-5.4",
        max_loops=1
    )
    assert agent.agent_name == "TestAgent"
    assert agent.model_name == "gpt-5.4"

def test_agent_run():
    """Test that an agent can run a simple task."""
    agent = Agent(
        agent_name="TestAgent",
        model_name="gpt-5.4",
        max_loops=1
    )
    result = agent.run("Say hello")
    assert result is not None
    assert len(result) > 0

Test Organization

Place tests in the tests/ directory
Mirror the structure of the swarms/ directory
Use descriptive test names that explain what is being tested
Group related tests in the same file

Running Specific Tests

# Run tests for a specific module
pytest tests/test_agent.py

# Run tests matching a pattern
pytest -k "test_agent"

# Run with verbose output
pytest -v tests/

# Run with coverage report
pytest --cov=swarms --cov-report=html tests/

Documentation

Building Documentation Locally

If you’re contributing to documentation:

# Install documentation dependencies
pip install mkdocs mkdocs-material

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

Writing Documentation

When adding new features, always update the documentation:

Add docstrings to all public classes and functions
Update relevant documentation pages in docs/
Add examples demonstrating the new feature
Update the API reference if necessary

Debugging Tips

Enable Verbose Logging

from swarms import Agent

agent = Agent(
    agent_name="DebugAgent",
    model_name="gpt-5.4",
    verbose=True  # Enable verbose output
)

Use Interactive Mode

agent = Agent(
    agent_name="InteractiveAgent",
    model_name="gpt-5.4",
    interactive=True  # Enable interactive mode
)

Check Logs

Swarms provides comprehensive logging. Check the logs in your workspace directory for debugging information.

Common Issues and Solutions

Import Errors

If you encounter import errors, ensure you’ve installed all dependencies:

pip install -r requirements.txt

API Key Errors

Make sure your .env file is properly configured with valid API keys.

Test Failures

If tests fail:

Check that you have the latest version of dependencies
Ensure your environment variables are set correctly
Run tests in verbose mode for more details: pytest -v

Getting Help

If you encounter any issues during development:

Check the FAQ
Search existing GitHub issues
Ask on Discord
Schedule an onboarding session

Ready to Contribute?

Now that you have your development environment set up, check out the Contributing Guide to learn how to make your first contribution!

Contributing

Protocol

Support

Development Setup

Prerequisites

Installation Methods

Using pip

Using uv (Recommended)

Using poetry

From Source (For Contributors)

Environment Configuration

API Keys

Project Structure

Development Workflow

1. Fork and Clone

2. Create a Branch

3. Make Changes

4. Run Tests

5. Lint Your Code

6. Commit Your Changes

7. Push to Your Fork

8. Create a Pull Request

Testing Guidelines

Writing Tests

Test Organization

Running Specific Tests

Documentation

Building Documentation Locally

Writing Documentation

Debugging Tips

Enable Verbose Logging

Use Interactive Mode

Check Logs

Common Issues and Solutions

Import Errors

API Key Errors

Test Failures

Getting Help

Ready to Contribute?

​Prerequisites

​Installation Methods

​Using pip

​Using uv (Recommended)

​Using poetry

​From Source (For Contributors)

​Environment Configuration

​API Keys

​Project Structure

​Development Workflow

​1. Fork and Clone

​2. Create a Branch

​3. Make Changes

​4. Run Tests

​5. Lint Your Code

​6. Commit Your Changes

​7. Push to Your Fork

​8. Create a Pull Request

​Testing Guidelines

​Writing Tests

​Test Organization

​Running Specific Tests

​Documentation

​Building Documentation Locally

​Writing Documentation

​Debugging Tips

​Enable Verbose Logging

​Use Interactive Mode

​Check Logs

​Common Issues and Solutions

​Import Errors

​API Key Errors

​Test Failures

​Getting Help

Ready to Contribute?

Prerequisites

Installation Methods

Using pip

Using uv (Recommended)

Using poetry

From Source (For Contributors)

Environment Configuration

API Keys

Project Structure

Development Workflow

1. Fork and Clone

2. Create a Branch

3. Make Changes

4. Run Tests

5. Lint Your Code

6. Commit Your Changes

7. Push to Your Fork

8. Create a Pull Request

Testing Guidelines

Writing Tests

Test Organization

Running Specific Tests

Documentation

Building Documentation Locally

Writing Documentation

Debugging Tips

Enable Verbose Logging

Use Interactive Mode

Check Logs

Common Issues and Solutions

Import Errors

API Key Errors

Test Failures

Getting Help