Providers de modèles

Mastra fournit une interface unifiée pour travailler avec des LLM chez plusieurs Providers et donne accès à 5 458 modèles provenant de 168 Providers via une seule API.

Fonctionnalités

• Une API pour tous les modèles : accédez à n’importe quel modèle sans installer ni gérer de dépendances de Provider supplémentaires.

• Accès aux IA les plus récentes : utilisez les nouveaux modèles dès leur sortie, quel que soit leur Provider. Évitez l’enfermement propriétaire grâce à l’interface indépendante des Providers de Mastra.

• Combiner les modèles : utilisez des modèles différents pour des tâches différentes. Par exemple, utilisez GPT-5-mini pour traiter de grands contextes, puis Claude Opus 4.6 pour les tâches de raisonnement.

• Solutions de repli de modèle : en cas d’indisponibilité d’un Provider, Mastra peut basculer automatiquement vers un autre Provider au niveau de l’application, en limitant la latence par rapport aux passerelles API.

Utilisation de base

Que vous utilisiez OpenAI, Anthropic, Google ou une passerelle comme OpenRouter, indiquez le modèle sous la forme "provider/model-name" et Mastra s’occupe du reste.

Mastra lit la variable d’environnement correspondante (par exemple ANTHROPIC_API_KEY) et achemine les requêtes vers le Provider. Si une clé API est absente, une erreur d’exécution claire indique exactement quelle variable définir.

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"
})

Répertoire des modèles

Parcourez le répertoire des modèles disponibles avec la navigation de gauche, ou explorez-les ci-dessous.

Passerelles

OpenRouter

Netlify

Vercel

+ 3 autres

Providers

OpenAI

Anthropic

Google

+ 159 autres

Vous pouvez aussi découvrir les modèles directement dans votre éditeur. Mastra propose l’autocomplétion complète pour le champ model : commencez à saisir du texte et votre IDE affichera les options disponibles.

Vous pouvez également parcourir et tester les modèles dans l’interface Studio.

info

En développement, nous actualisons automatiquement votre liste locale de modèles chaque heure afin que l’autocomplétion TypeScript et Studio restent à jour. Pour désactiver cette fonction, définissez MASTRA_AUTO_REFRESH_PROVIDERS=false. L’actualisation automatique est désactivée par défaut en production.

Combiner les modèles

Certains modèles sont plus rapides mais moins capables, tandis que d’autres offrent des fenêtres de contexte plus larges ou de meilleures capacités de raisonnement. Utilisez différents modèles d’un même Provider, ou combinez-les entre Providers selon chaque tâche.

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"
})

Sélection dynamique des modèles

