Python API & LiteLLM

MassGen provides two ways to integrate into your Python applications:

1. LiteLLM Integration (Recommended) - OpenAI-compatible interface, works with 100+ providers

2. Direct Python API - Async-first API with massgen.run() and massgen.build_config()

Note

For Contributors: Looking for internal API documentation? See Developer API Documentation for developer API reference of classes and modules.

LiteLLM Integration

The easiest way to use MassGen programmatically. Works with existing LiteLLM-based code.

Quick Start

from dotenv import load_dotenv
load_dotenv()  # Load API keys from .env

import litellm
from massgen import register_with_litellm

# Register MassGen as a provider (call once at startup)
register_with_litellm()

# Multi-agent with different models
response = litellm.completion(
    model="massgen/build",
    messages=[{"role": "user", "content": "What is machine learning?"}],
    optional_params={
        "models": ["openai/gpt-5", "anthropic/claude-sonnet-4-5-20250929"],
    }
)
print(response.choices[0].message.content)

Model String Format

• massgen/build - Build config dynamically from optional_params (most flexible)

• massgen/<example-name> - Use built-in example config

• massgen/model:<model-name> - Quick single-agent mode

• massgen/path:<config-path> - Explicit config file path

Optional Parameters

Pass MassGen-specific options via optional_params:

Parameter	Type	Description
models	list[str]	List of models for multi-agent (e.g., ["gpt-5", "claude-sonnet-4-5-20250929"])
model	str	Single model name for all agents
num_agents	int	Number of agents when using single model
enable_filesystem	bool	Enable filesystem/MCP tools (default: True)
context_paths	list	Paths with permissions for file operations
use_docker	bool	Enable Docker execution mode (default: False)
enable_logging	bool	Enable logging and return log directory
output_file	str	Write final answer to this file path

Examples

# Multi-agent with filesystem access
response = litellm.completion(
    model="massgen/build",
    messages=[{"role": "user", "content": "Read the config and summarize"}],
    optional_params={
        "model": "gpt-5",
        "context_paths": [
            {"path": "/path/to/project", "permission": "read"},
            {"path": "/path/to/output", "permission": "write"},
        ],
    }
)

# Lightweight mode (no filesystem, faster for simple queries)
response = litellm.completion(
    model="massgen/build",
    messages=[{"role": "user", "content": "What is 2+2?"}],
    optional_params={
        "model": "gpt-5-nano",
        "enable_filesystem": False,
    }
)

# Access coordination metadata
metadata = response._hidden_params
print(f"Winner: {metadata.get('massgen_selected_agent')}")
print(f"Votes: {metadata.get('massgen_vote_results', {}).get('vote_counts')}")

For complete LiteLLM examples, see Programmatic API Guide.

Direct Python API

For async workflows or more control, use massgen.run() directly.

import asyncio
import massgen

async def main():
    # Single agent with filesystem support (default)
    result = await massgen.run(
        query="What is machine learning?",
        model="gpt-5"
    )
    print(result['final_answer'])

    # Multi-agent mode
    result = await massgen.run(
        query="Compare approaches",
        models=["gpt-5", "claude-sonnet-4-5-20250929"]
    )
    print(result['final_answer'])

    # Lightweight mode (no filesystem)
    result = await massgen.run(
        query="What is 2+2?",
        model="gpt-5-nano",
        enable_filesystem=False
    )
    print(result['final_answer'])

asyncio.run(main())

API Reference

massgen.run()

async def run(
    query: str,
    config: str = None,
    model: str = None,
    models: list = None,
    num_agents: int = None,
    use_docker: bool = False,
    enable_filesystem: bool = True,
    enable_logging: bool = False,
    output_file: str = None,
    **kwargs
) -> dict

Parameters:

• query (str): The question or task for the agent(s)

• config (str, optional): Config file path or @examples/NAME

• model (str, optional): Model name for agents

• models (list, optional): List of models for multi-agent mode

• num_agents (int, optional): Number of agents when using single model

• use_docker (bool): Enable Docker execution (default: False)

• enable_filesystem (bool): Enable filesystem/MCP tools (default: True)

• enable_logging (bool): Enable logging (default: False)

• output_file (str, optional): Write final answer to file

• context_paths (list, optional): Paths with permissions for file operations

Returns:

{
    'final_answer': str,        # The generated answer
    'config_used': str,         # Config path or description
    'session_id': str,          # Session ID
    'selected_agent': str,      # Winner (multi-agent)
    'vote_results': dict,       # Voting details
    'answers': list,            # All agent answers
}

Usage Patterns

Single Agent Mode

For simple queries with a single agent:

import asyncio
import massgen

async def single_agent_query():
    result = await massgen.run(
        query="What are the benefits of renewable energy?",
        model="gpt-5-mini"
    )
    return result['final_answer']

answer = asyncio.run(single_agent_query())
print(answer)

Supported Models:

• OpenAI: gpt-5, gpt-5-mini, gpt-5-nano, gpt-4o, o1

• Anthropic: claude-sonnet-4, claude-opus-4

• Google: gemini-2.5-flash, gemini-2.5-pro, gemini-2.0-flash

• xAI: grok-4, grok-4-fast-reasoning

See Supported Models & Backends for the complete list.

Multi-Agent with Configuration

For complex queries requiring multiple agents:

import asyncio
import massgen

async def multi_agent_research():
    result = await massgen.run(
        query="Compare renewable energy sources with analysis",
        config="@examples/research_team"
    )
    return result

