Configuration

Configuration#

MassGen is configured using environment variables for API keys and YAML files for agent definitions and orchestrator settings. This guide shows you how to set up your configuration.

Tip

MassGen offers multiple usage modes: CLI with YAML configuration, Python API (massgen.run()), and LiteLLM integration for OpenAI-compatible interfaces. This guide focuses on CLI configuration. For Python integration, see Programmatic API Guide.

Configuration Methods#

MassGen offers three ways to configure your agents:

Interactive Setup Wizard (Recommended for beginners)
YAML Configuration Files (For advanced customization)
CLI Flags (For quick one-off queries)

Interactive Setup Wizard#

The easiest way to configure MassGen is through the interactive wizard:

# First run automatically triggers the wizard
uv run massgen

# Or manually launch it
uv run massgen --init

The Config Builder Interface:

╭──────────────────────────────────────────────────────────────────────────────╮
│                                                                              │
│       ███╗   ███╗ █████╗ ███████╗███████╗ ██████╗ ███████╗███╗   ██╗         │
│       ████╗ ████║██╔══██╗██╔════╝██╔════╝██╔════╝ ██╔════╝████╗  ██║         │
│       ██╔████╔██║███████║███████╗███████╗██║  ███╗█████╗  ██╔██╗ ██║         │
│       ██║╚██╔╝██║██╔══██║╚════██║╚════██║██║   ██║██╔══╝  ██║╚██╗██║         │
│       ██║ ╚═╝ ██║██║  ██║███████║███████║╚██████╔╝███████╗██║ ╚████║         │
│       ╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝╚══════╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝         │
│                                                                              │
│            🤖 🤖 🤖  →  💬 collaborate  →  🎯 winner  →  📢 final            │
│                                                                              │
│  Interactive Configuration Builder                                           │
│  Create custom multi-agent configurations in minutes!                        │
╰──────────────────────────────────────────────────────────────────────────────╯

The wizard guides you through 4 simple steps:

Select Your Use Case: Choose from pre-built templates (Research, Coding, Q&A, etc.)
Configure Agents: Select providers and models (wizard detects available API keys)
Configure Tools: Enable web search, code execution, file operations, etc.
Review & Save: Save to ~/.config/massgen/config.yaml (Windows: %USERPROFILE%\.config\massgen\config.yaml)

After completing the wizard, your configuration is ready to use:

uv run massgen "Your question"  # Uses default config automatically

Configuration Directory Structure#

MassGen uses two directories for configuration:

User Configuration (~/.config/massgen/):

~/.config/massgen/                        # Windows: %USERPROFILE%\.config\massgen\
├── config.yaml              # Default configuration (from wizard)
├── agents/                  # Your custom named configurations
│   ├── research-team.yaml
│   └── coding-agents.yaml
└── .env                     # API keys (optional)

Project Workspace (.massgen/ in your project):

MassGen also creates a .massgen/ directory in your project for sessions, workspaces, and snapshots. See Core Concepts for details.

Creating Named Configurations:

# Run the wizard in named config mode
uv run massgen --init

# Choose to save to ~/.config/massgen/agents/ (Windows: %USERPROFILE%\.config\massgen\agents\)
# Then use it:
uv run massgen --config research-team "Your question"

Quickstart Output Filenames#

Quickstart supports explicit config filenames without manually editing paths:

# Uses quickstart defaults and saves to .massgen/team-config.yaml
uv run massgen --quickstart --config team-config

# Extension is optional; .yaml is added when omitted
uv run massgen --quickstart --config team-config.yaml

In the TUI/Web quickstart wizard, use the “Save Location” step to:

choose project (.massgen/) or global (~/.config/massgen/) save location
enter a custom filename

Environment Variables#

API keys are configured through environment variables or a .env file. After pip install, the setup wizard can create ~/.config/massgen/.env (Windows: %USERPROFILE%\.config\massgen\.env) for you.

OpenRouter (Recommended)#

Use one API key to access all models - OpenRouter provides a unified API for OpenAI, Anthropic, Google, xAI, and 200+ other models:

# Single key for all models
export OPENROUTER_API_KEY=sk-or-v1-...

Then use OpenRouter models in your multi-agent configurations

