MAS-Lab

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 process: RELEASE-PROCESS.md
• Release overview: blog post

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 published packages
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
mas-ctl run-mas library-samples/apps/trip-planner/mas.yaml \
  --infra-ref standard:openai \
  -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.html

Then continue with:

Full install instructions: Tutorial 0 — Environment setup.
Full site content mirrors docs/ — see docs/index.md for the full introduction.

Choose the installation mode that matches the job:

The problem

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.

What MAS-Lab provides

• 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)

Protocol integrations: optional runtime adapters, not core logic

MCP and A2A are not required to validate an agent's reasoning, workflow, or
logic. They are production deployment concerns: remote tool access and remote
agent communication.

That distinction is deliberate. A team can build and test an agent with local
contracts and local execution without any protocol wiring at all. Once the system
needs a remote tool server or a remote peer, MAS-Lab swaps in an infra adapter
instead of rewriting the agent logic.

This matters because protocol integration is not just “another plugin.” It
involves discovery, routing, transport compatibility, authentication, lifecycle
semantics, compliance behavior, and ongoing maintenance as the protocol evolves.
A good runtime treats this as a platform concern, not a business-logic concern.

With the right separation, the system gains several benefits:

• logic remains stable while transport and protocol choices change;
• teams can certify protocol behavior once and reuse it across many agents;
• new versions and compliance fixes land in the infra layer rather than in each agent;
• local development remains lightweight: minimal agents can avoid remote protocol code entirely;
• security, auditability, and code review happen at the integration boundary instead of scattered through agent logic.

This is the design underlying the MCP and A2A tutorials:

• docs/tutorials/04-mcp-tools/README.md — switching local tool execution to MCP without rewriting agent logic
• docs/tutorials/05-a2a-agents/README.md — switching a delegated agent path from local to A2A without changing the MAS workflow
• docs/references/tool-server-registry.md — full MCP infra reference
• docs/a2a/developer.md — A2A contract and routing reference
• docs/manifests/infra.md — infrastructure manifest model and separation of concerns

Who it is for

• Developers — specs instead of glue code; tutorials
• Enterprises — overlays for policy, audit, and control; user guide
• Researchers — reproducible campaigns; paper labs

Packages

The headline packages:

mas-lab is a meta-package that installs the lab components (mas-lab-core,
mas-lab-bench, and mas-lab-controller).
Additional libraries ship alongside it (mas-library-eval, mas-library-lab,
mas-library-samples).

A lab (*.lab/ + lab-config.yaml) is the experiment surface. A
library is a folder with library.yaml. When to create each, how to
keep a local library inside a lab, and how name:path refs work:
docs/labs-and-libraries.md. Discovery
contract (developers): docs/library-discovery.md.

See docs/libraries.md for the installable package map and
docs/packages-reference.md for the complete,
auto-generated package list with dependencies and extras.

Supported versions

Security fixes are applied to the latest release on the main branch.

Citing this work

If you use MAS-Lab in research or publications, cite the
MAS-Lab article — not only this repository.

Contributing

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

License

Distributed under the Apache 2.0 License. See LICENSE for more
information.