A specification-driven foundation for building multi-agent systems that are testable, reproducible, observable, and governable from design to production.
Modern multi-agent systems are easy to prototype, but hard to trust at scale. MAS-Lab helps developers, enterprises, and researchers move from prompt-glued prototypes to engineered agentic systems — with explicit specifications, runtime contracts, reproducible experiments, and built-in observability.
- Documentation site: outshift-open.github.io/mas-lab
- Release overview: blog post
# 1 — Install (Docker or developer path — see Tutorial 0)
pip install mas-lab mas-library-standard mas-library-samples
# 2 — Configure LLM access (interactive, writes ~/.config/mas/config.yaml)
mas-lab init
# 3 — Export the API key printed by init
export OPENAI_API_KEY=<your-key>
# 4 — Run the trip-planner sample (mock LLM, no key required)
mas-ctl run-mas library-samples/apps/trip-planner/mas.yaml \
--infra-ref standard:mock-llm \
-q "Plan a trip from Celestia to Verdantia"
# 5 — Inspect traces
mas-lab telemetry show library-samples/apps/trip-planner/traces/events.jsonl
mas-lab plot trajectory library-samples/apps/trip-planner/traces/events.jsonl \
--format html -o traces/trip-planner-trajectory.htmlThen continue with:
| Path | Link |
|---|---|
| Tutorials | docs/tutorials/ |
| Web UI demo | docs/ui/index.md |
| Paper labs | docs/paper/index.md |
Full install instructions: Tutorial 0 — Environment setup.
Full site content mirrors docs/ — see docs/index.md for the full introduction.
Prototype demos are easy; production-grade trust is not. Prompts, tools, orchestration, and control are often interwoven, so behavior is hard to reproduce, debug, or govern. MAS-Lab separates intent, execution, observability, and governance through a shared specification and runtime model.
- Declarative MAS specifications (agents, tools, workflows, contracts)
- Runtime enforcement at system boundaries
- Governance and experimentation overlays
- Observability, replay, and benchmark pipelines
- Three reproducible paper labs (Section 5)
- Developers — specs instead of glue code; tutorials
- Enterprises — overlays for policy, audit, and control; user guide
- Researchers — reproducible campaigns; paper labs
The headline packages:
| Package | Role |
|---|---|
mas-runtime |
Agent runtime — contracts, plugins, design patterns |
mas-ctl |
Orchestration — chat, run-mas, validate |
mas-lab |
Meta-package — benchmarks, pipelines, telemetry, UI controller |
mas-library-standard |
Flavours, overlays, infra bundles |
mas-lab is a meta-package that installs the lab components (mas-lab-core,
mas-lab-bench, mas-lab-controller, mas-lab-content).
Additional libraries ship alongside it (mas-library-eval, mas-library-lab,
mas-library-samples).
See docs/libraries.md for the library model and docs/packages-reference.md for the complete, auto-generated package list with dependencies and extras.
Security fixes are applied to the latest release on the main branch.
| Version | Supported |
|---|---|
latest on main |
yes |
| older tagged releases | best effort |
If you use MAS-Lab in research or publications, cite the MAS-Lab article — not only this repository.
Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated. For detailed contributing guidelines, please see CONTRIBUTING.md · SECURITY.md
Distributed under the Apache 2.0 License. See LICENSE for more
information.