Get your key: OpenRouter

Individual Provider Keys#

Alternatively, use provider-specific keys:

# OpenAI (for GPT-5, GPT-4, etc.)
OPENAI_API_KEY=sk-...

# Anthropic Claude (for claude backend)
ANTHROPIC_API_KEY=sk-ant-...

# Claude Code (optional - for claude_code backend only)
# If set, claude_code uses this instead of ANTHROPIC_API_KEY
# CLAUDE_CODE_API_KEY=sk-ant-...

# Google Gemini
GOOGLE_API_KEY=...

# xAI Grok
XAI_API_KEY=...

Note

Separate API keys for Claude Code: The claude_code backend checks CLAUDE_CODE_API_KEY first, then falls back to ANTHROPIC_API_KEY. This allows you to use a Claude subscription (no API key) or a separate API key for Claude Code agents while using a different API key for standard Claude backend agents.

Getting API Keys:

OpenRouter (recommended - single key for all models)
OpenAI
Anthropic Claude
Google Gemini
xAI Grok

YAML Configuration Files#

MassGen uses YAML files to define agents, their backends, and orchestrator settings. Configuration files are stored in @examples/ and can be referenced using the --config flag.

Basic Configuration Structure#

A minimal MassGen configuration has these top-level keys:

agents:              # List of agents (required)
  - id: "agent_id"   # Agent definitions
    backend: ...     # Backend configuration
    system_message: ...  # Optional system prompt

orchestrator:        # Orchestrator settings (optional, required for file ops)
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"
  context_paths: ...

ui:                  # UI settings (optional)
  display_type: "rich_terminal"
  logging_enabled: true

Single Agent Configuration#

For a single agent, use the agents field (plural) with one entry:

# @examples/basic/single/single_gpt5nano
agents:                # Note: plural 'agents' even for single agent
  - id: "gpt-5-nano"
    backend:
      type: "openai"
      model: "gpt-5-nano"
      enable_web_search: true
      enable_code_interpreter: true

ui:
  display_type: "rich_terminal"
  logging_enabled: true

Warning

Common Mistake: When converting a single-agent config to multi-agent, remember to keep agents: (plural).

While agent: (singular) is supported for single-agent configs, always use agents: (plural) for consistency - this prevents errors when adding more agents later.

Run this configuration:

uv run massgen \
  --config @examples/basic/single/single_gpt5nano \
  "What is machine learning?"

Multi-Agent Configuration#

For multiple agents, add more entries to the agents list:

# @examples/basic/multi/three_agents_default
agents:
  - id: "gemini2.5flash"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"
      enable_web_search: true

  - id: "gpt5nano"
    backend:
      type: "openai"
      model: "gpt-5-nano"
      enable_web_search: true
      enable_code_interpreter: true

  - id: "grok3mini"
    backend:
      type: "grok"
      model: "grok-3-mini"
      enable_web_search: true

ui:
  display_type: "rich_terminal"
  logging_enabled: true

Run this configuration:

uv run massgen \
  --config @examples/basic/multi/three_agents_default \
  "Analyze the pros and cons of renewable energy"

Backend Configuration#

Each agent requires a backend configuration that specifies the model provider and settings.

Important

Choosing the right backend? Different backends support different features (web search, code execution, file operations, etc.). Check the Backend Capabilities Matrix in Backend Configuration to see which features are available for each backend type.

Supported Providers#

MassGen supports many LLM providers. Use the slash format (provider/model) for the Python API and LiteLLM:

Provider Reference#
Provider	Backend Type	Example Models	Slash Format Example
OpenAI	`openai`	`gpt-5`, `gpt-5-nano`, `gpt-5.1`	`openai/gpt-5`
Anthropic	`claude`	`claude-sonnet-4-5-20250929`, `claude-opus-4-5-20251101`	`claude/claude-sonnet-4-5-20250929`
Google	`gemini`	`gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-3-pro-preview`	`gemini/gemini-2.5-flash`
xAI	`grok`	`grok-4`, `grok-4-1-fast-reasoning`, `grok-3-mini`	`grok/grok-4`
Groq	`groq`	`llama-3.3-70b-versatile`, `mixtral-8x7b-32768`	`groq/llama-3.3-70b-versatile`
Cerebras	`cerebras`	`llama-3.3-70b`, `llama-3.1-8b`	`cerebras/llama-3.3-70b`
Together	`together`	`meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo`	`together/meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo`
Fireworks	`fireworks`	`accounts/fireworks/models/llama-v3p3-70b-instruct`	`fireworks/accounts/fireworks/models/llama-v3p3-70b-instruct`
OpenRouter	`openrouter`	200+ models (e.g., `x-ai/grok-4.1-mini`)	`openrouter/x-ai/grok-4.1-mini`
Qwen	`qwen`	`qwen-max`, `qwen-plus`, `qwen-turbo`	`qwen/qwen-max`
Moonshot	`moonshot`	`moonshot-v1-128k`, `moonshot-v1-32k`	`moonshot/moonshot-v1-128k`
Nebius	`nebius`	`Qwen/Qwen3-4B-fast`	`nebius/Qwen/Qwen3-4B-fast`
Claude Code	`claude_code`	`claude-sonnet-4-5-20250929`	(YAML only, no API key — subscription or CLI auth)
Codex	`codex`	`gpt-5.4`, `gpt-5.3-codex`	(YAML only, no API key — `codex login` OAuth)
Gemini CLI	`gemini_cli`	`gemini-2.5-pro`, `gemini-2.5-flash`	(YAML only, no API key — `gemini` CLI login)
GitHub Copilot	`copilot`	`gpt-5-mini`, `claude-sonnet-4`, `gemini-2.5-pro`	(YAML only, no API key — `copilot /login`)
Azure OpenAI	`azure_openai`	`gpt-4o` (deployment name)	(YAML only)

Tip

Nested slashes are supported! For providers like OpenRouter, Together, and Fireworks where model names contain slashes, the format still works:

openrouter/x-ai/grok-4.1-mini → provider=openrouter, model=x-ai/grok-4.1-mini
together/meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo → provider=together, model=meta-llama/Meta-Llama-3.1-405B-Instruct-Turbo

Using slash format in Python:

import massgen

# Build config with slash format
config = massgen.build_config(models=[
    "openai/gpt-5",
    "groq/llama-3.3-70b-versatile",
    "openrouter/x-ai/grok-4.1-mini"
])

# Or with LiteLLM (using OpenRouter)
from dotenv import load_dotenv
load_dotenv()  # Load OPENROUTER_API_KEY from .env

import litellm
from massgen import register_with_litellm

register_with_litellm()
response = litellm.completion(
    model="massgen/build",
    messages=[{"role": "user", "content": "Your question"}],
    optional_params={"models": ["openrouter/openai/gpt-5", "openrouter/anthropic/claude-sonnet-4.5"]}
)
print(response.choices[0].message.content)

Backend Types (YAML)#

For YAML configuration files, use the type field:

Agent/CLI backends (no API key required — use CLI auth):

claude_code - Claude Code SDK with dev tools (subscription or CLAUDE_CODE_API_KEY)
codex - OpenAI Codex CLI (codex login OAuth or OPENAI_API_KEY)
gemini_cli - Google Gemini CLI agent (gemini CLI login, no API key needed)
copilot - GitHub Copilot CLI (copilot /login, no API key needed)

API backends:

openai - OpenAI models (GPT-5, GPT-4, etc.)
claude - Anthropic Claude models
gemini - Google Gemini models
grok - xAI Grok models
groq - Groq inference (ultra-fast)
cerebras - Cerebras AI
together - Together AI
fireworks - Fireworks AI
openrouter - OpenRouter (200+ models)
qwen - Alibaba Qwen models
moonshot - Kimi/Moonshot AI
nebius - Nebius AI Studio
azure_openai - Azure OpenAI deployment
zai - ZhipuAI GLM models
ag2 - AG2 framework integration
lmstudio - Local models via LM Studio
chatcompletion - Generic OpenAI-compatible API

Basic Backend Structure#

backend:
  type: "openai"           # Backend type (required)
  model: "gpt-5-nano"      # Model name (required)
  api_key: "..."           # Optional - uses env var by default
  temperature: 0.7         # Optional - model parameters
  max_tokens: 4096         # Optional - response length

Backend-Specific Features#

