builder.configuration.agent.models

builder.configuration.agent.models is the admin-facing model policy input on AgentBuilderOptions. It controls which providers and models the Agent Builder exposes, and which model is pre-selected on new-agent create.

See Model policy for concepts and worked examples.

Usage example

src/mastra/index.ts

import { MastraEditor } from '@mastra/editor'

new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        models: {
          allowed: [
            { provider: 'openai', modelId: 'gpt-5.4-mini' },
            { provider: 'openai', modelId: 'gpt-5.4' },
            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
          ],
        },
      },
    },
  },
})

Properties

allowed?:

ProviderModelEntry[]

Allowlist of providers and models. Omit to allow every registered model. When non-empty, only the listed entries are selectable in the Builder.

KnownProviderEntry

provider:

Provider

Provider id from the generated provider registry (for example, `openai`, `anthropic`).

modelId?:

ModelForProvider<Provider>

Specific model id for that provider. Omit to allow every model under the provider.

CustomProviderEntry

kind:

'custom'

Discriminant marking this entry as a gateway or self-hosted provider not in the registry.

provider:

string

Provider id for the custom provider.

modelId?:

string

Specific model id under the custom provider. Omit to allow every model under it.

default?:

DefaultModelEntry

Pre-selected model on new-agent create. Same shape as `ProviderModelEntry`, but `modelId` is required. Must satisfy the `allowed` list when set.

DefaultModelEntry

provider:

Provider | string

Provider id. Use a `Provider` literal for known providers, or any `string` with `kind: 'custom'`.

modelId:

string

Required model id. Points at a specific model, not a whole provider.

kind?:

'custom'

Set to `custom` when targeting a provider that isn't in the generated registry.

Validation rules

Mastra validates the admin policy at server boot. Violations surface as warnings on GET /editor/builder/settings.modelPolicyWarnings.

• allowed empty or omitted: no restriction. Every registered model is available.
• When allowed is non-empty and a default is set: default must satisfy isModelAllowed(allowed, default). A default that fails this check is dropped and surfaced as a warning.
• To hide the end-user model picker, set features.agent.model: false in AgentBuilderOptions. When the picker is hidden, provide a default so new agents resolve a model.

Related

• BuilderAgentDefaults — parent object containing models.
• AgentBuilderOptions — the top-level Builder options.
• Model policy — concept and worked examples.