Configuration Examples

This reference provides a comprehensive catalog of MassGen configuration examples organized by use case, backend provider, and feature set.

Directory Structure

All configuration files are located in @examples/:

@examples/
├── basic/                 # Simple configs to get started
│   ├── single/           # Single agent examples
│   └── multi/            # Multi-agent examples
├── tools/                 # Tool-enabled configurations
│   ├── mcp/              # MCP server integrations
│   ├── planning/         # Planning mode examples
│   ├── web-search/       # Web search enabled configs
│   ├── code-execution/   # Code interpreter/execution
│   └── filesystem/       # File operations & workspace
├── providers/             # Provider-specific examples
│   ├── openai/           # GPT-5 series configs
│   ├── claude/           # Claude API configs
│   ├── gemini/           # Gemini configs
│   ├── azure/            # Azure OpenAI
│   ├── local/            # LMStudio, local models
│   └── others/           # Cerebras, Grok, Qwen, ZAI
├── teams/                # Pre-configured specialized teams
│   ├── creative/         # Creative writing teams
│   ├── research/         # Research & analysis
│   └── development/      # Coding teams
└── ag2/                  # AG2 framework integration

Quick Start Examples

Recommended Showcase Example

Best starting point for multi-agent collaboration:

# Three powerful agents (Gemini, GPT-5, Grok) with enhanced workspace tools
massgen \
  --config @examples/basic/multi/three_agents_default.yaml \
  "Your complex task"

This configuration combines:

• Gemini 2.5 Flash - Fast, versatile with web search

• GPT-5 Nano - Advanced reasoning with code interpreter

• Grok-3 Mini - Efficient with real-time web search

Quick Setup Without Config Files

Single agent with model name only:

# Quick test with any supported model - no configuration needed
massgen --model claude-3-5-sonnet-latest "What is machine learning?"
massgen --model gemini-2.5-flash "Explain quantum computing"
massgen --model gpt-5-nano "Summarize the latest AI developments"

Interactive Mode:

# Start interactive chat (no initial question)
massgen \
  --config @examples/basic/multi/three_agents_default.yaml

# Debug mode for troubleshooting
massgen \
  --config @examples/basic/multi/three_agents_default.yaml \
  --debug "Your question"

Tool-Enabled Configurations

MCP (Model Context Protocol) Servers

MCP enables agents to use external tools and services:

# Weather queries
massgen \
  --config @examples/tools/mcp/gemini_mcp_example.yaml \
  "What's the weather in Tokyo?"

# Discord integration
massgen \
  --config @examples/tools/mcp/claude_code_discord_mcp_example.yaml \
  "Extract latest messages"

See MCP Integration for complete MCP documentation.

Planning Mode

Prevent irreversible actions during coordination:

# Five agents with planning mode enabled
massgen \
  --config @examples/tools/planning/five_agents_filesystem_mcp_planning_mode.yaml \
  "Create a comprehensive project structure"

See Planning Mode for complete planning mode documentation.

Web Search

For agents with web search capabilities:

massgen \
  --config @examples/tools/web-search/claude_streamable_http_test.yaml \
  "Search for latest news"

Code Execution

For code interpretation and execution:

massgen \
  --config @examples/tools/code-execution/multi_agent_playwright_automation.yaml \
  "Browse three issues in https://github.com/Leezekun/MassGen and suggest improvements"

Filesystem Operations

For file manipulation, workspace management, and context path integration:

# Single agent with enhanced file operations
massgen \
  --config @examples/tools/filesystem/claude_code_single.yaml \
  "Analyze this codebase"

# Multi-agent workspace collaboration
massgen \
  --config @examples/tools/filesystem/claude_code_context_sharing.yaml \
  "Create shared workspace files"

See File Operations & Workspace Management for complete filesystem documentation.

Provider-Specific Examples

Each provider has unique features and capabilities:

OpenAI (GPT-5 Series)

massgen \
  --config @examples/providers/openai/gpt5.yaml \
  "Complex reasoning task"

Claude

massgen \
  --config @examples/tools/mcp/claude_mcp_example.yaml \
  "Creative writing task"

Gemini

massgen \
  --config @examples/tools/mcp/gemini_mcp_example.yaml \
  "Research task"

Local Models

