Skip to content

mas-ctl compile

Apply a manifest plus overlay stack and write the resolved spec: overlays merged, omitted runtime defaults filled. That is the in-memory Agent or MAS dict chat / run-mas hold before bootstrap wiring (delegation tools, skill injection, expanding tool refs to files).

mas-ctl compile applies target.kind: Agent overlays onto each nested agent file. compose / run-mas merge MAS overlays onto the MAS document (workflow, agency $op, models) and merge per-agent overlay patches onto the referenced Agent YAML when that file is loaded. Form A rows stay {id, ref}. See overlay.md.

mas-ctl compose is different: it emits EffectiveBind + placement. Use compile to inspect or snapshot YAML; use compose to inspect runtime bind and placement.

Terms: glossary.md · overlays: overlay.md

Basic usage

# Tutorial 1 — stdout (one Agent document)
mas-ctl compile docs/tutorials/01-building-an-agent/agent.yaml \
  -o docs/tutorials/01-building-an-agent/overlays/tools.yaml \
  -o docs/tutorials/01-building-an-agent/overlays/skills.yaml \
  -o docs/tutorials/01-building-an-agent/overlays/memory.yaml

# One agent → one file
mas-ctl compile agent.yaml -o overlays/tools.yaml -O compiled-agent.yaml

# MAS → folder (mas.yaml + agents/, refs rewritten)
mas-ctl compile mas.yaml -o overlays/linear.yaml -O ./compiled/

# MAS → one file with agents inlined under spec.agency.agents
mas-ctl compile mas.yaml -o overlays/linear.yaml --layout bundle -O team.yaml

--output / -O is a folder for a MAS tree, or a file for a single agent (and for --layout bundle). Omit it to print a bundle document on stdout.

Layout: tree vs bundle vs auto

Layout Agent MAS When to use
auto (default) file / stdout directory → tree; .yaml → bundle Usual CLI
tree agent.yaml in a folder mas.yaml + original agents/… paths Diff, re-validate, re-run with the same file layout
bundle one Agent YAML one MAS YAML with inlined Agent documents Snapshot, review, “what did the runtime see?”

Inlining a whole MAS in one file is valid (agency.agents may be either {id, ref} or a full kind: Agent document). It is the best match for the in-memory tree. A folder of files is better for editing and for mas-ctl validate / run-mas that still expect separate agent files.

Relative tool/skill refs are not rewritten. Library scheme refs (samples:tools/…) stay portable; ../../tools/foo.tool.yaml still resolves from the original agent directory, not from the compiled tree.

Defaults

Omitted plugin slots are filled from the same accessors the runtime uses (defaults.yaml). Model is not baked in: omitted Agent/MAS models compile to any. At engine time the chain is CLI → Agent → MAS → experiment.models.main / experiment.model → local config.yaml defaults.model (then package defaults.yaml).

  • spec.design_pattern (package default react; string design_pattern: cot ≡ {type: cot}. Compile fills params.max_cot_pass: 1, parallel: true. max_steps is omitted unless a production overlay such as with-hardened sets it)
  • spec.models[0] (model: any when omitted — inherit MAS / experiment.models.main, then local config.yaml at runtime)
  • MAS spec.models[0] (same any sentinel when the MAS omitted a default)
  • spec.context_manager (summarising, keep_turns 10, hysteresis_ratio 0.1, summarizer: llm, safety margin 0.1)

Auto context windows are resolved at runtime after infra model mappings; compile does not freeze an unknown or remappable model to a generic window. Unknown models use the 128,000-token fallback with a warning. See Context Management. - spec.assembler (package default assembler; compile fills emit_segments: true, always_reassemble: false)

Pass --no-defaults to emit overlay merge only. Explicit values are never overwritten.

Flags

Flag Description
-o / --overlay Overlay YAML (repeatable, later wins)
--override ROOT:PATH=VALUE Schema-backed path override, repeatable; applied after overlays
-O / --output Directory or YAML file
--layout auto\|tree\|bundle Output shape (see table)
--no-defaults Skip filling runtime defaults
--no-validate Skip schema validation
--no-header Omit the generated-by comment

Flavour and infra overlays are skipped (compile emits Agent/MAS specs only). MAS overlays cannot be applied to an Agent manifest.

For a MAS, use the mas: root to select an agency entry or update the MAS document; use agent: for a standalone Agent manifest:

mas-ctl compile mas.yaml \
  --override 'mas:spec.agency.agents[id=qa].spec.context.role="reviewer"'
mas-ctl compile agent.yaml \
  --override 'agent:spec.context.role="reviewer"'

See the full override reference and the Overlay manifest reference for target names, patch schemas, selectors, wildcards, precedence, and compatibility rules.

See also