Model Resolution

The Model Resolution Matrix picks the LLM model for each composition node at invocation time. It replaces hardcoded model assignments with a declarative rule table that selects based on multiple dimensions — agent identity, active skill, project, and phase — using a "most dimensions matched wins" algorithm.

Why a matrix?

Different nodes in a composition benefit from different models. A researcher node needs broad reasoning; an editor node needs precision; a security reviewer needs a model tuned for code analysis. Hardcoding a model per agent definition is inflexible. Hardcoding a model per workflow phase is worse — it means every phase-change requires editing a map in platform code.

The Matrix externalizes this decision. Org admins configure rules; the runtime resolves them per invocation. No platform code changes needed.

ModelResolutionRule

A rule is a pair: a selector (which invocations it matches) and a target (which model to use):

1interface ModelResolutionRule {
2  id: string;
3  selector: ModelMatrixSelector;
4  target: ModelRef;
5  priority?: number;           // tiebreaker; higher wins; defaults to 0
6}
7
8interface ModelMatrixSelector {
9  agent?: string;             // agent slug (exact match)
10  skill?: string;             // active skill slug (exact match)
11  project?: string;           // project ID
12  phase?: string;             // workflow phase key
13  // extra dimensions are carried in a free-form map:
14  extra?: Record<string, string>;
15}

Matching rule: among rules whose every selector dimension matches the invocation context, the rule that matches the most dimensions wins. Ties are broken by priority (higher wins). If no rule matches, the DEFAULT rule applies.

The DEFAULT rule

Every org must have exactly one DEFAULT rule — a rule with an empty selector that matches every invocation. It is the fallback model for the org:

1{
2  "id": "default",
3  "selector": {},
4  "target": "gpt-4o",
5  "priority": 0
6}

The platform seeds this rule when the org is created. Update it via Org Settings → Model Matrix → Default Model.

Resolution dimensions

All four dimensions are optional per rule. A rule with only agent: "security-reviewer" matches any invocation using that agent, regardless of project, phase, or active skill.

Most dimensions wins means a rule with { agent: "reviewer", skill: "security-review" } beats a rule with only { agent: "reviewer" } for an invocation where both apply — even if the second rule has a higher priority.

Example matrix

1[
2  {
3    "id": "default",
4    "selector": {},
5    "target": "gpt-4o",
6    "priority": 0
7  },
8  {
9    "id": "security-work",
10    "selector": { "skill": "security-review" },
11    "target": "claude-3-5-sonnet",
12    "priority": 1
13  },
14  {
15    "id": "fast-tasks",
16    "selector": { "phase": "triage" },
17    "target": "gpt-4o-mini",
18    "priority": 1
19  },
20  {
21    "id": "security-triage",
22    "selector": { "skill": "security-review", "phase": "triage" },
23    "target": "claude-3-5-sonnet",
24    "priority": 2
25  }
26]

Given an invocation with skill=security-review, phase=triage:

1. security-triage matches 2 dimensions → wins.
2. security-work matches 1 dimension → would be second.
3. fast-tasks matches 1 dimension → tied with security-work; broken by priority (both 1) then id (lexicographic fallback).
4. default matches 0 dimensions → last resort.

Per-invocation override

A run-time override sits above all rules. Pass modelOverride at the composition node level or via the session API.

Overrides are audited and visible in the run record. They do not modify the Matrix.

Debugging resolution

The Agent Studio run debugger shows which rule was applied to a specific invocation (a run and a node). It shows:

• The invocation context (agent, skill, project, phase).
• All matching rules and their dimension counts.
• The winning rule and the resolved model.
• The ResolvedModelDecision record (also visible in the Agent Studio run debugger).

Previous: ← Concepts