モデル Provider

Mastra は複数の Provider の LLM を扱う統一 interface を提供し、単一の API から 168 Provider、5458 モデルを利用できます。

機能

• すべてのモデルに 1 つの API: Provider ごとの依存関係を追加でインストール、管理せずに、任意のモデルを利用できます。

• 最新の AI をすぐに利用: Provider を問わず、新しいモデルのリリース直後から利用できます。Mastra の Provider 非依存 interface により vendor lock-in を避けられます。

• モデルを組み合わせる: タスクに応じて異なるモデルを使用します。たとえば、大きな context の処理には GPT-5-mini を使い、推論タスクには Claude Opus 4.6 に切り替えます。

• モデル fallback: Provider に障害が発生した場合、Mastra は application level で別の Provider に自動切り替えできます。API Gateway と比べてレイテンシーを抑えられます。

基本的な使用方法

OpenAI、Anthropic、Google、OpenRouter などの Gateway のいずれを使う場合も、モデルを "provider/model-name" 形式で指定すれば、残りは Mastra が処理します。

Mastra は対応する環境変数（例: ANTHROPIC_API_KEY）を読み取り、リクエストを Provider に routing します。API key がない場合は、設定すべき変数を示す明確な runtime error が発生します。

OpenAI

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "openai/gpt-5.6-sol"
})

Anthropic

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "anthropic/claude-sonnet-4-6"
})

Google Gemini

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "google/gemini-2.5-flash"
})

xAI

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "xai/grok-4.3"
})

OpenRouter

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: "openrouter/anthropic/claude-haiku-4.5"
})

モデル directory

左側の navigation または以下の一覧から、利用可能なモデルを探せます。

Gateway

OpenRouter

Netlify

Vercel

+ 3 more

Provider

OpenAI

Anthropic

Google

+ 159 more

エディターから直接モデルを探すこともできます。Mastra は model フィールドの完全な自動補完に対応しており、入力を始めると IDE に選択肢が表示されます。

また、Studio UI でモデルを探して試すこともできます。

情報

開発環境では、ローカルのモデル一覧が 1 時間ごとに自動更新され、TypeScript の自動補完と Studio が最新のモデルに保たれます。無効にするには MASTRA_AUTO_REFRESH_PROVIDERS=false を設定します。本番環境ではデフォルトで無効です。

モデルを組み合わせる

高速だが機能が限られるモデルもあれば、より大きな context window や強力な推論能力を持つモデルもあります。タスクに合わせて、同じ Provider の異なるモデルを使うか、複数の Provider のモデルを組み合わせます。

src/mastra/agents/reasoning-agent.ts

import { Agent } from "@mastra/core/agent";

// Use a cost-effective model for document processing
const documentProcessor = new Agent({
  id: "document-processor",
  name: "Document Processor",
  instructions: "Extract and summarize key information from documents",
  model: "openai/gpt-5.6-sol"
})

// Use a powerful reasoning model for complex analysis
const reasoningAgent = new Agent({
  id: "reasoning-agent",
  name: "Reasoning Agent",
  instructions: "Analyze data and provide strategic recommendations",
  model: "anthropic/claude-opus-4-7"
})

動的なモデル選択

モデルは単なる文字列なので、request context、変数、その他のロジックに基づいて動的に選択できます。

src/mastra/agents/dynamic-assistant-agent.ts

const agent = new Agent({
  id: "dynamic-assistant",
  name: "Dynamic Assistant",
  model: ({ requestContext }) => {
    const provider = requestContext.get("provider-id");
    const model = requestContext.get("model-id");
    return `${provider}/${model}`;
  },
});

これにより、次のパターンを実装できます。

• A/B test - 本番環境でモデルの性能を比較する
• ユーザーが選べるモデル - application でユーザーが好みのモデルを選択できるようにする
• multi-tenant application - 顧客ごとに独自の API key とモデル設定を使用する

Provider 固有の option

モデル Provider ごとに固有の設定 option があります。OpenAI では reasoningEffort、Anthropic では cacheControl などを調整できます。Mastra では、これらの providerOptions を Agent level または message ごとに設定できます。

src/mastra/agents/planner-agent.ts

// Agent level (apply to all future messages)
const planner = new Agent({
  id: "planner",
  name: "Planner",
  instructions: {
    role: "system",
    content: "You are a helpful assistant.",
    providerOptions: {
      openai: { reasoningEffort: "low" }
    }
  },
  model: "openai/gpt-5.6-sol",
});

const lowEffort =
  await planner.generate("Plan a simple 3 item dinner menu");

// Message level (apply only to this message)
const highEffort = await planner.generate([
  {
    role: "user",
    content: "Plan a simple 3 item dinner menu for a celiac",
    providerOptions: {
      openai: { reasoningEffort: "high" }
    }
  }
]);

カスタム header

organization ID やその他の Provider 固有フィールドなど、カスタム header を指定する場合は次の構文を使用します。

src/mastra/agents/custom-agent.ts

const agent = new Agent({
  id: "custom-agent",
  name: "Custom Agent",
  model: {
    id: "openai/gpt-5.6-sol",
    apiKey: process.env.OPENAI_API_KEY,
    headers: {
      "OpenAI-Organization": "org-abc123"
    }
  }
});

情報

