Home Original page

GitHub - BUPT-GAMMA/MASFactory: A Graph-Centric Framework for Orchestrating Multi-Agent Systems with Vibe Graphing. Paper: http://arxiv.org/abs/2603.06007

MASFactory MASFactory

【English | Chinese】

πŸ“– Overview

MASFactory is a composable framework for orchestrating Multi-Agent Systems with Vibe Graphing:

start from intent, sketch a graph, converge the structure via visual preview/editing, compile it into an executable workflow, and trace runtime states/messages/shared-attributes end-to-end with MASFactory Visualizer.

Documentation: https://bupt-gamma.github.io/MASFactory/

Key capabilities:

  • Vibe Graphing (intent β†’ graph): generate a draft structure from intent, then iterate toward an executable workflow.
  • Graph composability: scale from simple pipelines to complex workflows with subgraphs, loops, switches, and composite components.
  • Visualization & observability: preview topology, trace runtime events, and handle human-in-the-loop requests in VS Code.
  • Context protocol (ContextBlock): structure and inject Memory / RAG / MCP context in a controllable way.

⚑ Quick Start

1) Install MASFactory (PyPI)

Requirements: Python >= 3.10

pip install -U masfactory

Verify installation:

python -c "import masfactory; print('masfactory version:', masfactory.__version__)"
python -c "from masfactory import RootGraph, Graph, Loop, Agent, CustomNode; print('import ok')"

2) Install MASFactory Visualizer (VS Code)

MASFactory Visualizer is a VS Code extension for graph preview, runtime tracing, and human-in-the-loop interactions.

Install from VS Code Marketplace:

  1. Open VS Code β†’ Extensions
  2. Search: MASFactory Visualizer
  3. Install and reload

Open it:

  • Activity Bar β†’ MASFactory Visualizer β†’ Graph Preview, or
  • Command Palette:
    • MASFactory Visualizer: Start Graph Preview
    • MASFactory Visualizer: Open Graph in Editor Tab

🧩 Simple Example (from β€œFirst Code”)

This is a minimal two-agent workflow: ENTRY β†’ analyze β†’ answer β†’ EXIT.

import os
from masfactory import RootGraph, Agent, OpenAIModel, NodeTemplate

model = OpenAIModel(
    api_key=os.getenv("OPENAI_API_KEY", ""),
    base_url=os.getenv("OPENAI_BASE_URL") or os.getenv("BASE_URL") or None,
    model_name=os.getenv("OPENAI_MODEL_NAME", "gpt-4o-mini"),
)

BaseAgent = NodeTemplate(Agent, model=model)

g = RootGraph(
    name="qa_two_stage",
    nodes=[
        ("analyze", BaseAgent(instructions="You analyze the problem.", prompt_template="Question: {query}")),
        ("answer", BaseAgent(instructions="You provide the final answer.", prompt_template="Question: {query}\nAnalysis: {analysis}")),
    ],
    edges=[
        ("entry", "analyze", {"query": "User question"}),
        ("analyze", "answer", {"query": "Original question", "analysis": "Analysis result"}),
        ("answer", "exit", {"answer": "Final answer"}),
    ],
)

g.build()
out, _attrs = g.invoke({"query": "I want to learn Python. Where should I start?"})
print(out["answer"])

▢️ Run multi-agent reproductions (applications/)

Most workflows require OPENAI_API_KEY. Some scripts also read OPENAI_BASE_URL / BASE_URL and OPENAI_MODEL_NAME.

# ChatDev
python applications/chatdev/workflow/main.py --task "Develop a basic Gomoku game." --name "Gomoku"

# ChatDev Lite (simplified)
python applications/chatdev_lite/workflow/main.py --task "Develop a basic Gomoku game." --name "Gomoku"

# ChatDev Lite (VibeGraphing version)
python applications/chatdev_lite_vibegraph/main.py --task "Write a Ping-Pong (Pong) game." --name "PingPong"

# VibeGraph demo (intent β†’ graph_design.json β†’ compile β†’ run)
python applications/vibegraph_demo/main.py

# AgentVerse Β· PythonCalculator task
python applications/agentverse/tasksolving/pythoncalculator/run.py --task "write a simple calculator GUI using Python3."

# CAMEL role-playing demo
python applications/camel/main.py "Create a sample adder by using python"

πŸ“š Learn MASFactory (docs outline)

Online documentation: https://bupt-gamma.github.io/MASFactory/

  • Quick Start: Introduction β†’ Installation β†’ Visualizer β†’ First Code
  • Progressive Tutorials: ChatDev Lite (Declarative / Imperative / VibeGraph)
  • Development Guide: Concepts β†’ Message Passing β†’ NodeTemplate β†’ Agent Runtime β†’ Context Adapters β†’ Visualizer β†’ Model Adapters

πŸ—‚οΈ Project structure

.
β”œβ”€β”€ masfactory/               # MASFactory Framework
β”‚   β”œβ”€β”€ core/                 # Foundation: Node / Edge / Gate / Message
β”‚   β”œβ”€β”€ components/           # Components (Agents / Graphs / Controls / CustomNode)
β”‚   β”‚   β”œβ”€β”€ agents/           # Agent, DynamicAgent, SingleAgent
β”‚   β”‚   β”œβ”€β”€ graphs/           # BaseGraph, Graph, RootGraph, Loop
β”‚   β”‚   └── controls/         # LogicSwitch, AgentSwitch
β”‚   β”œβ”€β”€ adapters/             # Adapters (Model / Tool / Memory / Retrieval / MCP)
β”‚   β”‚   └── context/          # Context pipeline (ContextBlock / policy / renderer / composer)
β”‚   β”œβ”€β”€ integrations/         # 3rd-party integrations (MemoryOS / UltraRAG, etc.)
β”‚   β”œβ”€β”€ utils/                # Utilities (config, hook, Embedding, etc.)
β”‚   β”œβ”€β”€ resources/            # Resources and static files
β”‚   └── visualizer/           # MASFactory Visualizer runtime integration
β”œβ”€β”€ masfactory-visualizer/    # VSCode extension: MASFactory Visualizer
β”œβ”€β”€ applications/             # Examples and reproductions based on MASFactory
β”‚   β”œβ”€β”€ chatdev_lite/
β”‚   β”œβ”€β”€ chatdev/
β”‚   β”œβ”€β”€ agentverse/
β”‚   β”œβ”€β”€ camel/
β”‚   └── number_off_demo.py
β”œβ”€β”€ docs/                     # VitePress docs
β”‚   β”œβ”€β”€ .vitepress/
β”‚   └── src/
β”‚       β”œβ”€β”€ zh/
β”‚       └── en/
β”œβ”€β”€ examples/                 # Graph patterns (imperative vs declarative)
β”œβ”€β”€ README.md                 # English (default)
β”œβ”€β”€ README.zh.md              # Chinese
β”œβ”€β”€ pyproject.toml
β”œβ”€β”€ requirements.txt
└── uv.lock