result = asyncio.run(multi_agent_research())
print(result['final_answer'])
print(f"Config: {result['config_used']}")

Built-in Example Configurations:

Use the @examples/ prefix to access built-in configurations:

• @examples/basic/single/single_gpt5nano - Single agent configuration

• @examples/basic/multi/three_agents_default - Three-agent basic setup

• @examples/research_team - Research-focused agents with web search

• @examples/coding_team - Code generation with multiple agents

List all available examples:

massgen --list-examples

Default Configuration

Use your default configuration (from the setup wizard):

import asyncio
import massgen

async def use_default_config():
    # No config or model specified - uses ~/.config/massgen/config.yaml
    result = await massgen.run(
        query="Analyze the impact of AI on healthcare"
    )
    return result['final_answer']

answer = asyncio.run(use_default_config())
print(answer)

Custom Configuration Files

Use your own YAML configuration files:

import asyncio
import massgen

async def custom_config():
    result = await massgen.run(
        query="Your question",
        config="./my-agents.yaml"  # Relative path
    )
    return result

# Or absolute path
async def custom_config_abs():
    result = await massgen.run(
        query="Your question",
        config="/path/to/my-agents.yaml"
    )
    return result

Named Configurations

Use named configurations from ~/.config/massgen/agents/:

import asyncio
import massgen

async def named_config():
    # Looks for ~/.config/massgen/agents/research-team.yaml
    result = await massgen.run(
        query="Research question",
        config="research-team"  # No .yaml extension needed
    )
    return result

answer = asyncio.run(named_config())
print(answer)

Advanced Usage

Async/Await Patterns

Since MassGen is async-native, you can integrate it into async applications:

import asyncio
import massgen

async def process_multiple_queries():
    # Run multiple queries concurrently
    queries = [
        "What is AI?",
        "Explain machine learning",
        "Define neural networks"
    ]

    tasks = [
        massgen.run(query=q, model="gpt-5-mini")
        for q in queries
    ]

    results = await asyncio.gather(*tasks)

    for query, result in zip(queries, results):
        print(f"Q: {query}")
        print(f"A: {result['final_answer']}\n")

asyncio.run(process_multiple_queries())

Integration with FastAPI

MassGen works seamlessly with FastAPI:

from fastapi import FastAPI
import massgen

app = FastAPI()

@app.post("/query")
async def handle_query(question: str, model: str = "gpt-5-mini"):
    result = await massgen.run(
        query=question,
        model=model
    )
    return {
        "question": question,
        "answer": result['final_answer'],
        "config": result['config_used']
    }

# Run with: uvicorn myapp:app

Integration with Jupyter Notebooks

MassGen works great in Jupyter notebooks:

# In a Jupyter cell
import massgen

# Jupyter handles the event loop for you
result = await massgen.run(
    query="Explain photosynthesis",
    model="gemini-2.5-flash"
)

print(result['final_answer'])

# Or create an explicit async cell
async def research_query():
    return await massgen.run(
        query="Compare programming paradigms",
        config="@examples/research_team"
    )

result = await research_query()
print(result['final_answer'])

Error Handling

Handle errors gracefully:

import asyncio
import massgen

async def safe_query():
    try:
        result = await massgen.run(
            query="Your question",
            model="gpt-5-mini"
        )
        return result['final_answer']

    except ValueError as e:
        print(f"Configuration error: {e}")
        # E.g., config not found, no API key

    except Exception as e:
        print(f"Unexpected error: {e}")
        return None

answer = asyncio.run(safe_query())

Common Errors

No Configuration Found

ValueError: No config specified and no default config found.
Run `massgen --init` to create a default configuration.

Solution: Run the setup wizard to create a default config:

massgen --init

Or specify a config explicitly:

result = await massgen.run(query="...", config="@examples/basic/multi/three_agents_default")

API Key Not Found

If you see API key errors, ensure your keys are configured:

1. Set environment variables:

   export OPENAI_API_KEY="sk-..."
   export ANTHROPIC_API_KEY="sk-ant-..."
   

2. Or create ~/.config/massgen/.env:

   OPENAI_API_KEY=sk-...
   ANTHROPIC_API_KEY=sk-ant-...
   

Config Not Found

ConfigurationError: Configuration file not found: my-config

Solution: Check the config path exists, or use @examples/ for built-in configs.

Best Practices

1. Use Async/Await Properly

   # Good
   result = await massgen.run(query="...")
   
   # Bad (won't work)
   result = massgen.run(query="...")  # Missing await
   

2. Handle Errors

   Always wrap API calls in try/except blocks for production code.

3. Reuse Configurations

   Create named configurations for common use cases:

   # Save to ~/.config/massgen/agents/research.yaml
   # Then reuse:
   result = await massgen.run(query="...", config="research")
   

4. Use Single-Agent Mode for Simple Queries

   For straightforward questions, single-agent mode is faster:

   result = await massgen.run(
       query="Quick question",
       model="gpt-5-mini"  # Fast and cheap
   )
   

5. Use Multi-Agent Mode for Complex Analysis

   For research, comparison, or analysis:

   result = await massgen.run(
       query="Compare X and Y",
       config="@examples/research_team"
   )
   

See Also

• Installation - Installation and setup

• Configuration - Configuration file format

• CLI Reference - Command-line interface reference

• Supported Models & Backends - Supported models and backends

• YAML Configuration Reference - YAML configuration schema