Chapter 3 · Model Routing

Chapter goals: Understand the design philosophy behind Mastra's unified model interface, configure multiple providers, and switch models freely across projects.

3.1 Why Model Routing Exists

Different LLM providers have different SDK interfaces: OpenAI uses chat.completions.create, Anthropic uses messages.create — parameter names, error structures, and streaming formats all differ. If you depend directly on one vendor's SDK, switching models requires rewriting the call layer.

Mastra's Model Routing provides a unified abstraction:

• A single string "provider/model" expresses "which provider's which model";
• 40+ providers share the same call/stream/tool-calling protocol;
• Switching models = changing one string, zero business code changes.

Common model IDs (full list at mastra.ai/models):

openai/gpt-5.6-sol          anthropic/claude-opus-4-7
openai/gpt-5-mini           anthropic/claude-sonnet-4-6
google/gemini-2.5-flash     anthropic/claude-haiku-4-5

3.2 Configuring Provider Keys

Each provider only needs its corresponding environment variable — no extra SDK installation required:

# .env —— configure as needed; multiple providers can coexist
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_GENERATIVE_AI_API_KEY=...

// Agents reference strings directly; Mastra auto-resolves the provider prefix
import { Agent } from '@mastra/core/agent';

export const writerAgent = new Agent({
  id: 'writer',
  name: 'Writer',
  instructions: 'You are a concise technical writer.',
  model: 'anthropic/claude-sonnet-4-6', // Auto-reads ANTHROPIC_API_KEY
});

3.3 Runtime Model Switching

The same Agent can dynamically swap its model after creation — useful for A/B testing or graceful degradation:

import { mastra } from './mastra';

const agent = mastra.getAgent('writer');

// Scenario 1: daily use with flagship model
let res = await agent.generate('Write a product slogan');
console.log(res.text);

// Scenario 2: switch to a faster, cheaper model during peak hours
agent.__updateModel?.('anthropic/claude-haiku-4-5');

res = await agent.generate('Write a product slogan');

The more common pattern is to split into multiple Agents at registration time, each bound to a model tier appropriate for its workload:

// src/mastra/index.ts —— different tasks bound to different model tiers
export const mastra = new Mastra({
  agents: {
    // Heavy reasoning tasks use the flagship model
    analyst: analystAgent,   // model: 'openai/gpt-5.6-sol'
    // High-frequency lightweight tasks use the mini tier
    summarizer: summaryAgent, // model: 'openai/gpt-5-mini'
    // Long-context archival uses a cheap wide-window model
    archiver: archiveAgent,
  },
});

3.4 Model Selection Decision Framework

Dimension	Consideration	Example
Task complexity	Complex reasoning/code → flagship; classification/summarization → mini	Customer support triage uses mini
Cost	Flagship-to-mini price gap can be 10–30×	Batch processing tasks pick the cheaper tier
Latency	Real-time user-facing conversations prioritize low latency	haiku / gpt-5-mini
Context window	Long document analysis needs a wide-window model	gemini-2.5-flash

// Dynamically select model based on runtime environment: cheap tier in dev, flagship in prod
const model =
  process.env.NODE_ENV === 'production'
    ? 'openai/gpt-5.6-sol'
    : 'openai/gpt-5-mini';

export const adaptiveAgent = new Agent({
  id: 'adaptive',
  name: 'Adaptive Agent',
  instructions: 'You are a helpful assistant.',
  model,
});

Tiered Strategy

A common production pattern is a "model tier ladder": an inexpensive model at the入口做 intent classification, simple requests answered directly, complex requests escalated to the flagship model — reducing overall cost by an order of magnitude.

3.5 Chapter Summary

• Model Routing unifies 40+ providers via a "provider/model" string; switching models requires zero code changes;
• Keys are injected via standard environment variables (OPENAI_API_KEY etc.); multiple providers can coexist;
• Assign different model tiers to different Agents based on task complexity, cost, latency, and context length;
• Production systems recommend a "model tier ladder" pattern to control overall cost.

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. In Mastra model routing, what do the two parts of model field "google/gemini-2.5-flash" represent?

2. What is the minimal change to switch an Agent from GPT to Claude?

3. Which approach best aligns with Mastra's official multi-model management recommendation?

4. For a real-time chat scenario facing end users, which factor should you prioritize when choosing a model?

🛠️ Hands-On Exercises

1. Configure both OpenAI and Anthropic keys in your project; have two Agents answer the same question using each provider's model and compare the output styles.
2. Switch your Agent's model from the flagship tier to the mini tier; compare response quality and speed in Studio.
3. Visit mastra.ai/models and find models supporting a 1M token context window — record their provider prefixes.

Next: Chapter 4 · Your First Agent