Skip to content

MAS Lab — Hands-On Tutorials

These tutorials take you from one agent to full experiments. Each builds on the previous ones. You can also reproduce the paper labs or use the web UI.

Start with Tutorial 0. It covers the Docker or developer install, LLM credentials, and a check that everything works. The CLI and web UI share it.

Choose a route

If you want to... Start here
See a multi-agent system run Tutorial 0, then Tutorial 1
Understand the model: agents, MAS, overlays Tutorials 0, 1, 2
Run a controlled experiment Tutorial 3, then the paper labs
Add governance and human approval Tutorial 14
Export traces to an observability stack or a knowledge graph Tutorials 8 and 9
Click instead of type The web UI
# Tutorial What you learn
0 Environment Setup Install, PATH, model endpoint, API key wiring
1 Build an agent Agent manifest, tools, skills, memory, CLI, traces
2 Orchestrate your MAS MAS manifest, delegation, topology overlays
3 Run an experiment Experiments, benchmarks, pipelines, and MCE evaluation (Metrics Computation Engine)
4 MCP tools Call local and remote tools (Model Context Protocol) through one contract
5 A2A agents Call local and remote agents (Agent2Agent) through one contract
6 Agent skills Give an agent a reusable skill (procedure, reference material, checked script) outside its own instructions
7 (reserved)
8 Telemetry Native traces, live OTel, replay, collector / ClickHouse
9 KG & SCOPE Build a knowledge graph (KG) from native traces or OpenTelemetry (OTel) spans, using the SCOPE norm normalizer; write to Neo4j
10 Evaluation metrics Stock MCE, one-off prompts, reusable EvalMetrics, judge infra
11 Sessions and recovery Checkpoint, fork, resume and recover a conversation
12 Spawned subagents Run bounded, pre-authored subagent templates during a turn
13 Control attach and debug scripts Interrupt a bad session, persist, resume; investigate; steer-to-fix on the restarted chat; auto-checkpoint tree; gdb script_file / --debug-script
14 Governance and HITL Require human or policy approval (human in the loop, HITL) before a tool call runs

After Tutorial 14, reproduce the paper results in three labs: Paper.

Do Tutorials 0 to 3 in order: install, then one agent, then a MAS, then experiments. Tutorials 4 to 6 and 8 to 14 each cover one capability. Each page lists its prerequisites at the top, usually Tutorial 0 plus the agent or MAS it reuses.

Every tutorial except 10 ships a demo/scenario.yaml with steps, commands, expected exit codes, and sometimes expected output. CI runs the offline steps with tests/tutorials/test_scenario_commands.py, so the commands stay working.

To replay the offline commands, run this from the repository root:

pytest tests/tutorials/test_scenario_commands.py -v              # offline steps only
pytest tests/tutorials/test_scenario_commands.py -v -k tuto-03   # one tutorial
TUTORIAL_ONLINE=1 pytest tests/tutorials/test_scenario_commands.py -v -k tuto-01   # also live-LLM steps

Telemetry is Tutorial 8 (mas-library-telemetry). Knowledge-graph normalization is Tutorial 9 (mas-library-kg).

Sample applications

The labs run on sample systems from library-samples/apps. They are also the fastest way to see the runtime work.

Application What it is Used by
trip-planner A four-agent moderator and specialists system Topology and memory experiments
qa-mas A one-agent MAS wrapping a question-answering agent Design-pattern experiments

Both come with datasets. The trip planner's is trip-planner-benchmark.

What's next

After Tutorial 14:

Next: Tutorial 0 — Environment setup.