Comme les modèles ne sont que des chaînes de caractères, vous pouvez les sélectionner dynamiquement en fonction du contexte de requête, de variables ou de toute autre logique.

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}`;
  },
});

Cela permet des modèles de conception puissants :

• Tests A/B : comparez les performances des modèles en production.
• Modèles sélectionnables par l’utilisateur : laissez les utilisateurs choisir leur modèle préféré dans votre application.
• Applications multi-locataires : chaque client peut fournir ses propres clés API et préférences de modèle.

Options spécifiques aux Providers

Les différents Providers de modèles exposent leurs propres options de configuration. Avec OpenAI, vous pouvez ajuster reasoningEffort. Avec Anthropic, vous pouvez régler cacheControl. Mastra permet de définir ces providerOptions spécifiques au niveau de l’Agent ou pour chaque 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" }
    }
  }
]);

En-têtes personnalisés

Si vous devez indiquer des en-têtes personnalisés, comme un ID d’organisation ou d’autres champs spécifiques à un Provider, utilisez cette syntaxe.

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"
    }
  }
});

info

La configuration varie selon le Provider. Consultez les pages des Providers dans la navigation de gauche pour obtenir des détails sur les en-têtes personnalisés.

Solutions de repli de modèle

S’appuyer sur un seul modèle crée un point de défaillance unique pour votre application. Les solutions de repli de modèle assurent un basculement automatique entre modèles et Providers. Si le modèle principal devient indisponible, les requêtes sont relancées avec la solution de repli configurée suivante jusqu’à ce que l’une réussisse.

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 essaie d’abord votre modèle principal. S’il rencontre une erreur 500, une limite de débit ou un délai d’expiration, il bascule automatiquement vers votre première solution de repli. Si celle-ci échoue également, il passe à la suivante. Chaque modèle dispose de son propre nombre de tentatives avant le passage au suivant.

Vos utilisateurs ne subissent jamais l’interruption : la réponse revient au même format, mais depuis un autre modèle. Le contexte d’erreur est conservé au fil de la chaîne de repli, ce qui assure une propagation claire des erreurs tout en préservant la compatibilité avec le streaming.

Paramètres par modèle

Chaque entrée de repli peut comporter ses propres modelSettings, providerOptions et headers, ce qui est utile lorsque les modèles de la chaîne nécessitent des températures ou des réglages propres au Provider différents pour produire des résultats comparables.

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' } },
    },
  ],
});

Priorité :

• modelSettings et providerOptions : l’entrée de repli remplace les options fournies à l’appel, lesquelles remplacent les defaultOptions de l’Agent. modelSettings effectue une fusion superficielle par clé. providerOptions effectue une fusion récursive, de sorte que la configuration Provider imbriquée (par exemple google.thinkingConfig) préserve les clés sœurs entre les couches.
• headers : modelSettings.headers fourni à l’appel remplace les headers de la solution de repli, qui remplacent les en-têtes extraits des modèles du routeur. Les en-têtes d’exécution (tracing, authentification, location) ont volontairement priorité sur les en-têtes au niveau du modèle.

Chaque champ accepte également une fonction de requestContext, conformément à la résolution des modèles dynamiques.

Utiliser des modèles locaux avec Mastra

Mastra prend aussi en charge les modèles locaux comme gpt-oss, Qwen3, DeepSeek et bien d’autres, que vous exécutez sur votre propre matériel. L’application qui exécute votre modèle local doit fournir un serveur API compatible OpenAI auquel Mastra peut se connecter. Nous recommandons LMStudio (voir Exécuter le serveur LMStudio).

Pour les points de terminaison personnalisés compatibles OpenAI, id est la forme de routage que Mastra envoie via le routeur de modèles.

Utilisez provider/model lorsque le service distant se comporte comme un Provider direct et attend un nom de modèle simple tel que llama3.2.

Utilisez gateway/provider/model lorsque le service distant se comporte comme une passerelle de modèles et que l’espace de noms du modèle en amont inclut le Provider, tel que mastra/google/gemini-2.5-flash ou openrouter/google/gemini-2.5-flash.

Pour url, il est important d’utiliser l’URL de base du point de terminaison compatible OpenAI avec le paramètre model de Mastra, et non les points de terminaison de chat individuels.

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"
  }
})

Si le service distant se comporte comme une passerelle de modèles, incluez le préfixe de passerelle dans id :

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"
  }
})

Exemple : LMStudio

Après le démarrage du serveur LMStudio, le serveur local est disponible à l’adresse http://localhost:1234 et fournit des points de terminaison tels que /v1/models, /v1/chat/completions, etc. La url sera http://localhost:1234/v1. Pour id, vous pouvez utiliser (lmstudio/${modelId}), qui sera affiché dans l’interface LMStudio.

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"
  }
})

Utiliser AI SDK avec Mastra

Mastra prend en charge les modules Provider d’AI SDK si vous devez les utiliser directement.

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')
})

Vous pouvez utiliser un modèle AI SDK (par exemple groq('gemma2-9b-it')) partout où une chaîne "provider/model" est acceptée, notamment dans les solutions de repli du routeur de modèles et les scorers.