Amplifier Feature

Right-Sizing the Swarm

Per-agent model routing in Amplifier

microsoft/amplifier-bundle-routing-matrix · Shipped · v0.1.1

The Setup

A swarm of agents is leverage — until every one runs the parent's frontier model

Amplifier delegates work to specialized foundation agents — file readers, git operators, deep-reasoning architects. That delegation is the whole point. But when an agent has no model preference of its own, it inherits whatever model the parent session used — a bill nobody chose.

So the question is: does a file reader really need the frontier model?

file-opsreads / writes / edits / searches files

git-opsgit & GitHub operations

shell-execruns shell commands

zen-architectdeep design & reasoning

security-guardiansecurity audit & critique

Proof It's Real

The routing hook is shipped, compact, and covered by a passing test suite

This isn't a proposal. The hooks-routing module is ~816 lines across four files, its full suite of 270 tests passes in 0.46s, and it ships by default in Amplifier Foundation — no extra configuration needed.

Now let's see the default it replaces.

816

lines across 4 files

270

tests passing

0.46s

full-suite runtime

v0.1.1

in Foundation by default

The Old Default

With no routing bundle, the mount plan comes back unchanged

Amplifier's apply_provider_preferences returns the parent's mount plan unchanged when an agent sets no preferences. Per the README's matrix-strategy table, that agent simply gets the parent's mount-plan defaults — so a git-ops formatter runs on whatever frontier model the parent used.

The fix starts with a shared vocabulary.

# spawn_utils.apply_provider_preferences
if not preferences:
    return mount_plan   # unchanged

# README matrix-strategy table:
# model_role only, no routing bundle
# -> agent gets parent's
#    mount-plan defaults

The Vocabulary

Agents declare a semantic role, not a hardcoded model name

The routing-matrix bundle defines 13 semantic model roles — general, fast, coding, reasoning, and more. Only general and fast are required; every other role is an optional fallback. Roles are resolved through one of 8 curated matrices.

A hook turns those declarations into real models.

13

semantic model roles

8

curated matrices

2

required roles: general + fast

How It Works

A session:start hook resolves the role and overwrites provider_preferences

When the routing bundle is mounted, the session:start hook reads each agent's model_role, resolves it against the active matrix, and overwrites that agent's provider_preferences with the matrix's ranked candidates — at runtime, per agent.

But how does it pick from those ranked candidates?

1Read each agent's declared model_role

2Resolve the role against the active matrix

3Overwrite agent_cfg['provider_preferences'] with the resolved candidates

Why It's Portable

First-match, top-to-bottom — skipping providers you don't have installed

Resolution walks the matrix's ranked candidates top-to-bottom and takes the first that matches an installed provider, skipping any provider that isn't present. The same role declaration works across whatever providers you actually have.

Put it together and the swarm right-sizes itself.

↓Try candidate 1 — provider installed? take it

↓Not installed? skip to the next candidate

✓First installed match wins (limit=1 by default)

The Payoff

One session — utility agents on cheap tiers, reasoning agents on Opus

file-ops and git-ops declare model_role: fast, so they resolve to cheap Haiku / mini-class tiers. zen-architect declares reasoning, whose first candidate is claude-opus with high reasoning effort. Same session — each agent lands on the tier it actually needs.

The pattern that makes this repeatable:

file-opsfast → Haiku / mini

git-opsfast → Haiku / mini

shell-execfast → cheap tier

zen-architectreasoning → Opus (high)

security-guardiansecurity-audit, critique

The Takeaway

Declare intent, not models — and let the matrix hold the cost lever

One semantic role per agent means the matrix owns the cost decision. The copilot matrix documents it plainly: it avoids the 30x claude-opus-fast trap and uses Haiku (0.33x) for budget roles — GitHub Copilot request-multiplier figures noted in the matrix itself.

Change the matrix, not the agents — and pick with amplifier routing use.

Budget role, fast variant30x multiplier (the trap)

Budget role, Haiku0.33x multiplier

Switch matricesamplifier routing use <name>

Override one rolekeep the rest via base

Sources

Research Methodology

Shipped · in production

Feature: Per-agent model routing via microsoft/amplifier-bundle-routing-matrix (upstream); ramparte fork as local origin. Module amplifier_module_hooks_routing v0.1.1.

Timeline: Initial bundle 2026-02-28 (Brian Krabach, commit 0741a1d) → v0.1.1 parallelized resolution 2026-05-18 (#26) → skip list_models() for parent-resolved providers 2026-06-13 (#28) → latest commit 2026-07-16 (limit=N pool resolution, Sam Schillace, b559b10).

Primary contributors: Ken Chau (105 commits), Brian Krabach (45, authored initial bundle).

Research performed (git / gh / grep / wc / pytest):

ls routing/*.yaml | wc -l — 8 curated matrices
grep -cE '^ [a-z-]+:$' routing/balanced.yaml + routing-instructions.md — 13 roles; required = general, fast
grep -n 'model_role' amplifier-foundation/agents/{file-ops,git-ops,shell-exec,zen-architect,security-guardian}.md
sed -n '357,406p' spawn_utils.py — apply_provider_preferences returns mount plan unchanged when preferences empty
sed -n '133,205p' modules/hooks-routing/.../__init__.py — on_session_start overwrites provider_preferences
sed -n '169,277p' resolver.py — top-to-bottom first-match, skips uninstalled providers (limit=1 default)
wc -l modules/hooks-routing/.../*.py — 816 total lines across 4 files
.venv/bin/python -m pytest tests/ -q — 270 passed in 0.46s
sed -n '1,14p' routing/copilot.yaml — avoids 30x fast-variant trap, uses Haiku (0.33x)
git shortlog -sn --all — contributor commit counts

Gaps & caveats: The 30x / 0.33x figures are GitHub Copilot request-multiplier values documented in copilot.yaml, not a measured end-to-end cost/speed benchmark. No numeric latency/speedup artifact exists in the repo; the "faster" story rests qualitatively on cheap-tier utility routing plus two perf commits (v0.1.1 parallelization; skip list_models()). Contributor counts are from the local ramparte fork clone.