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

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

# 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](https://mastra.ai/docs/agent-builder/configuration) and [Memory](https://mastra.ai/docs/agent-builder/memory) for worked examples.

## Usage example

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

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

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

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

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

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

**workflows.allowed** (`string[]`): Allowlist of workflow\.id values. Omit for unrestricted, pass \[] to lock the picker down, pass \[...ids] to restrict to the listed workflows.

## Related

- [AgentBuilderOptions](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — the parent options object.
- [builder.configuration.agent.models](https://mastra.ai/reference/editor/agent-builder/builder-models) — admin-facing model allowlist and default.
- [SerializedMemoryConfig](https://mastra.ai/reference/memory/serialized-memory-config) — memory shape for new agents.
- [StorageWorkspaceRef](https://mastra.ai/reference/editor/storage-workspace-ref) — workspace reference shape.
- [StorageBrowserRef](https://mastra.ai/reference/editor/storage-browser-ref) — browser reference shape.
- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — concept and worked examples.