MAS Lab
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: ioc-project.github.io/mas-lab
- Release process: RELEASE-PROCESS.md
- Release notes: v0.1 post · v0.2 post
What MAS Lab provides
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).
Get started
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
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 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.html
Step 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-lint, or task verify-unit |
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 |
Protocols are adapters, not core logic
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 · A2A internals
- Infra manifest model
Packages
| Directory | Role |
|---|---|
runtime/ |
Agent runtime — contracts, plugins, design patterns |
ctl/ |
Orchestration — chat, run-mas, validate (flags) |
. (repo root) |
Meta-package — installs the runtime, control plane, lab components, and libraries |
lab/components/core/ |
Lab CLI (mas-lab) plus contracts, telemetry, and shared utilities |
library-standard/ |
Flavours, overlays, infra bundles |
mas-lab is an empty meta-package. The mas-lab command ships in
lab/components/core/. Installing the meta-package pulls core, bench, controller,
runtime, ctl, and the published libraries. The lab itself is the three
components under lab/components/. Wheel names are generated into the
packages reference.
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.
Supported versions
Security fixes are applied to the latest release on the main branch.
| Version | Supported |
|---|---|
latest on main |
yes |
| older tagged releases | best effort |
Citing this work
If you use MAS Lab in research or publications, cite the MAS Lab article (arXiv:2606.30546) — not only this repository. Reproduction of Section 5 is on the Paper page.
Contributing
Contributions are welcome. See CONTRIBUTING.md and SECURITY.md.
License
Distributed under the Apache 2.0 License. See LICENSE for more
information.
Metadata
Release files for mas-lab 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mas_lab-0.2.0.tar.gz | 9.1 kB | With provenance | Details for mas_lab-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mas_lab-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for mas_lab-0.2.0-py3-none-any.whl |
Total release size: 17.4 kB
Release files / mas_lab-0.2.0.tar.gz
| Download URL | mas_lab-0.2.0.tar.gz |
|---|---|
| Size | 9.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d67476b5dc50044421a9f2476fc98f4416ea9a1623386bd05e9e6e36c947bfbd
|
|
BLAKE2b-256 checksum How to use checksums |
e6e14654fd76e2b05ff89f69d111921998aadd2b4c319e6dccf0901beaa34d0f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logRelease files / mas_lab-0.2.0-py3-none-any.whl
| Download URL | mas_lab-0.2.0-py3-none-any.whl |
|---|---|
| Size | 8.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
33de0c9514088fec2094cd5add14e1eb1df3bb309d9ddbc3cf67ed9dde0a0e45
|
|
BLAKE2b-256 checksum How to use checksums |
a159c0189331afa3a7867d0e5d3c10d0b0460a9131fbe2d576a88bf481d68998
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logSecurity for mas-lab 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for mas_lab-0.2.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.