Route requests between model tiers

Overview

ModelRouter implements ModelProvider and selects from configured tiers. It uses explicit rules first, then a local complexity heuristic. It does not measure model capability, compare prices, or guarantee savings. Choose tier models with evaluation data for your application.

Quick Start

This factory accepts two configured providers. It constructs an Agent without making a request; the caller owns running and closing that Agent.

import { Agent, ModelRouter, type ModelProvider } from "@agentium/core";

export function createRoutedAssistant(fast: ModelProvider, capable: ModelProvider) {
  const router = new ModelRouter({
    tiers: [
      { model: fast, maxComplexity: 0.3 },
      { model: capable, maxComplexity: 1.0 },
    ],
    outcomeTracking: true,
  });
  const agent = new Agent({
    name: "routed-assistant", model: router, register: false,
    instructions: "Answer from the provided evidence. Ask when details are missing.",
  });
  return { agent, router };
}

Configure provider credentials and models using the integration directory. A reasonable experiment starts with gpt-6-luna for the fast tier and gpt-6.1-sol for the capable tier, then measures both with the same quality cases.

Built-in Complexity Classifier

The v4 classifier inspects the last user message, conversation depth, tools, and response format. Signals include text length, code markers, reasoning keywords, complex instructions, tool count, and structured output. It makes no model call. These signals estimate prompt shape, not whether the answer will be correct. Tiers are sorted by maxComplexity; the first threshold containing the score wins. If none matches, fallbackTier selects the tier, defaulting to the final sorted tier. Keep thresholds increasing and rule indices aligned with that order. The exported configuration type includes classifier, but the v4 implementation always calls the built-in heuristic. Do not expect supplying a provider in that field to invoke an alternate classifier.

Custom Routing Rules

Rules run in order before heuristic routing. This host factory sends requests with more than five tools to the second tier.

import { ModelRouter, type ModelProvider } from "@agentium/core";

export function createToolAwareRouter(fast: ModelProvider, capable: ModelProvider) {
  return new ModelRouter({
    tiers: [
      { model: fast, maxComplexity: 0.3 },
      { model: capable, maxComplexity: 1 },
    ],
    rules: [{ condition: (_messages, options) => (options?.tools?.length ?? 0) > 5, tier: 1 }],
    outcomeTracking: true,
  });
}

Test requests on both sides of the rule and inspect your provider instrumentation. Model selection can change latency, output shape, tool support, and cost; all selected providers must support the request you send them.

Outcome Tracking

Call router.getOutcomeStats() after requests. Each entry has tierIndex, total, successes, and rate. The bounded history records whether provider execution succeeded. A successful call is not a quality score; use eval scorers for answer correctness.

Events

The v4 router does not emit a model.routed EventBus event. Use outcome statistics and provider-level instrumentation for visibility. See observability for the surrounding run and tool lifecycle.

Handle provider failures

Routing selects a provider; it does not automatically retry another tier after failure. Wrap eligible providers with fallback when the application’s failure policy allows it. Compare this composition in the model patterns.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Route requests between model tiers

Overview

Quick Start

Built-in Complexity Classifier

Custom Routing Rules

Outcome Tracking

Events

Handle provider failures

​Overview

​Quick Start

​Built-in Complexity Classifier

​Custom Routing Rules

​Outcome Tracking

​Events

​Handle provider failures

Overview

Quick Start

Built-in Complexity Classifier

Custom Routing Rules

Outcome Tracking

Events

Handle provider failures