Model selection and fallback patterns

Use this page when a working application needs a model change or fallback strategy. Use the provider setup directory for installation, credentials, and deployment configuration. Current documentation defaults are recorded in Example models.

Compare models on the same application task

Host function: pass separately configured providers. Each iteration owns a fresh Agent so conversation or opaque provider continuation state is not carried between candidates. Live candidates require credentials and incur their own requests.

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

export async function compareDrafts(models: ModelProvider[], input: string) {
  const results: { model: string; text: string; totalTokens: number }[] = [];
  for (const model of models) {
    const agent = new Agent({
      name: "support-comparison", model, register: false,
      instructions: "Write a concise answer. Use only facts supplied in the input.",
    });
    try {
      const result = await agent.run(input);
      if (result.status !== "completed") throw new Error(`${model.modelId}: ${result.status}`);
      results.push({
        model: `${model.providerId}:${model.modelId}`,
        text: result.text,
        totalTokens: result.usage.totalTokens,
      });
    } finally {
      await agent.close();
    }
  }
  return results;
}

Run the same representative inputs through each candidate, then score correctness before optimizing latency or price. A single attractive answer is not a regression suite. Reuse the evaluation pattern or quality-gate project for repeatable comparisons. This comparison stops at the first unsuccessful run. A benchmarking host that continues should retain the failure as a result, not discard it and report only successful candidates.

Add an explicit fallback chain

Host factory: pass configured providers in preference order. The caller owns the returned Agent and closes it after its runs. Every fallback candidate needs the tools, modalities, and output contract required by the application.

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

export function createResilientAssistant(primary: ModelProvider, backup: ModelProvider) {
  const model = withFallback([primary, backup], {
    onFallback: (from, to, error) => {
      console.warn("Model fallback", { from, to, reason: error instanceof Error ? error.message : String(error) });
    },
  });
  return new Agent({
    name: "resilient-support", model, register: false,
    instructions: "Answer from the supplied facts; acknowledge missing information.",
  });
}

The fallback contract classifies failures and tracks each provider’s circuit. Test an unavailable primary and verify the callback identifies the backup. A committed stream cannot be silently restarted: once any public chunk has been emitted, a later failure propagates instead of concatenating output from another provider. Provider fallback does not undo earlier tool effects. Do not replay provider-specific signed reasoning or continuation state into an incompatible provider; test the actual multi-turn/tool path you will deploy.

Route deliberately

Choose a provider before a new run when the host already knows the task type. Use ModelRouter when its routing rules fit the application. Measure answer quality and actual costs for each route; heuristics cannot establish that the cheapest tier is sufficient for every request. When changing providers, verify:

Contract	What can differ
Tool execution	Endpoint, tool-call arguments, and continuation metadata
Structured output	Supported schema features and validation behavior
Reasoning	Supported effort values, adaptive thinking, and summary fields
Input/output	Vision, audio, context limits, and streaming chunks
Hosting	Direct API model IDs versus cloud deployment/profile IDs
Accounting	Reported token fields and your model-keyed pricing table

See reasoning, model types, and the individual integration guide for exact behavior. A shared ModelProvider interface does not make provider capabilities identical.

More patterns

Use provider setup for OpenAI, Anthropic, Gemini, cloud deployments, local models, and compatible gateways. Use custom providers for a host adapter or deterministic fixture, Jev examples for typed decisions, and cost patterns when refreshing prices alongside a model change.

Complete projects

Agents & memory

Models & Jev

Tools & knowledge

Teams & jobs

Deploy & devices

Quality & production

Model selection and fallback patterns

Compare models on the same application task

Add an explicit fallback chain

Route deliberately

More patterns

​Compare models on the same application task

​Add an explicit fallback chain

​Route deliberately

​More patterns

Compare models on the same application task

Add an explicit fallback chain

Route deliberately

More patterns