# Requires LM Studio running locally
massgen \
  --config @examples/providers/local/lmstudio.yaml \
  "Run with local model"

See Supported Models & Backends for choosing backends.

Pre-Configured Teams

Teams are specialized multi-agent setups for specific domains:

Creative Teams

massgen \
  --config @examples/teams/creative/creative_team.yaml \
  "Write a story"

Research Teams

massgen \
  --config @examples/teams/research/research_team.yaml \
  "Analyze market trends"

Development Teams

massgen \
  --config @examples/providers/others/zai_coding_team.yaml \
  "Build a web app"

Configuration File Format

Single Agent

agents:
  - id: "agent_name"
    backend:
      type: "provider_type"
      model: "model_name"
      # Additional backend settings
    system_message: "Agent instructions"

ui:
  display_type: "rich_terminal"
  logging_enabled: true

Multi-Agent

agents:
  - id: "agent1"
    backend:
      type: "provider1"
      model: "model1"
    system_message: "Agent 1 role"

  - id: "agent2"
    backend:
      type: "provider2"
      model: "model2"
    system_message: "Agent 2 role"

ui:
  display_type: "rich_terminal"
  logging_enabled: true

See YAML Configuration Reference for complete configuration reference.

MCP Server Configuration

backend:
  type: "provider"
  model: "model_name"
  mcp_servers:
    - name: "server_name"
      type: "stdio"
      command: "command"
      args: ["arg1", "arg2"]
      env:
        KEY: "${ENV_VAR}"

See MCP Integration for complete MCP configuration.

Finding the Right Configuration

1. New Users: Start with basic/single/ or basic/multi/

2. Need Tools: Check tools/ subdirectories for specific capabilities

3. Specific Provider: Look in providers/ for your provider

4. Complex Tasks: Use pre-configured teams/

5. Planning Mode: Use tools/planning/ for tasks with irreversible actions

Release History & Examples

v0.0.29 - Latest

New Features: Planning Mode, File Operation Safety, Enhanced MCP Tool Filtering

Key Configurations:

• @examples/tools/planning/five_agents_discord_mcp_planning_mode.yaml - Five agents with Discord MCP in planning mode

• @examples/tools/planning/five_agents_filesystem_mcp_planning_mode.yaml - Five agents with filesystem MCP in planning mode

• @examples/tools/planning/five_agents_notion_mcp_planning_mode.yaml - Five agents with Notion MCP in planning mode

• @examples/tools/mcp/five_agents_weather_mcp_test.yaml - Five agents testing weather MCP tools

Try it:

# Planning mode with filesystem operations
massgen \
  --config @examples/tools/planning/five_agents_filesystem_mcp_planning_mode.yaml \
  "Create a comprehensive project structure with documentation"

# Multi-agent weather MCP testing
massgen \
  --config @examples/tools/mcp/five_agents_weather_mcp_test.yaml \
  "Compare weather forecasts for New York, London, and Tokyo"

v0.0.28

New Features: General Framework Interoperability, External Agent Backend, Code Execution Support

Key Configurations:

• @examples/ag2/ag2_single_agent.yaml - Basic single AG2 agent setup

• @examples/ag2/ag2_coder.yaml - AG2 agent with code execution capabilities

• @examples/ag2/ag2_gemini.yaml - AG2-Gemini hybrid configuration

Try it:

# AG2 single agent with code execution
massgen \
  --config @examples/ag2/ag2_coder.yaml \
  "Create a factorial function and calculate the factorial of 8"

# Mixed team: AG2 agent + Gemini agent
massgen \
  --config @examples/ag2/ag2_gemini.yaml \
  "what is quantum computing?"

v0.0.27

New Features: Multimodal Support (Image Processing), File Upload and File Search

Key Configurations:

• @examples/basic/multi/gpt4o_image_generation.yaml - Multi-agent image generation

• @examples/basic/multi/gpt5nano_image_understanding.yaml - Multi-agent image understanding

• @examples/basic/single/single_gpt5nano_file_search.yaml - File search for document Q&A

Try it:

# Image generation
massgen \
  --config @examples/basic/single/single_gpt4o_image_generation.yaml \
  "Generate an image of a gray tabby cat hugging an otter"

# Image understanding
massgen \
  --config @examples/basic/multi/gpt5nano_image_understanding.yaml \
  "Please summarize the content in this image"

