Skip to main content

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.

License Python

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:

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:

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)

Source distribution for mas-lab 0.2.0
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)

Table of built distributions (wheels) for mas-lab 0.2.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page