Core Concepts#
Understanding MassGen’s core concepts is essential for using the system effectively.
What is MassGen?#
MassGen is a multi-agent coordination system that assigns tasks to multiple AI agents who work in parallel, share observations, vote for solutions, and converge on the best answer through natural consensus.
Agents observe, critique, and build on each other’s work across cycles of refinement and restarts. When they believe they have a strong enough answer, they vote — and the best collectively validated answer wins.
Configuration-Driven Architecture#
MassGen uses YAML files to configure everything, not Python code.
agents:
- id: "researcher"
backend:
type: "gemini"
model: "gemini-2.5-flash"
system_message: "You are a researcher"
- id: "analyst"
backend:
type: "openai"
model: "gpt-5-nano"
system_message: "You are an analyst"
Run via command line:
massgen --config config.yaml "Your question"
This design makes MassGen:
Declarative - Describe what you want, not how to do it
Version-controllable - Config files in Git
Shareable - Easy to share and reproduce setups
Language-agnostic - No Python required for most users
See also
Configuration - Complete configuration guide with all options and examples
CLI-Based Execution#
MassGen is currently run via command line (a Python library API is planned for future releases):
Quick single agent:
massgen --model claude-3-5-sonnet-latest "Question"
Multi-agent with config:
massgen --config my_agents.yaml "Question"
Interactive mode:
# Omit question for interactive chat
massgen --config my_agents.yaml
See CLI Reference for complete CLI reference.
Execution Hierarchy#
Understanding MassGen’s execution hierarchy helps navigate logs and debug issues.
Session (multi-turn conversation)
└── Turn 1 (first user question)
│ └── Attempt 1 (orchestration execution)
│ ├── Round 1: Agent A processes → new_answer
│ ├── Round 2: Agent B processes → new_answer
│ ├── Round 3: Agent A processes → vote for B
│ └── Round 4: Agent B processes → vote for self → CONSENSUS
│
└── Turn 2 (second user question)
└── Attempt 1
├── Round 1: Agent A → new_answer
└── Round 2: Agent B → vote → CONSENSUS
Definitions:
Term |
Definition |
Log Path |
|---|---|---|
Session |
Multi-turn conversation. Spans multiple user interactions. |
|
Turn |
Single user question/task. Triggers full coordination. |
|
Attempt |
One orchestration execution. Restarts create new attempts. |
|
Round |
Single agent LLM call cycle: context → streaming → output. |
Recorded in |
Key Insight: Coordination ends when all agents vote (no new_answer calls). Each new_answer extends coordination; each vote moves toward consensus.
Multi-Agent Coordination#
How Coordination Works#
MassGen’s coordination follows a natural collaborative flow where agents observe each other’s work and converge on the best solution:
At each step, agents can:
See recent answers - Agents view the most recent answers from other agents
Decide their action - Each agent chooses to either:
Provide a new answer if they have a better approach or refinement
Vote for an existing answer they believe is best
Share context through workspace snapshots (if file operations are enabled) - When agents provide answers, their workspace state is captured, allowing other agents to see their work
Coordination completes when:
All agents have voted for solutions
The agent with most votes becomes the final presenter
Final presentation:
The winning agent delivers the coordinated final answer, using read/write permissions (if using filesystem operations and configured with context paths)
Coordination Flow Diagram#
Here’s how agents asynchronously evaluate and respond during coordination:
┌─────────────────────────────────────────────────────────────┐
│ ASYNCHRONOUS COORDINATION LOOP │
└─────────────────────────────────────────────────────────────┘
│
┌────────────┼────────────┐
│ │ │
┌───▼──┐ ┌───▼──┐ ┌───▼──┐
│Agent │ │Agent │ │Agent │
│ A │ │ B │ │ C │
└───┬──┘ └───┬──┘ └───┬──┘
│ │ │
┌───────────▼────────────▼────────────▼───────────┐
│ View ANONYMIZED Answers (Context) │
│ - ORIGINAL MESSAGE │
│ - CURRENT ANSWERs (anonymized) │
└───────────┬────────────┬────────────┬───────────┘
│ │ │
┌───────────▼────────────▼────────────▼───────────┐
│ "Does the best CURRENT ANSWER address the │
│ ORIGINAL MESSAGE well?" │
└───────────┬────────────┬────────────┬───────────┘
│ │ │
┌───────▼──────┐ │ ┌──────▼───────┐
│ YES │ │ │ NO │
│ │ │ │ │
┌───▼──────────┐ │ │ │ ┌─────────▼──────────┐
│Use `vote` │ │ │ │ │Digest existing │
│tool │ │ │ │ │answers, combine │
│ │ │ │ │ │strengths, address │
│ │ │ │ │ │weaknesses, then use│
│ │ │ │ │ │`new_answer` tool │
└───┬──────────┘ │ │ │ └─────────┬──────────┘
│ │ │ │ │
│ │ │ │ │
└──────────────┴─────┴─────┴──────────────┘
│
▼
┌──────────────────────────┐
│ All agents voted? │
│ (No new_answer calls) │
└────┬──────────────┬──────┘
│ │
YES │ │ NO
│ │
┌──────────▼───────┐ │
│ Select Winner │ │
│ (Most votes) │ │
└──────────┬───────┘ │
│ │
┌──────────▼───────┐ │
│ Final Presentation│ │
│ (Winner delivers)│ │
└───────────────────┘ │
│
┌──────────▼───────────────┐
│ Agent provided new_answer│
│ ↓ │
│ INJECT update to others: │
│ ALL agents receive update│
│ and continue with new │
│ answer in context │
│ (loop back to top) │
└──────────────────────────┘
Key Insights:
Asynchronous evaluation - Agents evaluate continuously and independently (no synchronized rounds)
Anonymized answers - Agents don’t know who provided which answer, reducing bias
Actual agent prompt - Agents evaluate “Does best CURRENT ANSWER address ORIGINAL MESSAGE well?”
Inject-and-continue - When any agent uses
new_answer, other agents receive an update appended to their conversation and continue (preserving their conversation history, though a new API call is made). Agents that haven’t produced their first answer yet are protected from interruption (see First-Answer Protection below).Natural consensus - Coordination ends only when all agents vote (no
new_answercalls)Democratic selection - Winner determined by peer voting
Streaming Architecture#
Each agent round involves streaming LLM responses with potential tool execution:
┌─────────────────────────────────────────────────────────────────┐
│ SINGLE AGENT ROUND │
└─────────────────────────────────────────────────────────────────┘
┌──────────────┐ ┌──────────────────────────────────────────┐
│ 1. CONTEXT │────▶│ 2. LLM API CALL (streaming) │
│ │ │ │
│ • Messages │ │ ┌────────────────────────────────────┐ │
│ • Tools │ │ │ Stream Chunks: │ │
│ • Prev Ans │ │ │ content → content → content → │ │
└──────────────┘ │ │ tool_calls → done │ │
│ └────────────────────────────────────┘ │
└──────────────────┬───────────────────────┘
│
┌────────────▼────────────┐
│ 3. TOOL EXECUTION? │
│ (if tool_calls) │
└────────────┬────────────┘
│
┌────────────────────┴────────────────────┐
│ │
┌──────▼──────┐ ┌───────▼──────┐
│ Yes: MCP │ │ No: Done │
│ or Custom │ │ │
│ Tool Call │ │ Output: │
└──────┬──────┘ │ new_answer │
│ │ or vote │
▼ └──────────────┘
┌─────────────┐
│ Execute & │
│ Add Result │
│ to Messages │
└──────┬──────┘
│
▼
┌─────────────┐
│ RECURSE: │
│ New LLM │──────▶ (back to step 2)
│ Call │
└─────────────┘
Streaming Flow:
Context Assembly - Messages, tools, and previous answers prepared
LLM Streaming - Response chunks arrive:
content,tool_calls,reasoning,doneTool Detection - If
tool_callschunk received, execute toolsRecursive Call - Tool results added to messages, new LLM call made
Completion - When
donereceived without tools, round complete
Context Management & Injection#
Each agent maintains an AgentConversationBuffer - a unified store that captures all streaming content and supports context injection from other agents.
Why a Unified Buffer?
During streaming, agents accumulate content, tool calls, reasoning, and tool results. When one agent provides a new_answer, other agents need to receive that update mid-work. The buffer ensures:
Complete context - All streaming content is captured and persisted
Working injection - Updates from other agents are immediately visible
Single source of truth - No fragmented storage locations
Data Flow During Streaming:
Backend yields chunks:
│
├── content chunk ──────► buffer.add_content("I'll analyze...")
│ └── Accumulates in pending content
│
├── reasoning chunk ────► buffer.add_reasoning("Let me think...")
│ └── Accumulates in pending reasoning
│
├── tool_call chunk ────► buffer.add_tool_call("read_file", {path: "x"})
│ └── Added to pending tool calls
│
├── tool_result chunk ──► buffer.add_tool_result("read_file", "call_1", "...")
│ └── Updates matching pending tool call
│
└── done chunk ─────────► buffer.flush_turn()
│
├── Creates permanent entries from pending data
└── Clears all pending accumulators
Data Flow During Injection:
When Agent A provides a new_answer, other agents receive an injection:
Agent A provides new_answer
│
▼
Orchestrator detects new_answer, sets restart_pending[B] = True
│
▼
Agent B reaches safe point (between LLM calls)
│
▼
Orchestrator injects into Agent B's buffer:
buffer_b.inject_update({"<anonymized>": "Here's my answer..."})
│
├── Formats injection message with <NEW_ANSWERS> tags
└── Creates INJECTION entry in buffer
│
▼
Agent B's next LLM call:
messages = buffer_b.to_messages() ← Includes injection entry
│
▼
agent.chat(messages) ← Agent sees the injected update!
Key Insight: The buffer ensures that when Agent B receives an injection, it sees:
Original context - The initial user question and system messages
Own previous work - All content, tool calls, and results from its streaming
New injection - The update from Agent A, formatted as a new user message
This allows agents to seamlessly continue their work with full awareness of what other agents have discovered.
First-Answer Protection#
When an agent submits a new_answer, MassGen signals all other agents to restart
or receive a mid-stream injection with the new context. However, agents that have not
yet produced their first answer are protected from these interruptions.
Why? Independent first answers are critical for diversity. If Agent A finishes quickly and Agent B is immediately restarted before completing its first round, Agent B never contributes an independent perspective – it only ever sees Agent A’s work. This undermines the parallel exploration that makes multi-agent coordination valuable.
How it works:
When any agent submits
new_answer, all agents are flagged withrestart_pendingBefore acting on the flag, MassGen checks whether the target agent has produced at least one answer
If the agent has no answer yet, the flag is cleared and the agent continues working undisturbed
If the agent already has an answer, the restart or injection proceeds normally
This guard applies to all injection paths: full restarts, mid-stream hook injection, and no-hook enforcement fallbacks. It does not apply to fairness gate restarts, which correctly prevent agents from voting before they have sufficient context.
Note
The restart_pending flag will be re-set if additional answers arrive while
the agent is still working on its first round. The protection only defers the
action – it does not permanently suppress updates.
What Agents See#
Answer Context:
Each agent sees the most recent answers from other agents anonymously. Answers are presented without attribution to reduce bias.
Key Points:
Anonymized evaluation - Agents don’t know which agent provided which answer
Focus on content - Decisions based on answer quality, not agent identity
Bias reduction - Prevents agents from favoring certain models or deferring to “authority”
Original message - All agents always see the initial user query
Best current answer - Agents evaluate if the best available answer is sufficient
This anonymous evaluation lets agents:
Compare different approaches objectively
Build on good insights regardless of source
Catch potential errors without bias
Decide whether to vote or provide a better answer based purely on merit
Note
Workspace Naming: Always use cwd: "workspace" in your configs rather than numbered names like workspace1 or workspace2. MassGen automatically adds unique random suffixes per agent at runtime (e.g., workspace_f7a3b2c1). This prevents agents from inferring their identity from workspace paths, which would undermine the anonymous voting design.
Workspace Snapshots (for file operations):
When an agent with filesystem capabilities provides an answer:
Their workspace is saved as a snapshot
Other agents can see this snapshot in their temporary workspace
This enables code review, file analysis, and iterative refinement
Example: If Agent A writes code and provides answer “agent_a.1”, Agent B can review that code in .massgen/temp_workspaces/agent_a/ before deciding to vote or provide improvements.
Voting Mechanism#
Agents participate in democratic decision-making by evaluating solutions and voting for the best answer:
Voting Process:
Each agent reviews answers from other agents
Agent decides: “Is there a better answer than mine?”
If YES → Vote for the better answer
If NO → Continue with their own answer or refine it
Natural Consensus:
The system reaches consensus when all agents have voted. No forced agreement - agents vote for what they genuinely believe is best based on their evaluation criteria.
Example Scenario:
Agent A (Researcher) - Provides detailed research → Votes for Agent C’s synthesis
Agent B (Analyst) - Provides data analysis → Votes for Agent C’s synthesis
Agent C (Synthesizer) - Combines insights → Votes for self (believes synthesis is best)
Result: Agent C wins with 3 votes (including self-vote) and presents the final answer.
Checklist-Gated Evaluation#
By default, agents decide when to vote based on their own judgment. Checklist-gated evaluation adds structured quality gates that agents must pass before they can vote, ensuring answers meet specific standards rather than relying on subjective “good enough” assessments.
This design is inspired by GEPA (Genetic-Pareto), a framework for optimizing systems through LLM-based reflection and Pareto-efficient evolutionary search. GEPA’s core insight is that structured diagnostic feedback – what it calls “Actionable Side Information” – produces far better iterative improvement than numeric scores alone. MassGen adapts this idea into multi-agent coordination: agents evaluate their work against explicit, evaluable criteria and receive structured feedback that guides their next iteration, rather than simply deciding “is this good enough?”
Rather than having a workflow-based improvement process encoded via code, MassGen is an interactive agent harness, with agents responsible for both implementing solutions and evaluating them against a checklist. This creates a tight feedback loop where agents diagnose weaknesses, propose specific improvements, implement them, and re-evaluate until they meet the quality bar to vote.
How It Works:
When voting_sensitivity: checklist_gated is enabled, agents follow a structured cycle:
┌─────────────────────────────────────────────┐
│ 1. IMPLEMENT │
│ Agent works on the task, produces output │
└──────────────────────┬──────────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ 2. SUBMIT CHECKLIST │
│ Agent scores its work against criteria: │
│ E1: Requirements met? (8/10) │
│ E2: No broken functionality? (9/10) │
│ E3: Thorough, no gaps? (6/10) │
│ E4: Shows care beyond correct? (5/10) │
└──────────────────────┬──────────────────────┘
│
┌──────┴──────┐
│ │
ITERATE VOTE/STOP
│ │
▼ ▼
┌────────────────────┐ ┌──────────────┐
│ 3. PROPOSE │ │ Terminal: │
│ IMPROVEMENTS │ │ Agent votes │
│ What to fix, │ │ for best │
│ what to keep │ │ answer │
└────────┬───────────┘ └──────────────┘
│
▼
┌────────────────────┐
│ 4. IMPLEMENT FIXES │
│ Submit improved │
│ new_answer │
│ (back to step 2) │
└─────────────────────┘
The Two Tools:
submit_checklist– The agent scores each criterion for the answers in context. The system returns a verdict: iterate (keep improving) or vote/stop (quality bar met). The agent cannot vote until the checklist says the work is ready.draft_approach– After an iterate verdict, the agent specifies what to fix and what to preserve. This creates a structured improvement plan rather than vague “make it better” instructions. The agent then implements the plan and submits a new answer.
Default Criteria (E1-E4):
MassGen ships with four default evaluation criteria that work across any task type:
ID |
Criterion |
Focus |
|---|---|---|
E1 |
The output directly achieves what was asked for – requirements are met, not just approximated. |
Correctness |
E2 |
No broken functionality, errors, or obvious defects. Everything that’s present works correctly. |
Functionality |
E3 |
The output is thorough – no significant gaps, thin sections, or placeholder content. |
Completeness |
E4 |
The output shows care beyond correctness – thoughtful choices, consistent style, attention to edge cases. |
Craft |
Custom Evaluation Criteria:
For tasks where the defaults are too generic, MassGen can generate task-specific criteria before coordination begins. Enable this with evaluation_criteria_generator: {enabled: true} in your config. A pre-coordination consensus run analyzes the task and produces tailored E1-EN criteria that replace the defaults.
You can also provide criteria directly via --eval-criteria criteria.json or --checklist-criteria-preset for common task types (persona generation, task decomposition, prompt crafting, log analysis).
Configuration:
orchestrator:
voting_sensitivity: checklist_gated # Enable checklist gates
evaluation_criteria_generator:
enabled: true # Generate task-specific criteria
min_criteria: 4
max_criteria: 7
Why Checklists Matter:
Without structured evaluation, agents tend to converge prematurely – voting for “good enough” answers that miss subtle quality gaps. The checklist forces agents to explicitly assess each quality dimension before they can vote, catching blind spots that subjective judgment misses. Combined with draft_approach, this creates a tight feedback loop: diagnose weaknesses, plan fixes, implement, re-evaluate.
Benefits of Multi-Agent Approach#
Diverse Perspectives - Different models, different insights
Error Correction - Agents catch each other’s mistakes
Collaborative Refinement - Ideas build on each other
Quality Convergence - Natural selection of best solutions
Robustness - System works even if some agents fail
Coordination Termination#
Coordination ends when one of these conditions is met:
Normal Completion:
✅ All agents have voted - Consensus reached naturally
✅ Winner selected - Agent with most votes presents final answer
Timeout:
⏰ Orchestrator timeout reached (default: 30 minutes)
System saves current state and terminates gracefully
Partial results preserved
Typical Duration:
Simple tasks: 1-5 minutes (2-3 rounds total across all agents)
Standard tasks: 5-15 minutes (3-5 rounds)
Complex tasks: 15-30 minutes (5-10 rounds)
Configuration:
timeout_settings:
orchestrator_timeout_seconds: 1800 # 30 minutes (default)
CLI Override:
massgen --orchestrator-timeout 600 --config config.yaml
See Timeout Configuration for complete timeout documentation.
Agents & Backends#
Agent Definition#
Each agent has:
ID: Unique identifier
Backend: LLM provider (Claude, Gemini, GPT, etc.)
Model: Specific model version
System Message: Role and instructions (system prompt)
Tools: Optional MCP servers or native capabilities
Example:
agents:
- id: "code_expert"
backend:
type: "claude_code"
model: "sonnet"
cwd: "workspace"
system_message: "You are a coding expert with file operations"
Backend Types#
MassGen supports multiple backend providers:
API-based: Claude, Gemini, GPT, Grok, Azure OpenAI, Z AI
Local: LM Studio, vLLM, SGLang
External Frameworks: AG2
Each backend type has different capabilities. See Supported Models & Backends for details.
Workspace Isolation#
Each agent gets an isolated workspace for file operations, preventing interference during coordination phase.
What is a Workspace?
A workspace is an agent’s private directory where it can:
Read, write, and edit files freely
Execute code and scripts
Create directory structures
Perform file operations without affecting other agents
All workspaces are stored under .massgen/workspaces/ in your project directory.
Example:
agents:
- id: "writer"
backend:
type: "claude_code"
cwd: "writer_workspace" # Isolated workspace: .massgen/workspaces/writer_workspace/
- id: "reviewer"
backend:
type: "gemini"
cwd: "reviewer_workspace" # Separate workspace: .massgen/workspaces/reviewer_workspace/
Benefits of Isolation:
No conflicts - Agents can’t accidentally overwrite each other’s files
Parallel work - Multiple agents modify files simultaneously
Clean state - Each agent starts with a fresh workspace
Workspace sharing - Agents can review each other’s workspaces via snapshots
See also
File Operations & Workspace Management - Complete workspace management guide including directory structure, snapshots, and safety features
MCP Tool Integration#
MassGen integrates tools via Model Context Protocol (MCP), enabling access to web search, weather, file operations, and many other external services.
Example:
backend:
type: "gemini"
model: "gemini-2.5-flash"
mcp_servers:
- name: "search"
type: "stdio"
command: "npx"
args: ["-y", "@modelcontextprotocol/server-brave-search"]
See also
MCP Integration - Complete MCP guide including common servers, tool filtering, planning mode, and security considerations
Project Integration#
Work directly with your existing codebase using context paths with granular read/write permissions.
What is a Context Path?
A context path is a shared directory that agents can access during collaboration. Unlike isolated workspaces, context paths allow agents to:
Read your existing project files for analysis
Write to your project (only the final agent during presentation)
Reference code, documentation, or data from your real project
Key Features:
Permission control - Specify
readorwriteaccess per pathCoordination safety - All paths are read-only during coordination
Final agent writes - Only the winning agent can write during final presentation
Protected paths - Mark specific files as read-only even within writable paths
Example:
orchestrator:
context_paths:
- path: "/Users/me/project/src"
permission: "read" # All agents can analyze code
- path: "/Users/me/project/docs"
permission: "write" # Final agent can update docs
protected_paths:
- "README.md" # Keep README read-only
All MassGen state organized under .massgen/ directory in your project root.
See also
Project Integration & Context Paths - Complete project integration guide
Protected Paths - Protect specific files within writable paths
File Operations & Workspace Management - File operation safety features
Interactive Multi-Turn Mode#
Start MassGen without a question for interactive chat with context preservation across turns.
# Single agent interactive
massgen --model gemini-2.5-flash
# Multi-agent interactive
massgen --config my_agents.yaml
Key Features:
Context preservation - Sessions are automatically saved and restored
Multi-turn coordination - Full coordination process runs for each turn
Workspace persistence - File operations persist across turns
Tool integration - MCP tools work seamlessly across turns
Session management - Resume previous conversations or start fresh
Tool Running in Multi-Turn:
When using MCP tools or file operations in multi-turn mode:
Tools execute during each turn’s coordination
Workspace state is preserved in
.massgen/sessions/Subsequent turns can access previous turn’s files and data
Planning mode can be enabled to prevent premature tool execution
Example Session:
Turn 1: "Create a website about Python"
# Agents coordinate, winner creates files in workspace
# Workspace saved to .massgen/sessions/session_abc123/
Turn 2: "Add a dark mode toggle"
# Agents see previous workspace, coordinate on improvements
# Winner modifies existing files
See also
Interactive Multi-Turn Mode - Complete interactive mode guide including commands, session management, and debugging
MCP Integration - Using MCP tools in multi-turn sessions
Planning Mode - Prevent premature tool execution during coordination
External Framework Integration#
AG2 Integration#
Integrate AG2 framework as a custom tool:
agents:
- id: "ag2_assistant"
backend:
type: "openai"
model: "gpt-4o"
custom_tools:
- name: ["ag2_lesson_planner"]
category: "education"
path: "massgen/tool/_extraframework_agents/ag2_lesson_planner_tool.py"
function: ["ag2_lesson_planner"]
system_message: |
You have access to an AG2-powered tool that uses
nested chats and group collaboration.
AG2’s multi-agent orchestration patterns are wrapped as tools that MassGen agents can invoke.
See General Framework Interoperability for details.
File Operation Safety#
Read-Before-Delete Enforcement#
MassGen prevents accidental file deletion:
Agents must read a file before deleting it
Exception: Agent-created files can be deleted
Clear error messages when operations blocked
Directory Validation#
All paths validated at startup
Context paths must be directories, not files
Absolute paths required
Permissions#
During coordination: All context paths are READ-ONLY
Final presentation: Winning agent gets configured permission (read/write)
See File Operations & Workspace Management for safety features.
System Architecture#
Execution Flow#
Load Configuration
Parse YAML configuration, validate paths, initialize agents
Coordination
Agents work in parallel, each seeing recent answers from others
Each agent decides: provide new answer or vote for existing answer
Other agents see snapshots in their temporary workspace
Continues until all agents have voted
Winner Selection
Agent with most votes is selected as final agent
Final Presentation
Winning agent delivers the coordinated final answer
If using context paths with write permission, winning agent can update project files
Output
Results displayed, logged, and workspace snapshots saved
Real-Time Visualization#
MassGen provides rich terminal UI showing:
Agent coordination table
Voting progress
Consensus detection
Streaming responses
Phase transitions
Disable with --no-display for simple text output.
State Management & .massgen Directory#
MassGen organizes all working files under the .massgen Directory in your project root. This keeps MassGen state separate from your project files.
Directory Structure:
.massgen/
├── workspaces/ # Agent workspaces
│ ├── agent1_workspace/ # Agent 1's isolated workspace
│ └── agent2_workspace/ # Agent 2's isolated workspace
├── snapshots/ # Workspace snapshots for sharing
│ └── agent1_snapshot_1/ # Agent 1's snapshot from coordination round 1
├── temp_workspaces/ # Temporary workspaces for viewing others' work
│ └── agent1/ # Agent 2 can see Agent 1's work here
├── sessions/ # Multi-turn session history
│ └── session_abc123/ # Saved session state
└── logs/ # Execution logs
Key Features:
Workspace isolation - Each agent has private workspace under
workspaces/Snapshot sharing - Agents share work via
snapshots/during coordinationSession persistence - Multi-turn conversations saved in
sessions/Clean separation - All MassGen files kept separate from your project
Git-friendly - Add
.massgen/to.gitignoreto exclude from version control
How State Persists:
During coordination: Agent workspaces and snapshots are created/updated
Between turns: Session state saved to
sessions/directoryOn restart: Sessions can be resumed from saved state
Final presentation: Winner’s workspace contains the final output
See Project Integration & Context Paths for using .massgen with your existing codebase.
Common Patterns#
Research Tasks#
agents:
- id: "gemini" # Fast web search
backend:
type: "gemini"
model: "gemini-2.5-flash"
- id: "gpt5" # Deep analysis
backend:
type: "openai"
model: "gpt-5-nano"
Coding Tasks#
agents:
- id: "coder" # Code execution
backend:
type: "claude_code"
cwd: "workspace"
- id: "reviewer" # Code review
backend:
type: "gemini"
Hybrid Teams#
agents:
- id: "ag2_executor" # AG2 framework tool
backend:
custom_tools:
- name: ["ag2_lesson_planner"]
# ... AG2 tool config
type: "openai"
# ... backend config
- id: "claude_analyst" # File operations
backend:
type: "claude_code"
# ... MCP config
- id: "gemini_researcher" # Web search
backend:
type: "gemini"
Best Practices#
Start Simple - Begin with 2-3 agents, add more as needed
Diverse Models - Mix different providers for varied perspectives
Clear Roles - Give each agent specific system messages
Use MCP - Leverage tools for enhanced capabilities
Enable Planning Mode - For tasks with irreversible actions
Context Paths - Work with existing projects safely
Interactive Mode - For iterative development
Next Steps#
Running MassGen - Practical examples
YAML Configuration Reference - Complete configuration reference
MCP Integration - Add tools to agents
Interactive Multi-Turn Mode - Interactive conversations
Project Integration & Context Paths - Work with your codebase
General Framework Interoperability - External framework integration