Different backends support different built-in tools:

# OpenAI with tools
backend:
  type: "openai"
  model: "gpt-5-nano"
  enable_web_search: true
  enable_code_interpreter: true

# Gemini with tools
backend:
  type: "gemini"
  model: "gemini-2.5-flash"
  enable_web_search: true
  enable_code_execution: true

# Claude Code with workspace
backend:
  type: "claude_code"
  model: "claude-sonnet-4"
  cwd: "workspace"          # Working directory for file operations

Note

Always use cwd: "workspace" rather than numbered names like workspace1. MassGen automatically adds a unique suffix per agent at runtime to prevent identity leakage during voting.

See YAML Configuration Reference for complete backend options.

System Messages#

Customize agent behavior with system messages:

agents:
  - id: "research_agent"
    backend:
      type: "gemini"
      model: "gemini-2.5-flash"
    system_message: |
      You are a research specialist. When answering questions:
      1. Always search for current information
      2. Cite your sources
      3. Provide comprehensive analysis

  - id: "code_agent"
    backend:
      type: "openai"
      model: "gpt-5-nano"
    system_message: |
      You are a coding expert. When solving problems:
      1. Write clean, well-documented code
      2. Use code execution to test solutions
      3. Explain your approach clearly

Orchestrator Configuration#

Control workspace sharing and project integration:

orchestrator:
  snapshot_storage: "snapshots"              # Workspace snapshots for sharing
  agent_temporary_workspace: "temp_workspaces"  # Temporary workspaces
  context_paths:                             # Project integration
    - path: "/absolute/path/to/project"
      permission: "read"                     # read or write

Decomposition Mode Configuration#

Use decomposition mode when agents own subtasks and one presenter synthesizes:

agents:
  - id: "frontend"
    subtask: "Implement UI and client behavior"
    backend:
      type: "openai"
      model: "gpt-5-nano"

  - id: "backend"
    subtask: "Implement API and persistence"
    backend:
      type: "openai"
      model: "gpt-5-nano"

  - id: "integrator"
    subtask: "Integrate and present final output"
    backend:
      type: "openai"
      model: "gpt-5-nano"

orchestrator:
  coordination_mode: "decomposition"
  presenter_agent: "integrator"
  # Recommended decomposition defaults:
  max_new_answers_per_agent: 2  # Recommended range: 2-3
  max_new_answers_global: 9     # Team-wide cumulative cap across all agents
  answer_novelty_requirement: "balanced"

Sensible defaults guidance:

By default, use max_new_answers_per_agent: 2-3 in decomposition mode.
Usually this is lower than fully parallel voting mode settings.
Add max_new_answers_global for deterministic total coordination budget.
Keep other answer-control parameters at defaults unless you need stricter behavior.
Keep fairness defaults enabled (fairness_enabled: true, fairness_lead_cap_answers: 2, max_midstream_injections_per_round: 2) to prevent fast agents from repeatedly lapping slower peers and causing restart churn.

Quickstart note:

The Quickstart flows (uv run massgen --quickstart and the Web/TUI quickstart wizard) expose decomposition mode, presenter selection, and these defaults directly.
For GPT-5x models, Quickstart also exposes reasoning.effort selection. OpenAI GPT-5 models support low|medium|high and Codex GPT-5 models include xhigh.

Example:

agents:
  - id: "agent_a"
    backend:
      type: "codex"
      model: "gpt-5.4"
      reasoning:
        effort: "xhigh"
        summary: "auto"

Advanced Configuration#

MCP Integration#

Add MCP (Model Context Protocol) servers for external tools:

agents:
  - id: "agent_with_mcp"
    backend:
      type: "openai"
      model: "gpt-5-nano"
      mcp_servers:
        - name: "weather"
          type: "stdio"
          command: "npx"
          args: ["-y", "@fak111/weather-mcp"]

See MCP Integration for details.

File Operations#

Enable file system access for agents:

agents:
  - id: "file_agent"
    backend:
      type: "claude_code"
      model: "claude-sonnet-4"
      cwd: "workspace"       # Agent's working directory

orchestrator:
  snapshot_storage: "snapshots"
  agent_temporary_workspace: "temp_workspaces"

