Skip to content

Installation

Jump to bottom
Michael Goetz edited this page Jun 14, 2025 · 4 revisions

Installation Guide

This guide provides detailed instructions for installing and setting up the Multi-Agent Framework.

Table of Contents

Prerequisites

System Requirements

  • Python: 3.10 or higher
  • Memory: 4GB RAM minimum (8GB recommended)
  • Storage: 500MB for framework + space for your projects
  • OS: Linux, macOS, or Windows 10/11

Required Software

# Check Python version
python --version  # Should be 3.10+

# Check pip
pip --version

# Git (for source installation)
git --version

API Keys

You'll need at least one LLM provider API key:

Installation Methods

Install from PyPI

Coming Soon! Once published, you'll be able to install with:

pip install multi-agent-framework

Install from Source

1. Clone the Repository

git clone https://github.com/micgo/maf-standalone.git
cd maf-standalone

2. Create Virtual Environment

# Create virtual environment
python -m venv venv

# Activate virtual environment
# On Linux/macOS:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

3. Install Package

# Install in standard mode
pip install .

# Or install in editable mode (for development)
pip install -e .

Development Installation

For contributors and developers:

# Clone and enter directory
git clone https://github.com/micgo/maf-standalone.git
cd maf-standalone

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install with development dependencies
pip install -e ".[dev]"

# Install pre-commit hooks (optional)
pre-commit install

Initial Setup

1. Initialize Your Project

Navigate to your project directory and run:

cd /path/to/your/project
maf init

This creates:

  • .maf-config.json - Project configuration
  • .env.example - Template for API keys
  • .maf/ - Runtime directory containing:
    • state.json - Framework state tracking
    • message_queues/ - Agent message queues
  • .maf_logs/ - Log files

2. Configure API Keys

Copy the environment template:

cp .env.example .env

Edit .env and add your API keys:

# Add at least one of these:
GEMINI_API_KEY=your_actual_gemini_key_here
ANTHROPIC_API_KEY=your_actual_claude_key_here
OPENAI_API_KEY=your_actual_openai_key_here

Security Note: Never commit .env to version control!

3. Verify Configuration

Check that MAF is properly configured:

maf config

This displays your current configuration and validates API keys.

Verification

Test Installation

# Check MAF version
maf --version

# Run help command
maf --help

# Test framework
python -m pytest tests/  # If installed from source

Launch Test Agents

# Start agents in test mode
maf launch --agents orchestrator

# Check agent status
maf status

Run Sample Task

# Create a simple test task
maf trigger "Create a hello world function"

# Monitor progress
maf status --detailed

Troubleshooting

Common Issues

Import Errors

# Error: ModuleNotFoundError: No module named 'multi_agent_framework'
# Solution: Ensure you've activated your virtual environment
source venv/bin/activate  # Linux/macOS
venv\Scripts\activate     # Windows

API Key Issues

# Error: No API keys configured
# Solution: Check .env file exists and contains valid keys
cat .env  # Should show your API keys

# Verify keys are loaded
python -c "import os; print('GEMINI_API_KEY' in os.environ)"

Permission Errors

# Error: Permission denied when creating directories
# Solution: Ensure you have write permissions
chmod +w .  # Make current directory writable

Installation Validation Script

Create a test script to validate installation:

# test_installation.py
import sys
try:
    import multi_agent_framework
    print("✓ MAF imported successfully")
    print(f"✓ Version: {multi_agent_framework.__version__}")
    
    from multi_agent_framework.cli import main
    print("✓ CLI module loaded")
    
    import os
    api_keys = ['GEMINI_API_KEY', 'ANTHROPIC_API_KEY', 'OPENAI_API_KEY']
    configured = [k for k in api_keys if os.getenv(k)]
    if configured:
        print(f"✓ API keys configured: {', '.join(configured)}")
    else:
        print("✗ No API keys configured")
    
except Exception as e:
    print(f"✗ Error: {e}")
    sys.exit(1)

Run with:

python test_installation.py

Getting Help

If you encounter issues:

  1. Check the Troubleshooting Guide
  2. Search existing issues
  3. Ask in Discussions
  4. Create a new issue with:
    • Error messages
    • System information
    • Steps to reproduce

Next Steps

Clone this wiki locally