Composition All the Way Down

How 11 lines of YAML become a running agent

amplifier-foundation

A composition layer turns thin YAML bundles into running AI agents

Foundation is the layer that makes thin Amplifier bundles runnable — so no app has to hand-wire the plumbing itself. It first imported on 2025-12-09.

First, just how thin can a bundle get?

13,331

lines of Python in the library, across 63 files (HEAD 0965a34)

4

composable verbs: compose · prepare · spawn · @mention

The proof

A whole provider/agent fits in exactly 11 lines of YAML

providers/anthropic-sonnet.yaml is 11 lines and fully describes a provider/agent — name, version, description, and one provider module with its source and config.

But eleven lines can't run themselves.

# providers/anthropic-sonnet.yaml — 11 lines
bundle:
  name: provider-anthropic-sonnet
  version: 1.0.0
  description: ...
providers:
  - module: provider-anthropic
    source: git+https://github.com/
      microsoft/amplifier-module-
      provider-anthropic@main
    config:
      default_model: claude-sonnet-4-5
    raw: true

The complication

Eleven lines can't run themselves

Without a shared layer, every app re-implements the same wiring — and if heavy docs are always loaded, they poison every session's context.

So how does the shared layer do the wiring instead?

Duplicated plumbing. Every app re-implements module download and activation.
Context poisoning. "Documentation that duplicates code becomes context poisoning when it drifts." — API_REFERENCE.md

Mechanism · compose + prepare

compose() and prepare() do the wiring, once, for everyone

compose() deep-merges bundles — later overrides earlier. prepare() downloads and activates the modules a bundle references, returning a runnable PreparedBundle.

That solves duplicated plumbing. Now the docs problem.

compose()

compose(self, *others: Bundle) -> Bundle — merges configuration; later overrides earlier.

prepare()

async def prepare(...) -> PreparedBundle — downloads & activates modules into a runnable bundle.

Mechanism · @mention

@mentions keep heavy docs out of every session

The @namespace:path system pulls context in by reference. Expert agents act as context sinks — their heavy docs load ONLY when the agent is spawned, not into every session.

And the verbs don't stop there — they apply to themselves.

"Expert agents serve as context sinks — they carry heavy documentation that would bloat every session if always loaded." — AGENT_AUTHORING.md
@my-bundle:docs/FULL_GUIDE.md — heavy docs, loaded only when spawned.

The turn · spawn

spawn() applies the same verbs recursively

spawn() launches a child sub-session from a child bundle. By default (compose: bool = True) the child is composed with its parent — the verbs compose on themselves.

Which means the platform can be built the same way it runs an agent.

# amplifier_foundation/bundle/_prepared.py:433
async def spawn(
    self,
    child_bundle: Bundle,
    instruction: str,
    *,
    compose: bool = True,
    ...
) -> dict[str, Any]

The payoff

Foundation's own bundle is a bundle of bundles

bundle.md (v2.0.0) is a thin manifest whose includes: list composes 20 other bundles — 7 internal behaviors and 13 external git+https bundles. The same four verbs build the whole platform.

Composition all the way down.

2.0.0

foundation bundle version (bundle.md front matter)

20

bundles composed: 7 internal + 13 external git+https

The pattern to keep

A small composition core gives an 11-line bundle enormous leverage

A 3,809-line composition core — inside the 13,331-line library — lets an 11-line bundle become a running, self-composing agent. That leverage is the reusable pattern.

Thin at the edges, composable at the center.

11

lines of YAML to describe an agent

3,809

lines in the composition core (compose · prepare · spawn · @mentions · registry)

13,331

total library lines across 63 files

Sources

Research Methodology

Feature status: Shipped compose · prepare · spawn · @mentions all verified in current HEAD.

Repository: microsoft/amplifier-foundation (local checkout, HEAD 0965a34, 2026-04-09).

Data as of: HEAD 0965a34 — first import c1d26bf 2025-12-09; 502 commits on branch.

Commands run:

for f in providers/*.yaml; do echo "$(wc -l < "$f") $f"; done → anthropic-sonnet.yaml = 11 lines
grep -n 'def compose' amplifier_foundation/bundle/_dataclass.py → line 93
grep -n 'async def prepare' amplifier_foundation/bundle/_dataclass.py → line 240
grep -n 'async def spawn' amplifier_foundation/bundle/_prepared.py → line 433
sed -n '1,40p' amplifier_foundation/mentions/parser.py → parse_mentions / load_mentions
head -60 bundle.md ; grep -c '^\s*- bundle:' bundle.md → v2.0.0, 20 bundles (7 internal + 13 git+https)
find amplifier_foundation/ -name '*.py' | xargs wc -l | tail -1 → 13,331 lines / 63 files
wc -l _dataclass.py _prepared.py registry.py spawn_utils.py mentions/*.py → 3,809 lines (composition core)
git log --oneline | wc -l → 502 commits; git shortlog -sn --all → Brian Krabach 739 commits

Gaps: The composition-all-the-way-down phrase is the topic's framing, strongly supported (bundle.md composing 20 bundles) but not a verbatim slogan in the source. Earlier "8,645 LOC" figures were not reproducible at this HEAD and are not used.

Primary contributor: Brian Krabach (739 commits, dominant author; authored initial import).