Skip to content

Manifest reference

MAS Lab reads YAML manifests: declarative files that describe agents, multi-agent systems, experiments, datasets, overlays, and pipelines.

This folder documents each YAML kind (kind: Agent, MAS, Overlay, and so on). It also documents fields that have no kind of their own, such as spec.governance, which lives next to Agent. Runtime behaviour that spans several fields (retries, circuit breaker, logging) lives under references/. Start at reliability.md.

New to the vocabulary? Read glossary.md first (scenario, overlay, pipeline, run, flavour).

Hands-on path:

  1. Tutorial 1: build an agent.
  2. Tutorial 2: build a multi-agent system (MAS).
  3. Tutorial 3: run experiments.

How manifests fit together

For the exact address space used by --override PATH=VALUE, see the session tree. It distinguishes source documents from resolved runtime nodes, and explains why ref bindings are not automatically traversable YAML subtrees.

experiment.yaml          <- what to run (scenarios x dataset x n_runs + pipelines)
    |
    +-- application     -> mas.yaml / registered app
    +-- scenarios[]     -> overlay stacks, one per variant
    +-- dataset         -> Dataset items (inputs + expectations)
    +-- run/item/scenario/post -> pipeline steps (metrics, plots)

mas.yaml                 <- team topology, workflow, transport
    +-- agents/*.yaml    <- design pattern, tools, skills, observability
          +-- tools/*.tool.yaml

lab-config.yaml   <- lab folder metadata (local libraries, plugins)
config.yaml       <- project defaults (flavour, infra_refs, .env path)
Layer Manifest kinds Reference
Agent Agent agent.md · governance.md · checkpoint.md · subagents.md
Agent internals (fields, not kinds) spec.models[].reasoning, spec.assembler, spec.context_manager, plugin slots llm-reasoning.md · context-assembly.md · summarization.md · plugin-bindings.md
Tools Tool, ToolBundle; runtime-owned system tools tool.md · system-tools.md
MAS MAS, Workflow mas.md
Override Overlay overlay.md
Environment Flavour; infra kinds (InfraBundle, LLMProxy, InfraMiddleware, …) flavour.md · infra.md · llm-cache.md
Engine tuning RuntimeEngine runtime-engine.md · execution.md (removed agent spec.execution)
Model data LLM model catalog (shipped data file, not a kind) llm-model-catalog.md
Experiment experiment: root experiment.md
Inputs Dataset (apiVersion: lab/v1) dataset.md · dataset-migration.md
Processing pipeline: root / kind: Pipeline pipeline.md
Lab folder lab: root (lab-config.yaml) lab.md

The runtime manifests (Agent, MAS, overlays, infra) are documented under runtime.md. Failure handling is in reliability.md. To reference one manifest from another (paths, LIBRARY: prefixes, versions, file names), see writing-manifests.md.

Resolution: ref vs id

Form Example Meaning
File path ref: ./agents/broker.yaml Relative to the referring manifest.
Catalog name dataset.name: trip-planner-benchmark Resolved under the lab or library.
Library ref standard:openai Bundled infra from library-standard.
CLI override --infra-ref, -o overlay.yaml, --override One-shot for mas-ctl / mas-lab (overrides).

Schema files

The YAML schemas live under docs/schemas/ (overview: schemas.md). The bench UI and the validators compile them at runtime. mas-ctl validate checks any kind. mas-lab validate checks experiment, pipeline, lab config, and Dataset files.

Area Schema directory
Lab (experiment, dataset, pipeline) docs/schemas/lab/
Runtime (agent, mas, overlay, infra) docs/schemas/runtime/
Workspace config.schema.yaml

Application binding (tutorials vs paper labs)

An experiment names the MAS under test in experiment.application. The plural applications: form is deprecated. It is still accepted while you migrate.

Style Example When to use
Inline manifest application: {manifest: ./mas.yaml, configs_dir: ./overlays} Tutorials, self-contained experiments
Registered app application: {app: trip-planner, configs_dir: ./overlays} Paper labs, shared apps under library-samples/apps/

Scenarios reference overlay ids from configs_dir (tutorial cot, lab pattern-cot). Point the dataset at a file with path: ./dataset.yaml (tutorial), or at a catalogued benchmark with name plus locator: samples.

For workflow overlays versus routing overlays, see Topology, workflow, and routing.

See also