MastraModelGateway

Abstract base class for implementing custom model gateways. Gateways handle provider-specific logic for accessing language models, including provider configuration, authentication, URL construction, and model instantiation.

Class Overview

import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm';
import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5';
import type { LanguageModelV2 } from '@ai-sdk/provider-v5';

class MyCustomGateway extends MastraModelGateway {
  readonly id = 'custom';
  readonly name = 'My Custom Gateway';

  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
    return {
      'my-provider': {
        name: 'My Provider',
        models: ['model-1', 'model-2'],
        apiKeyEnvVar: 'MY_API_KEY',
        gateway: this.id,
      },
    };
  }

  buildUrl(modelId: string, envVars?: Record<string, string>): string {
    return 'https://api.my-provider.com/v1';
  }

  async getApiKey(modelId: string): Promise<string> {
    const apiKey = process.env.MY_API_KEY;
    if (!apiKey) throw new Error('MY_API_KEY not set');
    return apiKey;
  }

  async resolveLanguageModel({
    modelId,
    providerId,
    apiKey,
  }: {
    modelId: string;
    providerId: string;
    apiKey: string;
  }): Promise<LanguageModelV2> {
    const baseURL = this.buildUrl(`${providerId}/${modelId}`);
    return createOpenAICompatible({
      name: providerId,
      apiKey,
      baseURL,
    }).chatModel(modelId);
  }
}

Required Properties

id:

string

Unique identifier for the gateway. This ID is used as the prefix for all providers from this gateway (e.g., "netlify/anthropic"). Exception: models.dev is a provider registry and doesn't use a prefix.

name:

string

Human-readable name for the gateway.

Required Methods

fetchProviders()

Fetches provider configurations from the gateway.

Returns: Promise<Record<string, ProviderConfig>>

ProviderConfig Structure:

name:

string

Display name of the provider

models:

string[]

Array of available model IDs

apiKeyEnvVar:

string | string[]

Environment variable(s) for API key

gateway:

string

Gateway identifier

url?:

string

Optional base API URL

apiKeyHeader?:

string

Optional custom auth header name

docUrl?:

string

Optional documentation URL

buildUrl()

Builds the API URL for a specific model/provider combination.

Parameters:

modelId:

string

Full model ID (e.g., "custom/my-provider/model-1")

envVars?:

Record<string, string>

Optional environment variables

Returns: string | undefined | Promise<string | undefined>

getApiKey()

Retrieves the API key for authentication.

Parameters:

modelId:

string

Full model ID

Returns: Promise<string>

resolveLanguageModel()

Creates a language model instance.

Parameters:

modelId:

string

The model ID

providerId:

string

The provider ID

apiKey:

string

The API key for authentication

Returns: Promise<LanguageModelV2> | LanguageModelV2

Instance Methods

getId()

Returns the gateway's unique identifier.

Returns: string - The gateway's id property

Model ID Format

For true gateways, the gateway ID is used as a prefix and models are accessed using this format:

[gateway-id]/[provider]/[model]

Examples:

• Gateway with id = 'custom': 'custom/my-provider/model-1'

Built-in Implementations

• NetlifyGateway - Netlify AI Gateway integration
• ModelsDevGateway - Registry of OpenAI-compatible providers

Related

• Custom Gateways Guide - Complete guide to creating custom gateways