Skip to main content

BuilderAgentDefaults

BuilderAgentDefaults describes the admin-pinned defaults applied to every agent the Agent Builder produces. Pass it as builder.configuration.agent. End users can't override these values from the Builder UI.

See Configuration and Memory for worked examples.

Usage example
Direct link to Usage example

src/mastra/index.ts
import { MastraEditor } from '@mastra/editor'

new MastraEditor({
  builder: {
    enabled: true,
    configuration: {
      agent: {
        memory: { observationalMemory: true },
        workspace: {
          type: 'inline',
          config: {
            name: 'builder-workspace',
            filesystem: {
              provider: 'local',
              config: { basePath: './workspace' },
            },
          },
        },
        models: {
          allowed: [
            { provider: 'openai', modelId: 'gpt-5.4-mini' },
            { provider: 'openai', modelId: 'gpt-5.4' },
            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
          ],
        },
        tools: { allowed: ['weather-info'] },
        agents: { allowed: ['weather-agent'] },
        workflows: { allowed: ['greet-workflow'] },
      },
    },
  },
})

Properties
Direct link to Properties

memory?:

SerializedMemoryConfig
Default memory configuration for new agents. Pass `{ observationalMemory: true }` to enable long-lived fact extraction. Requires `Mastra.storage`. See the SerializedMemoryConfig reference for the full schema.

workspace?:

StorageWorkspaceRef
Default workspace reference for new agents. Pass `{ type: 'inline', config }` to embed a snapshot, or `{ type: 'id', workspaceId }` to point at a workspace registered on `Mastra.workspace`. See the StorageWorkspaceRef reference for both variants.

browser?:

StorageBrowserRef
Default browser configuration for new agents. Pass `{ type: 'inline', config: { provider } }` to attach a registered browser provider. See the StorageBrowserRef reference for the full schema.

models?:

{ allowed?: ProviderModelEntry[]; default?: DefaultModelEntry }
Model allowlist and default applied to every Builder-created agent. See the BuilderModels reference for the full schema and validation rules.
{ allowed?: ProviderModelEntry[]; default?: DefaultModelEntry }

allowed?:

ProviderModelEntry[]
Allowlist of providers and models. Omit to allow every registered model. ProviderModelEntry is a discriminated union (known providers vs. custom).

default?:

DefaultModelEntry
Pre-selected model on new-agent create. Required when the model picker is hidden. DefaultModelEntry requires `provider` and `modelId`, with an optional `kind`.

tools?:

{ allowed?: string[] }
Allowlist of tool IDs visible in the Builder tools picker. Unknown IDs are dropped and surfaced as warnings.
{ allowed?: string[] }

allowed?:

string[]
Allowlist of `tool.id` values. Omit for unrestricted, pass `[]` to lock the picker down, pass `[...ids]` to restrict to the listed tools.

agents?:

{ allowed?: string[] }
Allowlist of agent IDs visible in the Builder sub-agents picker. Unknown IDs are dropped and surfaced as warnings.
{ allowed?: string[] }

allowed?:

string[]
Allowlist of `Agent.id` values. Omit for unrestricted, pass `[]` to lock the picker down, pass `[...ids]` to restrict to the listed agents.

workflows?:

{ allowed?: string[] }
Allowlist of workflow IDs visible in the Builder workflows picker. Unknown IDs are dropped and surfaced as warnings.
{ allowed?: string[] }

allowed?:

string[]
Allowlist of `workflow.id` values. Omit for unrestricted, pass `[]` to lock the picker down, pass `[...ids]` to restrict to the listed workflows.
On this page