Model policy

The model policy controls which providers and models Builder-created agents can use, which model is selected by default, and whether end users can change it. Define the policy in builder.configuration.agent.models.

Quickstart

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

This restricts the Builder's model picker to two OpenAI models and one Anthropic model. End users choose one when creating an agent.

Validation rules

Mastra validates the model policy at server boot. getModelPolicyWarnings() returns warnings for any violations.

• When allowed is empty or omitted, every registered model is available.
• When allowed is non-empty, default (if set) must satisfy the allowlist. Mastra drops a default that fails this check and reports a warning through getModelPolicyWarnings().
• 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.

Registered providers (provider: 'openai', provider: 'anthropic', and so on) can omit modelId to allow every model from that provider.

See the builder.configuration.agent.models reference for every admin-writable field and validation rules.