ctl
Multi-agent orchestration — compile, compose, chat, validate, run.
Objective
mas-ctl manages multi-agent systems described by declarative MAS manifests
(mas.yaml). It resolves topologies, applies flavours and infra bundles, runs
workflows, and provides the interactive CLI (chat, tui) on top of
mas-runtime.
mas-runtime ← single agent : kernel + contracts + design-pattern plugins
mas-ctl ← multi-agent : compile, compose, chat, run-mas, validate
mas-lab ← evaluation : benchmarks, pipelines, controller UI
Benchmarking is mas-lab, not mas-ctl.
Install
uv sync --all-packages
Quickstart
# Validate / compile manifests
mas-ctl validate agent.yaml
mas-ctl compile agent.yaml -o overlays/tools.yaml
# Interactive single agent
mas-ctl chat agent.yaml -q "Hello"
# Run a MAS
mas-ctl run-mas library-samples/apps/trip-planner/mas.yaml --flavour local
# Inspect workspace / infra
mas-ctl infra list
mas-ctl flavour list
Key concepts
MAS manifest (mas.yaml)
Declares agents, workflow, and metadata. See docs/manifests/mas.md.
Flavour
Selects model endpoint and non-secret configuration (local, mock, …) from
library-standard.
Scenario
Named overlay for A/B configuration without duplicating manifests.
Workspace
$XDG_CONFIG_HOME/mas/config.yaml and optional project config.yaml — see
docs/user-config.md for the full XDG layout.
CLI reference
| Command | What it does | Flags |
|---|---|---|
mas-ctl chat MANIFEST |
Interactive or scripted conversation | docs/cli/mas-ctl.md |
mas-ctl tui MANIFEST |
Terminal UI for chat | same · docs/ctl/tui.md |
mas-ctl run-mas MANIFEST |
Run a multi-agent workflow | docs/cli/mas-ctl.md |
mas-ctl compile … |
Dump resolved Agent/MAS YAML (overlays + defaults) | docs/cli/compile.md |
mas-ctl compose … |
Compose effective manifests / placement | mas-ctl compose --help |
mas-ctl plan … |
Dry-run placement plan | mas-ctl plan --help |
mas-ctl validate PATH … |
Validate agent / MAS / experiment YAML | docs/cli/mas-ctl.md |
mas-ctl schemas |
List JSON/YAML schemas | — |
mas-ctl flavour list|show |
List or show flavours | — |
mas-ctl infra list|show |
List or show infra bundles | — |
mas-ctl registry … |
Plugin registry introspection | mas-ctl registry --help |
mas-ctl checkpoint … |
Session checkpoint utilities | mas-ctl checkpoint --help |
mas-ctl list-bundles |
List library bundles | — |
Overview: docs/cli/index.md. Workspace YAML: docs/references/config.yaml.md.
Design philosophy
- Declarative over imperative — topology and policies in YAML.
- Secrets separated from config — only
*_envnames in manifests. - Thin CLI — click handlers call library code in
mas.ctl.*. - Library-first bench —
mas-labimports ctl session/bootstrap, not subprocesses.
Tutorials
Primary path (MkDocs): docs/tutorials/index.md
| # | Tutorial | Topic |
|---|---|---|
| 0 | Environment | Docker / uv, credentials, workspace |
| 1 | Building an agent | mas-ctl chat, overlays |
| 2 | Creating a MAS | mas.yaml, run-mas |
| 3 | Experiments | mas-lab benchmark run |
Examples
| Path | Description |
|---|---|
| library-samples/apps/ | Trip planner, Q&A, moderator variants |
| docs/tutorials/ | Copy-paste tutorial manifests |
Flavours ship in library-standard and resolve by name:
mas-ctl run-mas … --flavour local.
Documentation
| Document | Covers |
|---|---|
| ../docs/user-guide.md | Operational guide |
| ../docs/cli/index.md | CLI overview |
| ../docs/cli/mas-ctl.md | mas-ctl flags (--trace, --events, …) |
| ../docs/references/config.yaml.md | config.yaml fields |
| ../docs/cli/observability.md | events.jsonl |
| ../docs/manifests/ | YAML manifests |
| ../docs/libraries.md | Package matrix |
Related packages
| Package | Role |
|---|---|
mas-runtime |
Kernel, contracts, design patterns |
mas-lab |
Benchmarks, pipelines, UI |
library-standard |
Flavours, overlays, infra |
Metadata
Release files for mas-lab-ctl 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_ctl-0.2.0.tar.gz | 381.0 kB | With provenance | Details for mas_lab_ctl-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mas_lab_ctl-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for mas_lab_ctl-0.2.0-py3-none-any.whl |
Total release size: 783.1 kB
Release files / mas_lab_ctl-0.2.0.tar.gz
| Download URL | mas_lab_ctl-0.2.0.tar.gz |
|---|---|
| Size | 381.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
8bf94e22ab13c5530aad08884652d25b569a37455cb80302a4a6a42f8edf4a81
|
|
BLAKE2b-256 checksum How to use checksums |
2e8ddbc8b1d0448a09ee4b255d2a19ac82e8a94082cdc6ba48bce8c398bdebb3
|
| 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_ctl-0.2.0-py3-none-any.whl
| Download URL | mas_lab_ctl-0.2.0-py3-none-any.whl |
|---|---|
| Size | 402.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
516b181b19dfef3df5bc78ce955d9feffa610d3eaf8683f24b91e9f09a255034
|
|
BLAKE2b-256 checksum How to use checksums |
ae577df7d554e965d7eaff7b916c145608b93fb82de843f1faf8e31feafd6566
|
| 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-ctl 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_ctl-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.