@mastra/core/dist/docs/references/reference-editor-agent-builder-builder-models.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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](https://mastra.ai/docs/agent-builder/model-policy) for concepts and worked examples.

## Usage example

```typescript
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.

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

**allowed.modelId** (`ModelForProvider<Provider>`): Specific model id for that provider. Omit to allow every model under the provider.

**allowed.kind** (`'custom'`): Discriminant marking this entry as a gateway or self-hosted provider not in the registry.

**allowed.provider** (`string`): Provider id for the custom provider.

**allowed.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.

**default.provider** (`Provider | string`): Provider id. Use a Provider literal for known providers, or any string with kind: 'custom'.

**default.modelId** (`string`): Required model id. Points at a specific model, not a whole provider.

**default.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](https://mastra.ai/reference/editor/agent-builder/agent-builder-options). When the picker is hidden, provide a `default` so new agents resolve a model.

## Related

- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — parent object containing `models`.
- [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — the top-level Builder options.
- [Model policy](https://mastra.ai/docs/agent-builder/model-policy) — concept and worked examples.