MAS Lab builds, runs, and tests multi-agent systems (MAS) from YAML files. A MAS is a team of LLM agents with tools and a workflow that says who talks to whom.
It is for three audiences:
- Developers write agents, tools, and workflows as specs instead of glue code. Start with the tutorials.
- Enterprises add policy, audit, and budget controls as overlays. Start with the user guide.
- Researchers run repeatable experiments and compare designs. Start with the paper labs.
Links:
- Documentation site: outshift-open.github.io/mas-lab
- Release process: RELEASE-PROCESS.md
- Release notes: v0.1 post · v0.2 post
Prototype multi-agent demos are easy. Trusting them in production is not, because prompts, tools, orchestration, and control are interwoven. Behaviour is then hard to reproduce, debug, or govern.
MAS Lab separates intent, execution, observability, and governance through one specification. It provides:
- Declarative specs for agents, tools, workflows, and contracts.
- Runtime enforcement of those contracts at system boundaries.
- Governance and experiment overlays (small YAML files merged onto a spec).
- Tracing, replay, and benchmark pipelines.
- Three reproducible paper labs (Section 5 of the article).
PyPI publication pending: the package names and installation path are prepared, but the public packages are not uploaded yet. Use the Docker or developer workspace paths below until the first PyPI release is complete.
# 1 — Install the packages (once published; until then see the paths below)
uv venv
uv pip install mas-lab mas-library-standard mas-library-samples
export PATH="$PWD/.venv/bin:$PATH"
# 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
# (`samples:` resolves the app shipped in mas-library-samples; from a source
# checkout you can pass library-samples/apps/trip-planner/mas.yaml instead)
mas-ctl run-mas samples:apps/trip-planner/mas.yaml \
--infra-ref standard:openai \
--events-file "$PWD/traces/trip-planner.jsonl" \
-q "Plan a trip from Celestia to Verdantia"
# 5 — Inspect the trace written by step 4
mas-lab telemetry show traces/trip-planner.jsonl
mas-lab plot trajectory traces/trip-planner.jsonl \
--format html -o traces/trip-planner-trajectory.htmlStep 4 writes traces/trip-planner.jsonl, the machine-readable trace of the
run (one JSON event per line). Step 5 prints it and plots the trajectory.
Pick the installation mode that matches your job:
| Mode | Use it for | Validation entry point |
|---|---|---|
| PyPI + uv venv (once published) | Running a published release | mas-ctl validate / mas-ctl chat |
| Docker | Running without a local Python environment | docker compose --profile tools run --rm cli mas-ctl validate ... |
| Developer workspace | Editing MAS Lab itself | uv run pytest, task verify-unit, or task ci |
Full install steps: Tutorial 0 — Environment setup.
The documentation site mirrors docs/; start at docs/index.md.
Then continue with:
| Path | Link |
|---|---|
CLI (mas-lab) |
docs/cli/mas-lab.md |
CLI (mas-ctl) |
docs/cli/mas-ctl.md |
| Tutorials | docs/tutorials/ |
| Web UI (authoring) | docs/ui/index.md |
| Live dashboard | docs/ui/live.md |
| Paper labs | docs/paper/index.md |
| Labs vs libraries | docs/labs-and-libraries.md |
MCP (Model Context Protocol, for remote tools) and A2A (Agent2Agent, for remote agents) are deployment concerns. You do not need them to test an agent's reasoning or workflow.
Build and test an agent with local tools and local delegation first. When you need a remote tool server or a remote peer, MAS Lab swaps in an infra adapter. The agent logic does not change.
Keeping protocols in the infra layer has these effects:
- Agent logic stays stable while transport and protocol choices change.
- You certify protocol behaviour once and reuse it across agents.
- Protocol upgrades and compliance fixes land in one place, not in every agent.
- Minimal agents carry no remote-protocol code.
- Security review and auditing happen at the integration boundary.
Details:
- Tutorial 4 switches local tool execution to MCP.
- Tutorial 5 switches a delegated agent from local to A2A.
- MCP infra reference
- A2A contract and routing
- Infra manifest model
| Package | Role |
|---|---|
mas-runtime |
Agent runtime — contracts, plugins, design patterns |
mas-ctl |
Orchestration — chat, run-mas, validate (flags) |
mas-lab |
Meta-package — benchmarks, pipelines, telemetry, UI controller |
mas-library-standard |
Flavours, overlays, infra bundles |
mas-lab installs three lab components (mas-lab-core, mas-lab-bench,
mas-lab-controller) plus mas-runtime, mas-ctl, and mas-library-eval.
Add other libraries as separate packages: mas-library-samples,
mas-library-lab, mas-library-ioa, mas-library-kg, mas-library-skills,
mas-library-telemetry.
A lab (*.lab/ plus lab-config.yaml) is where you run experiments. A
library is a folder with library.yaml holding reusable apps, tools, and
plugins. See labs and libraries for when to create
each and how name:path references work. Developers: see the
library discovery contract.
The package map lists installable packages. The packages reference is auto-generated and lists 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 welcome. See CONTRIBUTING.md and SECURITY.md.
Distributed under the Apache 2.0 License. See LICENSE for more
information.