Skip to main content

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

  1. Declarative over imperative — topology and policies in YAML.
  2. Secrets separated from config — only *_env names in manifests.
  3. Thin CLI — click handlers call library code in mas.ctl.*.
  4. Library-first bench — mas-lab imports 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

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)

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

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

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

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

Select from 2 files

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