microsoft/amplifier-bundle-routing-matrix

microsoft/amplifier-bundle-routing-matrix

Description: Routing Matrix bundle for the Amplifier project

Language: Python

License: MIT

Stars: 2

Forks: 9

Open issues: 5

Created: 2026-02-28T22:25:15Z

Pushed: 2026-06-13T06:56:45Z

Default branch: main

Fork: no

Archived: no

README:

Routing Matrix Bundle

Curated model routing matrices for Amplifier. Maps semantic roles (like coding, reasoning, fast) to ranked lists of provider/model candidates, so agents request *what kind* of model they need rather than hardcoding a specific one.

The routing hook tries candidates top-to-bottom and uses the first that matches an installed provider.

Matrices

Eight curated matrices ship with this bundle:

| Matrix | When to use | |--------|-------------| | balanced (default) | Mixed workloads. Good quality/cost tradeoff for everyday development. | | quality | Maximum capability. Uses the strongest models for every role, regardless of cost. | | economy | Cost-optimized. Prefers free tiers, smaller models, and local providers like Ollama. | | anthropic | Anthropic Claude models exclusively. | | openai | OpenAI models exclusively. | | gemini | Google Gemini models exclusively. | | copilot | GitHub Copilot-optimized. Balances multiplier costs, avoids the 30x fast-variant trap. | | ollama | Ollama across two instances: ollama (local) + ollama-cloud (Ollama Cloud). Routes heavy roles to gpt-oss:120b on cloud; local fallbacks. Requires both provider instances configured — see provider README. |

Browse the matrix files directly in the [routing/](routing/) directory.

Including the Bundle

Foundation already includes this bundle — no extra configuration needed if you use Foundation.

To include it in a custom bundle:

includes:
- routing-matrix:behaviors/routing.yaml

How Agents Use model_role

Agents declare what kind of model they need via the model_role frontmatter field. The routing hook resolves this to a concrete provider/model at session start.

String shorthand — request a single role:

meta:
name: my-agent
description: "..."
model_role: coding

List form with fallbacks — try roles in order:

meta:
name: my-agent
description: "..."
model_role: [vision, coding, general]

The system tries vision first. If no installed provider matches any candidate for that role, it falls back to coding, then general.

Available Roles

| Role | Description | |------|-------------| | general | Versatile catch-all, no specialization needed | | fast | Quick parsing, classification, file ops, bulk work | | coding | Code generation, implementation, debugging | | ui-coding | Frontend/UI code — components, layouts, styling, spatial reasoning | | security-audit | Vulnerability assessment, attack surface analysis, code auditing | | reasoning | Deep architectural reasoning, system design, complex multi-step analysis | | critique | Analytical evaluation — finding flaws in existing work | | creative | Design direction, aesthetic judgment, high-quality creative output | | writing | Long-form content — documentation, marketing, case studies, storytelling | | research | Deep investigation, information synthesis across multiple sources | | vision | Understanding visual input — screenshots, diagrams, UI mockups | | image-gen | Image generation, visual mockup creation, visual ideation | | critical-ops | High-reliability operational tasks — infrastructure, orchestration |

Every matrix must define at least general and fast. All other roles are optional — agents fall back through their model_role list if a role isn't defined.

How model_role and provider_preferences interact (matrix strategy)

> The behavior documented in this section is matrix-strategy policy. Alternative routing-strategy bundles that register the model_role_resolver capability MAY choose different semantics.

amplifier-foundation agents/skills/recipes typically declare both model_role: and provider_preferences: in their frontmatter. This is by design, not redundant:

• `provider_preferences:` is the bundle-portable, always-works fallback. It functions for every AmplifierSession regardless of which bundles are installed — including sessions that don't include any routing bundle at all.
• `model_role:` is the opt-in enhancement that activates only when a routing bundle (such as this one) is installed. It tells the routing bundle which semantic role to resolve against the active matrix.

What this bundle does when both fields are declared

When this bundle's hooks-routing is mounted, its session:start hook reads each agent's model_role:. For every agent that declares one, the hook resolves it against the active matrix and overwrites agent_cfg["provider_preferences"] with the matrix-resolved candidates. The hard-pinned frontmatter provider_preferences: is replaced at runtime.

When this bundle is NOT mounted (the session has no routing bundle), the hook never runs, and frontmatter provider_preferences: flows through unchanged. The agent operates on its hard-pinned fallback.

The net effect:

| Configuration | Routing bundle installed | Routing bundle NOT installed | |---|---|---| | model_role: + provider_preferences: (typical foundation agent) | Matrix resolves model_role → preferences | Frontmatter provider_preferences flows through | | model_role: only | Matrix resolves model_role → preferences | Agent gets parent's mount-plan defaults (no per-agent override) | | provider_preferences: only (rare; only when matrix resolution is undesirable) | Frontmatter flows through (no override) | Frontmatter flows through |

Author guidance

Declare both. That's the supported and recommended pattern. Authors get:

• Per-agent provider preferences that work in any bundle composition (provider_preferences:)
• Smart matrix resolution that activates automatically when a routing bundle is loaded (model_role:)

Per-delegate model_role overrides (e.g. delegate(agent="...", model_role="research")) take precedence over BOTH the agent's frontmatter and the matrix-resolved agent-config preferences. That precedence is the spawner's policy, not this bundle's — see...