See File Operations & Workspace Management for details.

Project Integration#

Share directories with agents (read or write access):

agents:
  - id: "project_agent"
    backend:
      type: "claude_code"
      cwd: "workspace"

orchestrator:
  context_paths:
    - path: "/absolute/path/to/project/src"
      permission: "read"      # Agents can analyze code
    - path: "/absolute/path/to/project/docs"
      permission: "write"     # Agents can update docs

See Project Integration & Context Paths for details.

Protected Paths#

Make specific files read-only within writable context paths:

orchestrator:
  context_paths:
    - path: "/project"
      permission: "write"
      protected_paths:
        - "config.json"        # Read-only
        - "template.html"      # Read-only
        # Other files remain writable

Use Case: Allow agents to modify most files while protecting critical configurations or templates.

See Protected Paths for complete documentation.

Planning Mode#

Prevent irreversible actions during multi-agent coordination:

orchestrator:
  coordination:
    enable_planning_mode: true
    planning_mode_instruction: |
      PLANNING MODE: Describe your intended actions without executing.
      Save execution for the final presentation phase.

Use Case: File operations, API calls, or any task with irreversible consequences.

See Planning Mode for complete documentation.

Subagents#

Enable agents to spawn parallel child processes for independent tasks:

orchestrator:
  coordination:
    enable_subagents: true
    subagent_default_timeout: 300  # 5 minutes per subagent
    subagent_max_concurrent: 3     # Max parallel subagents

Example usage:

uv run massgen \
  --config @massgen/configs/features/subagent_demo.yaml \
  "Build a website with frontend, backend, and documentation"

The agent can spawn subagents to work on each component simultaneously. Subagents:

Run in isolated workspaces
Inherit parent agent configurations by default
Execute concurrently for parallel task completion
Return structured results with workspace paths

Use Case: Complex tasks with independent, parallelizable components (e.g., multi-part research, website building, documentation generation).

See Subagents for complete documentation.

Timeout Configuration#

Control maximum coordination time:

timeout_settings:
  orchestrator_timeout_seconds: 1800  # 30 minutes (default)

CLI Override:

uv run massgen --orchestrator-timeout 600 --config config.yaml

See Timeout Configuration for complete timeout documentation.

For the complete list of CLI parameters, see CLI Reference

Configuration Best Practices#

Start Simple: Use single agent configs for testing, then scale to multi-agent
Use Environment Variables: Never commit API keys to version control
Organize Configs: Group related configurations in directories
Comment Your YAML: Add comments to explain agent roles and settings
Test Incrementally: Verify each agent works before combining them
Version Your Configs: Track configuration changes in version control

Example Configuration Templates#

All configuration examples are in @examples/:

@examples/basic/single/single_gpt5nano - Single agent configuration
@examples/basic/multi/three_agents_default - Multi-agent collaboration
@examples/basic/multi/decomposition_quickstart - Decomposition mode with recommended defaults
@examples/basic/multi/decomposition_example - Decomposition mode with richer role setup
@examples/tools/mcp/* - MCP integration examples
@examples/tools/filesystem/* - File operation examples
@examples/ag2/* - AG2 framework integration

See the Configuration Guide for the complete catalog.

Next Steps#

Excellent! You understand configuration basics. Here’s your path forward:

✅ You are here: You know how to configure agents in YAML

⬜ Put it to use: Basic Examples - Copy ready-made configurations

⬜ Go deeper: Core Concepts - Understand how multi-agent coordination works

⬜ Add capabilities: MCP Integration - Integrate external tools

Need a reference? The complete configuration schema is at YAML Configuration Reference

Troubleshooting#

Configuration not found:

Ensure the path is correct relative to the MassGen directory:

# Correct - relative to MassGen root
uv run massgen --config @examples/basic/multi/three_agents_default

# Incorrect - missing massgen/ prefix
uv run massgen --config configs/basic/multi/three_agents_default.yaml

API key not found:

Check that your .env file exists and contains the correct key:

# Verify .env file exists
ls -la .env

# Check for the required key
grep "OPENAI_API_KEY" .env

YAML syntax error:

Validate your YAML syntax:

python -c "import yaml; yaml.safe_load(open('your-config.yaml'))"