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/ 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 amplifier-app-cli/docs/SPAWN_PRECEDENCE.md.

Selecting a Matrix

Via CLI command:

amplifier routing use balanced   # or: quality, economy
amplifier routing list           # show available matrices
amplifier routing show           # show resolved roles for current matrix

Via settings.yaml:

# ~/.amplifier/settings.yaml (global) or .amplifier/settings.yaml (project)
routing:
  matrix: quality

Overriding Specific Roles

Users can override individual role assignments without replacing the entire matrix. Use the base keyword in settings.yaml to reference the active matrix and selectively replace roles:

# ~/.amplifier/settings.yaml
routing:
  matrix: balanced
  overrides:
    coding:
      - provider: ollama
        model: codellama:70b
    fast:
      - provider: ollama
        model: llama3:8b
      - base  # fall back to the matrix's "fast" candidates after Ollama

With base in the list, the matrix's original candidates for that role are appended after your overrides. Without base, your override completely replaces the matrix's candidates.

Creating a Custom Matrix

Create a YAML file following this schema:

name: my-matrix
description: "Short description of this matrix's philosophy."
updated: "2026-02-28"

roles:
  general:                          # REQUIRED
    description: "Balanced catch-all"
    candidates:
      - provider: anthropic         # Module type name (not "provider-anthropic")
        model: claude-sonnet-4-6    # Exact model name
      - provider: ollama
        model: "*"                  # Glob: any model from this provider

  fast:                             # REQUIRED
    description: "Quick utility work"
    candidates:
      - provider: openai
        model: gpt-5-mini

  coding:                           # Optional
    description: "Code generation"
    candidates:
      - provider: anthropic
        model: claude-sonnet-4-6
        config:                     # Optional: passed to provider session config
          reasoning_effort: high

Schema Reference

Top-level fields:

Field	Required	Description
name	Yes	Matrix identifier
description	Yes	Human-readable description
updated	Yes	Last update date (YYYY-MM-DD)
roles	Yes	Map of role name to role definition

Role definition:

Field	Required	Description
description	Yes	What this role is for
candidates	Yes	Ordered list of provider/model candidates

Candidate fields:

Field	Required	Description
provider	Yes	Module type name (e.g., anthropic, openai, ollama)
model	Yes	Exact model name or glob pattern (e.g., claude-sonnet-*, *)
config	No	Model parameters passed to provider (e.g., reasoning_effort: high)

Place custom matrix files in routing/ within this bundle, or reference them from your own bundle.

See docs/MATRIX_CURATOR_GUIDE.md for detailed authoring guidance.

Contributing

Note

This project is not currently accepting external contributions, but we're actively working toward opening this up. We value community input and look forward to collaborating in the future. For now, feel free to fork and experiment!

Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit Contributor License Agreements.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.