設定は Provider によって異なります。カスタム header の詳細は、左側の navigation から各 Provider のページを参照してください。

モデル fallback

単一モデルへの依存は application の単一障害点になります。モデル fallback は、モデルと Provider の間で自動 failover を行います。primary model が利用できなくなると、成功するまで設定済みの次の fallback にリクエストを再試行します。

src/mastra/agents/resilient-assistant-agent.ts

import { Agent } from '@mastra/core/agent';

const agent = new Agent({
  id: 'resilient-assistant',
  name: 'Resilient Assistant',
  instructions: 'You are a helpful assistant.',
  model: [
    {
      model: "openai/gpt-5.6-sol",
      maxRetries: 3,
    },
    {
      model: "anthropic/claude-sonnet-4-6",
      maxRetries: 2,
    },
    {
      model: "google/gemini-2.5-pro",
      maxRetries: 2,
    },
  ],
});

Mastra は最初に primary model を試します。500 error、rate limit、timeout が発生すると、最初の fallback に自動で切り替えます。それも失敗した場合は次へ進みます。各モデルは、次へ進む前に個別の回数で再試行されます。

ユーザーが切り替えを意識することはありません。別のモデルから同じ形式のレスポンスが返ります。fallback chain を進む間も error context が保持されるため、streaming との互換性を維持しながらエラーを適切に伝播できます。

モデルごとの設定

各 fallback entry には独自の modelSettings、providerOptions、headers を指定できます。chain 内のモデルで、同等の出力を得るために異なる temperature や Provider 固有設定が必要な場合に便利です。

src/mastra/agents/tuned-resilient-agent.ts

import { Agent } from '@mastra/core/agent';

const agent = new Agent({
  id: 'tuned-resilient',
  name: 'Tuned Resilient Agent',
  instructions: 'You are a helpful assistant.',
  model: [
    {
      model: 'google/gemini-2.5-flash',
      maxRetries: 2,
      modelSettings: { temperature: 0.3 },
      providerOptions: { google: { thinkingConfig: { thinkingBudget: 0 } } },
    },
    {
      model: 'openai/gpt-5-mini',
      maxRetries: 2,
      modelSettings: { temperature: 0.7 },
      providerOptions: { openai: { reasoningEffort: 'low' } },
    },
  ],
});

優先順位:

• modelSettings と providerOptions: fallback entry ごとの設定が呼び出し時の option より優先され、呼び出し時の option は Agent の defaultOptions より優先されます。modelSettings は key ごとに shallow merge されます。providerOptions は再帰的に deep merge されるため、入れ子の Provider 設定（例: google.thinkingConfig）では layer 間で隣接 key が保持されます。
• headers: 呼び出し時の modelSettings.headers、fallback entry ごとの headers、モデルルーターのモデルから抽出された header の順に優先されます。runtime header（Trace、認証、tenancy）は意図的にモデル level の header より優先されます。

各フィールドには、動的モデルの解決方法と同様に requestContext の function も指定できます。

Mastra でローカルモデルを使用する

Mastra は、gpt-oss、Qwen3、DeepSeek など、自分の hardware で実行する多くのローカルモデルにも対応しています。ローカルモデルを実行する application は、Mastra が接続できる OpenAI 互換 API server を提供する必要があります。LMStudio の使用を推奨します（LMStudio server の実行を参照）。

カスタム OpenAI 互換 endpoint では、id は Mastra がモデルルーターに渡す routing 形式です。

remote が直接接続する Provider として動作し、llama3.2 のような単純なモデル名を受け取る場合は、provider/model を使用します。

remote がモデル Gateway として動作し、upstream のモデル namespace に Provider が含まれる場合は、mastra/google/gemini-2.5-flash や openrouter/google/gemini-2.5-flash のように gateway/provider/model を使用します。

url には個別の chat endpoint ではなく、Mastra の model 設定とともに OpenAI 互換 endpoint の base URL を使用することが重要です。

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: {
    id: "custom/my-qwen3-model",
    url: "http://your-custom-openai-compatible-endpoint.com/v1"
  }
})

remote がモデル Gateway として動作する場合は、id に Gateway prefix を含めます。

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: {
    id: "mastra/google/gemini-2.5-flash",
    url: "http://your-custom-openai-compatible-endpoint.com/v1"
  }
})

例: LMStudio

LMStudio server を起動すると、ローカル server は http://localhost:1234 で利用でき、/v1/models、/v1/chat/completions などの endpoint を提供します。url は http://localhost:1234/v1 です。id には、LMStudio interface に表示される lmstudio/${modelId} を使用できます。

src/mastra/agents/my-agent.ts

import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  instructions: "You are a helpful assistant",
  model: {
    id: "lmstudio/qwen/qwen3-30b-a3b-2507",
    url: "http://localhost:1234/v1"
  }
})

Mastra で AI SDK を使用する

Mastra は、直接使用する場合のために AI SDK Provider module に対応しています。

src/mastra/agents/my-agent.ts

import { groq } from '@ai-sdk/groq';
import { Agent } from "@mastra/core/agent";

const agent = new Agent({
  id: "my-agent",
  name: "My Agent",
  model: groq('gemma2-9b-it')
})

AI SDK モデル（例: groq('gemma2-9b-it')）は、モデルルーターの fallback や scorer など、"provider/model" 文字列を受け取る任意の場所で使用できます。