User guide¶

How to install and use MAS Lab: single agents, multi-agent teams, batch experiments, and optional libraries.

MAS Lab is a specification-driven toolkit. You declare agents and experiments in YAML, run them with mas-ctl and mas-lab, and analyze results through reusable benchmark pipelines.

Related: References · Web UI · Run logs · Paper labs · Glossary

Ways to work with MAS Lab¶

Several entry points fit different goals. All of them need a working environment first — complete Tutorial 0 — Environment setup once (Docker or developer install, LLM credentials). The same setup covers the CLI and the optional web UI.

Hands-on tutorials¶

Learn the toolkit step by step: one agent, then a multi-agent team, then a full benchmark experiment.

	Tutorial	What you will do
0	Environment setup	Install and verify your environment
1	Build an agent	Author a manifest and chat with your agent
2	Orchestrate your MAS	Define a team and run it end to end
3	Run an experiment	Run a benchmark and inspect results

Tutorials index

Paper labs¶

Reproduce the experiments from the MAS-Lab article — three labs under labs/ that match Section 5 of the paper.

Paper labs & reproducibility

Web UI¶

Design agents and experiments, browse manifests, and inspect benchmark runs in the browser. Started as part of Tutorial 0 (same Docker stack).

Web UI guide

Three CLIs¶

CLI	Package	Use for
`mas-ctl`	`ctl/`	Chat, TUI, compose, validate, `run-mas`
`mas-runtime`	`runtime/`	Headless `run-agent` (Docker / CI)
`mas-lab`	`lab/`	Benchmarks, pipelines, controller UI

Benchmarking is always mas-lab, not mas-ctl.

Included libraries¶

mas-runtime
mas-lab
mas-ctl
mas-library-standard
mas-library-lab

Full package map: libraries.md.

Install¶

Docker (recommended for new users)¶

git clone https://github.com/outshift-open/mas-lab.git && cd mas-lab
cd docker && cp .env.example .env
# Edit .env and set OPENAI_API_KEY if you plan to call a live model
docker compose build backend

Then follow Tutorial 0 for workspace setup and your first mas-ctl commands.

Mount your project at /workspace and persistent data at /data via MAS_WORKSPACE_MOUNT and MAS_DATA_MOUNT in docker/.env. See docker/README.md in the repository.

Start the web UI (same compose stack):

docker compose up --build
# UI http://localhost:8080 · API http://localhost:8090

See Web UI for what you can do in the browser.

From source (developers)¶

Recommended consumption model:

Install versioned OSS packages normally.
Use packaged sample apps through their canonical pkg:// URIs.
Only switch to editable multi-package development when you are modifying the OSS code itself.

Typical install from a development checkout:

uv sync --all-packages

# Optional but recommended: avoid prefixing every command with `uv run`
export PATH="$PWD/.venv/bin:$PATH"

# Verify command resolution
mas-runtime --help >/dev/null
mas-ctl --help >/dev/null
mas-lab --help >/dev/null

Editable installs per package when developing:

uv pip install -e runtime -e lab -e ctl -e library-standard -e library-lab

Typical install from a package index:

uv pip install mas-lab

Sample apps¶

Canonical sample app references:

app: trip-planner — resolves mas.yaml via mas.apps (from mas-library-samples)
samples:apps/trip-planner/mas.yaml — manifest library scheme ref

When you work from a source checkout, relative paths under library-samples/ or tutorial directories also work. Prefer app: or library scheme refs in committed labs so paths stay stable across machines.

Typical workflow¶

Build or run an agent with runtime.
Orchestrate multi-agent setup with ctl.
Run experiments with lab.
Add standard/library-lab extensions as needed.

Referencing apps from labs¶

When a lab needs to run an app, use one of these three patterns.

1. Library app via `app:` or `samples:` scheme (recommended)¶

mas:
  app: trip-planner
  base_scenario: baseline

Or an explicit manifest library path:

applications:
  - manifest: samples:apps/trip-planner/mas.yaml

2. Absolute path inside the current workspace¶

Use for local development when the app lives in the same checkout but is not packaged yet.

3. Symlink through a local library-like folder¶

Use only for local composition — not for committed OSS labs.

For committed reusable OSS examples, prefer app: or samples: scheme refs.

Running agents with observability¶

Use mas-ctl chat for single-agent runs:

mas-ctl chat my-agent.yaml -q "Your question here" -v
mas-ctl chat my-agent.yaml -q "Your question here" --trace

Example from Tutorial 1:

cd docs/tutorials/01-building-an-agent
mas-ctl chat agent.yaml -o overlays/tools.yaml \
  -q "What is the capital of France?" -v

See cli/observability.md for events.jsonl and trace flags.

Configuration¶

Machine-wide paths and workspace defaults: user-config.md.

Runtime contributor docs live under runtime/docs/ (Mealy envelope, contracts, design patterns).

The public repository ships tutorials 0–3, three paper labs under labs/, and the v2 Mealy runtime kernel.