v0.0.26

New Features: File Deletion, Protected Paths, File-Based Context Paths

Key Configurations:

• @examples/tools/filesystem/gemini_gpt5nano_protected_paths.yaml - Protected paths configuration

• @examples/tools/filesystem/gemini_gpt5nano_file_context_path.yaml - File-based context paths

• @examples/tools/filesystem/grok4_gpt5_gemini_filesystem.yaml - Multi-agent filesystem collaboration

Try it:

# Protected paths - keep reference files safe
massgen \
  --config @examples/tools/filesystem/gemini_gpt5nano_protected_paths.yaml \
  "Review the HTML and CSS files, then improve the styling"

v0.0.25

New Features: Interactive Multi-Turn Mode Filesystem Support, SGLang Backend Integration

Key Configurations:

• @examples/tools/filesystem/multiturn/two_gemini_flash_filesystem_multiturn.yaml - Multi-turn with Gemini agents

• @examples/tools/filesystem/multiturn/grok4_gpt5_claude_code_filesystem_multiturn.yaml - Three-agent multi-turn

• @examples/basic/multi/two_qwen_vllm_sglang.yaml - Mixed vLLM and SGLang deployment

Example Multi-Turn Session:

# Turn 1 - Initial creation
massgen \
  --config @examples/tools/filesystem/multiturn/two_gemini_flash_filesystem_multiturn.yaml

Turn 1: Make a website about Bob Dylan
# Creates workspace and saves state to .massgen/sessions/

# Turn 2 - Enhancement based on Turn 1
Turn 2: Remove the image placeholder and improve the appearance
# Automatically loads Turn 1's workspace state

v0.0.24 and Earlier

See the GitHub repository for complete release history including:

• v0.0.24 - vLLM Backend Support

• v0.0.23 - Backend Architecture Refactoring

• v0.0.22 - Workspace Copy Tools via MCP

• v0.0.21 - Advanced Filesystem Permissions

• v0.0.20 - Claude MCP Support

• v0.0.17 - OpenAI MCP Integration

• v0.0.16 - Unified Filesystem Support

• v0.0.15 - Gemini MCP Integration

• v0.0.12-14 - Enhanced Logging

• v0.0.10 - Azure OpenAI Support

• v0.0.7 - Local Model Support

• v0.0.5 - Claude Code Integration

Environment Variables

Most configurations use environment variables for API keys. Set up your .env file based on .env.example:

Provider-specific keys:

• OPENAI_API_KEY - OpenAI models

• ANTHROPIC_API_KEY - Claude models

• GOOGLE_API_KEY - Gemini models

• XAI_API_KEY - Grok models

• AZURE_OPENAI_API_KEY - Azure OpenAI

MCP server keys:

• DISCORD_BOT_TOKEN - Discord MCP integration

• BRAVE_API_KEY - Brave Search MCP integration

See Configuration for complete environment setup.

Naming Convention

MassGen configuration files follow this pattern for clarity:

Format: {agents}_{features}_{description}.yaml

1. Agents (who’s participating):

• single-{provider} - Single agent (e.g., single-claude, single-gemini)

• {provider1}-{provider2} - Two agents (e.g., claude-gemini, gemini-gpt5)

• three-mixed - Three agents from different providers

• team-{type} - Specialized teams (e.g., team-creative, team-research)

2. Features (what tools/capabilities):

• basic - No special tools, just conversation

• mcp - MCP server integration

• mcp-{service} - Specific MCP service (e.g., mcp-discord, mcp-weather)

• websearch - Web search enabled

• codeexec - Code execution/interpreter

• filesystem - File operations and workspace management

3. Description (purpose/context - optional):

• showcase - Demonstration/getting started example

• test - Testing configuration

• research - Research and analysis tasks

• dev - Development and coding tasks

• collab - Collaboration example

Note: Existing configs maintain their current names for compatibility. New configs should follow this convention.

Related Documentation

• Configuration - Configuration guide with step-by-step setup

• YAML Configuration Reference - Complete YAML schema reference

• Supported Models & Backends - All supported models and backends

• CLI Reference - Command-line interface reference

• MCP Integration - MCP tool integration guide

• Planning Mode - Planning mode documentation

• Protected Paths - Protected paths feature