@mastra/mcp-docs-server 1.1.41 → 1.1.42-alpha.4

package/.docs/docs/agent-builder/overview.md

@@ -0,0 +1,97 @@
+# Agent Builder overview
+
+> **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
+
+The Agent Builder lets you build, configure, and operate Mastra agents all within the UI. It runs inside your Mastra server, persists everything to `Mastra.storage`, and supports multi-tenant agent workflows with RBAC and channel integrations.
+
+- [**Configuration**](https://mastra.ai/docs/agent-builder/configuration): Toggle UI sections and pin admin-controlled defaults for every new agent.
+- [**Model policy**](https://mastra.ai/docs/agent-builder/model-policy): Restrict which providers and models the Builder exposes, and pin a default.
+- [**Memory**](https://mastra.ai/docs/agent-builder/memory): Configure the default memory shape for every Builder-created agent.
+- [**Access control**](https://mastra.ai/docs/agent-builder/access-control): Gate the Builder behind Mastra RBAC roles and permissions.
+- [**Channels**](https://mastra.ai/docs/agent-builder/channels): Connect Builder-created agents to Slack and other channels.
+- [**Skill registries**](https://mastra.ai/docs/agent-builder/skill-registries): Browse and install community skills from opt-in registries.
+- [**Deploying**](https://mastra.ai/docs/agent-builder/deploying): Swap local primitives for cloud-backed storage, filesystems, and sandboxes.
+
+For building agents entirely in code, see the [Agents overview](https://mastra.ai/docs/agents/overview). For editing code-defined agents through Studio, see the [Editor overview](https://mastra.ai/docs/editor/overview).
+
+## Get started
+
+Install `@mastra/editor` alongside a storage adapter:
+
+**npm**:
+
+```bash
+npm install @mastra/editor @mastra/libsql
+```
+
+**pnpm**:
+
+```bash
+pnpm add @mastra/editor @mastra/libsql
+```
+
+**Yarn**:
+
+```bash
+yarn add @mastra/editor @mastra/libsql
+```
+
+**Bun**:
+
+```bash
+bun add @mastra/editor @mastra/libsql
+```
+
+Wire the Agent Builder onto a `Mastra` instance:
+
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { MastraEditor } from '@mastra/editor'
+import { createBuilderAgent } from '@mastra/editor/ee'
+import { LibSQLStore } from '@mastra/libsql'
+
+export const mastra = new Mastra({
+  storage: new LibSQLStore({ url: 'file:./mastra.db' }),
+  agents: { builderAgent: createBuilderAgent() },
+  editor: new MastraEditor({
+    builder: {
+      enabled: true,
+      configuration: {
+        agent: {
+          memory: { observationalMemory: true },
+        },
+      },
+    },
+  }),
+})
+```
+
+Start the dev server:
+
+```bash
+npx mastra dev
+```
+
+The Agent Builder is mounted at `http://localhost:4111/agent-builder`.
+
+## Prerequisites
+
+The Agent Builder requires:
+
+- **Storage**: An `@mastra/core` storage adapter on the `Mastra` instance. Agents, memory, and workspace state all persist through `Mastra.storage`.
+- **The Builder agent**: Register a Builder agent created with the `createBuilderAgent()` factory from `@mastra/editor/ee` on `Mastra.agents`. The chat-based editor invokes it through the same `Mastra.getAgent(id)` lookup as any other agent. Without this registration, the chat-based editor returns 404.
+- **`OPENAI_API_KEY`**: The Builder agent created by `createBuilderAgent()` runs on an OpenAI model, so an `OPENAI_API_KEY` environment variable is required.
+
+## Disabling the Builder
+
+Set `enabled: false` to keep the config in place but turn the surface off:
+
+```typescript
+new MastraEditor({
+  builder: {
+    enabled: false,
+  },
+})
+```
+
+Omitting the `builder` field has the same effect.

package/.docs/docs/agent-builder/skill-registries.md

@@ -0,0 +1,31 @@
+# Skill registries
+
+> **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
+
+Registries let the Agent Builder browse and install community skills directly from the UI. All registries are opt-in. When no registry is enabled, the Builder hides registry browse UI entirely.
+
+## Quickstart
+
+Enable the [skills.sh](https://skills.sh) registry:
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+new MastraEditor({
+  builder: {
+    enabled: true,
+    registries: {
+      skillsSh: { enabled: true },
+    },
+  },
+})
+```
+
+The Builder library tab now exposes a **Browse** view backed by skills.sh. End users can preview a skill, then install it into an agent.
+
+> **Note:** See the [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) for the full `registries` schema.
+
+## Related
+
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire registries alongside the rest of the Builder config.
+- [AgentBuilderOptions reference](https://mastra.ai/reference/editor/agent-builder/agent-builder-options) — every field on `builder`.

package/.docs/docs/agent-builder/workspace.md

@@ -0,0 +1,60 @@
+# Workspace
+
+> **Note:** The Agent Builder is part of the Mastra Enterprise Edition. Production deployments require a valid EE license. [Contact sales](https://mastra.ai/contact) for more information.
+
+A [workspace](https://mastra.ai/docs/workspace/overview) gives agents filesystem access, command execution, and skill loading. The Agent Builder pins a default workspace onto every new agent through `builder.configuration.agent.workspace`. End users can still override the workspace per agent through the Builder UI.
+
+## Quickstart
+
+Pin an inline workspace snapshot as the Builder default:
+
+```typescript
+import { Mastra } from '@mastra/core'
+import { MastraEditor } from '@mastra/editor'
+
+export const mastra = new Mastra({
+  editor: new MastraEditor({
+    builder: {
+      enabled: true,
+      configuration: {
+        agent: {
+          workspace: {
+            type: 'inline',
+            config: {
+              name: 'project-workspace',
+              filesystem: {
+                provider: 'local',
+                config: { basePath: './workspace' },
+              },
+            },
+          },
+        },
+      },
+    },
+  }),
+})
+```
+
+The Builder derives a deterministic id from the inline config and persists the snapshot, so identical inline configs are deduplicated across agents.
+
+## Workspace references
+
+`configuration.agent.workspace` accepts a `StorageWorkspaceRef`:
+
+- **`{ type: 'inline', config }`** — embeds a serialized workspace snapshot directly on the agent. Useful for per-agent, ad-hoc configurations.
+- **`{ type: 'id', workspaceId }`** — references a workspace already registered on the `Mastra` instance via `new Mastra({ workspace })` or `mastra.addWorkspace(...)`. Use this for shared, named workspaces.
+
+See the [StorageWorkspaceRef reference](https://mastra.ai/reference/editor/storage-workspace-ref) for both variants.
+
+## Filesystem and sandbox
+
+A workspace combines a `filesystem` (file tools) and an optional `sandbox` (command execution). For local development, point both at the same directory so files written through the filesystem are immediately visible to commands in the sandbox.
+
+For cloud deployments, swap `LocalFilesystem` / `LocalSandbox` for managed providers (e.g., S3, E2B). See [Deploying](https://mastra.ai/docs/agent-builder/deploying) for the cloud-swap pattern.
+
+## Related
+
+- [Workspace overview](https://mastra.ai/docs/workspace/overview) — the underlying workspace model.
+- [Filesystem](https://mastra.ai/docs/workspace/filesystem) and [Sandbox](https://mastra.ai/docs/workspace/sandbox) — the building blocks.
+- [BuilderAgentDefaults reference](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — the full `workspace` field schema.
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — wire `workspace` alongside the rest of the Builder config.

package/.docs/docs/agents/channels.md

@@ -88,6 +88,8 @@ When a user mentions the agent mid-conversation in a channel thread, the agent m
 
 Set `threadContext: { maxMessages: 0 }` to disable this behavior. This only applies to non-DM threads.
 
+Mastra also adds a short system message telling the agent which channel and platform the request came from (DM vs public channel, platform name, bot display name). Set `threadContext: { addSystemMessage: false }` to skip it.
+
 ## Tool approval
 
 Tools with `requireApproval: true` render as interactive cards with Approve and Deny buttons:

package/.docs/docs/memory/observational-memory.md

@@ -117,6 +117,25 @@ const memory = new Memory({
 
 In this example, the top-level idle setting is disabled for observations, while reflections opt into idle and provider-change activation.
 
+### Buffer on idle
+
+Set `observation.bufferOnIdle` to `true` to run background observation buffering when an agent turn ends and the agent becomes idle. This is useful for apps that want short turns to be observed without waiting for the next turn or the `messageTokens` threshold.
+
+```typescript
+const memory = new Memory({
+  options: {
+    observationalMemory: {
+      model: 'openai/gpt-5-mini',
+      observation: {
+        bufferOnIdle: true,
+      },
+    },
+  },
+})
+```
+
+`bufferOnIdle` is off by default. It is separate from `bufferTokens`: `bufferTokens` controls step-time async buffering, while `bufferOnIdle` controls end-of-turn buffering for idle turns.
+
 See [the API reference](https://mastra.ai/reference/memory/observational-memory) for the full configuration shape.
 
 ## Benefits

package/.docs/guides/deployment/inngest.md

@@ -431,6 +431,75 @@ export { handler as GET, handler as POST, handler as PUT }
 
 The `createServe` function works with any Inngest adapter. See the [Inngest serve documentation](https://www.inngest.com/docs/reference/serve) for a complete list of available adapters including AWS Lambda, Cloudflare Workers, and more.
 
+## Running as a Connect worker
+
+`serve()` exposes an HTTP endpoint that Inngest calls into. As an alternative, `connect()` opens a long-lived outbound connection from your worker to Inngest, so the worker does not need a publicly reachable endpoint. Use this for long-running worker processes on runtimes such as Kubernetes, Docker, ECS, Fly.io, or Render.
+
+> **Note:** Inngest Connect is in public beta. Serverless runtimes such as Vercel and AWS Lambda are not supported for Connect workers.
+
+### When to use `connect()` instead of `serve()`
+
+- The worker process runs in a private network that only allows outbound connections.
+- You want to keep heavy workflow execution out of the same process that serves user-facing HTTP traffic.
+- You want to scale workers up and down independently of the Mastra HTTP server, with per-worker concurrency limits.
+
+Use the same Mastra workflow definitions with either `serve()` or `connect()`. The collection behavior is the same for standard workflows, nested workflows, cron workflows, and additional Inngest functions.
+
+### Requirements
+
+- `inngest@^4`
+- Node.js `22.13.0` or later
+- A long-running process for the worker
+
+### Setup
+
+Run the Mastra server and the Connect worker as two processes. The Mastra server in this setup does not need to expose `/inngest/api`:
+
+```ts
+import { Mastra } from '@mastra/core'
+import { incrementWorkflow } from './workflows'
+import { PinoLogger } from '@mastra/loggers'
+
+export const mastra = new Mastra({
+  workflows: { incrementWorkflow },
+  logger: new PinoLogger({ name: 'Mastra', level: 'info' }),
+})
+```
+
+```ts
+import { connect } from '@mastra/inngest/connect'
+import { mastra } from './mastra'
+import { inngest } from './mastra/inngest'
+
+await connect({
+  mastra,
+  inngest,
+  instanceId: process.env.INNGEST_CONNECT_INSTANCE_ID,
+  maxWorkerConcurrency: Number(process.env.INNGEST_CONNECT_MAX_WORKER_CONCURRENCY ?? 10),
+})
+```
+
+Start the worker with `INNGEST_DEV=1 node --import tsx src/worker.ts` during local development. The Inngest Dev Server discovers the worker through the outbound connection, so no `-u` flag is required.
+
+In production, set `INNGEST_EVENT_KEY` and `INNGEST_SIGNING_KEY`. Set `appVersion` on the `Inngest` client to a deploy identifier, such as a commit SHA or image tag, so Inngest can manage rolling deploys.
+
+When migrating an existing production app from `serve()` to `connect()`, test the worker with a separate Inngest app before moving traffic.
+
+### Options
+
+`connect()` accepts the same options as Inngest's [`connect`](https://www.inngest.com/docs/setup/connect) plus the Mastra-specific fields. The most common ones:
+
+- `mastra`: The Mastra instance whose workflows should be exposed.
+- `inngest`: The Inngest client. Use the same client you would pass to `serve()`.
+- `functions`: Optional array of additional Inngest functions to register alongside Mastra workflows.
+- `instanceId`: Stable identifier for the worker, shown in the Inngest dashboard. Defaults to the machine hostname.
+- `maxWorkerConcurrency`: Maximum number of steps the worker runs at a time. Defaults to unlimited.
+- `registerOptions`: Forwarded to Inngest during app registration (for example `signingKey`). When a field is set both here and at the top level, `registerOptions` wins — this matches the behavior of `serve()`.
+
+`connect()` returns Inngest's `WorkerConnection`. The Inngest SDK handles `SIGINT` and `SIGTERM` by default. Store the returned connection and call `.close()` only when your worker needs custom shutdown control.
+
+If the Mastra instance has no `InngestWorkflow` and no additional `functions` are provided, `connect()` logs a warning because the worker would otherwise stay connected with nothing to execute. Register at least one workflow on Mastra or pass `functions: [...]`.
+
 ## Using a custom `apiPrefix`
 
 If you need to keep `/api/inngest` (for example to match Inngest's auto-discover convention without changing the dashboard URL), set `server.apiPrefix` to relocate Mastra's built-in routes:

package/.docs/reference/agents/channels.md

@@ -41,7 +41,7 @@ export const supportAgent = new Agent({
 
 **userName** (`string`): Bot display name shown in platform messages. Defaults to the agent's \`name\`, or \`'Mastra'\` if no name is set. (Default: `` agent's `name` ``)
 
-**threadContext** (`{ maxMessages?: number }`): Fetch recent messages from the platform when the agent is first mentioned in a thread. Set \`maxMessages: 0\` to disable. Only applies to non-DM threads. (Default: `{ maxMessages: 10 }`)
+**threadContext** (`{ maxMessages?: number; addSystemMessage?: boolean }`): How the agent picks up context about the current thread. \`maxMessages\` controls how many recent platform messages are fetched on first mention (set to \`0\` to disable; only applies to non-DM threads). \`addSystemMessage: false\` skips the built-in system message that tells the agent which channel/platform a request came from. (Default: `{ maxMessages: 10, addSystemMessage: true }`)
 
 **chatOptions** (`Omit<ChatConfig, 'adapters' | 'state' | 'userName'>`): Additional options passed directly to the \[Chat SDK]\(https\://chat-sdk.dev/docs/usage). Use for advanced configuration such as \`dedupeTtlMs\`, \`fallbackStreamingPlaceholderText\`, \`lockScope\`, and \`messageHistory\`.
 

package/.docs/reference/client-js/agent-builder.md

@@ -0,0 +1,161 @@
+# Agent Builder API
+
+The Agent Builder API provides methods to interact with [Agent Builder](https://mastra.ai/docs/agent-builder/overview) actions on the server. Each action is a workflow exposed under `/agent-builder/:actionId/*`. The Builder must be enabled on the server via `MastraEditor.builder.enabled`, with a valid `MASTRA_EE_LICENSE` in production.
+
+## Getting all actions
+
+Retrieve a record of available Agent Builder actions:
+
+```typescript
+const actions = await mastraClient.getAgentBuilderActions()
+```
+
+Returns a `Record<string, WorkflowInfo>` keyed by action ID.
+
+## Working with a specific action
+
+Get an instance of a specific action by its ID:
+
+```typescript
+const action = mastraClient.getAgentBuilderAction('create-agent')
+```
+
+## Action methods
+
+### `details()`
+
+Retrieve metadata about an Agent Builder action:
+
+```typescript
+const info = await action.details()
+```
+
+### `createRun()`
+
+Create a new run for this action and receive a `runId`. Use the returned id with `startActionRun()`, `stream()`, `resume()`, or `observeStream()`.
+
+```typescript
+const { runId } = await action.createRun()
+```
+
+You can also pass an explicit `runId`:
+
+```typescript
+const { runId } = await action.createRun({ runId: 'my-run-id' })
+```
+
+### `startAsync()`
+
+Start the action and wait for completion. Returns the final `AgentBuilderActionResult` with `success`, `applied`, `branchName`, `message`, `validationResults`, `error`, `errors`, and `stepResults`.
+
+```typescript
+const result = await action.startAsync({
+  inputData: { agentName: 'support-bot' },
+})
+```
+
+Pass an existing `runId` as the second argument to start a previously created run:
+
+```typescript
+const { runId } = await action.createRun()
+const result = await action.startAsync({ inputData }, runId)
+```
+
+### `startActionRun()`
+
+Start an existing run without waiting for completion. Returns `{ message }`.
+
+```typescript
+const { runId } = await action.createRun()
+await action.startActionRun({ inputData }, runId)
+```
+
+### `stream()`
+
+Start an existing run and stream progress events as a `ReadableStream<{ type, payload }>`.
+
+```typescript
+const { runId } = await action.createRun()
+const stream = await action.stream({ inputData }, runId)
+
+for await (const event of stream) {
+  console.log(event.type, event.payload)
+}
+```
+
+### `resume()`
+
+Resume a suspended step on a run. Returns `{ message }`.
+
+```typescript
+await action.resume({ step: 'review', resumeData: { approved: true } }, runId)
+```
+
+### `resumeAsync()`
+
+Resume a suspended step and wait for completion. Returns an `AgentBuilderActionResult`.
+
+```typescript
+const result = await action.resumeAsync({ step: 'review', resumeData: { approved: true } }, runId)
+```
+
+### `resumeStream()`
+
+Resume a suspended step and stream subsequent events.
+
+```typescript
+const stream = await action.resumeStream({
+  runId,
+  step: 'review',
+  resumeData: { approved: true },
+})
+```
+
+### `observeStream()`
+
+Attach to an existing run, replaying cached events from the beginning, then continuing with live events. Use this to recover after a page refresh or hot reload.
+
+```typescript
+const stream = await action.observeStream({ runId })
+```
+
+### `observeStreamLegacy()`
+
+Same as `observeStream()` but uses the legacy streaming endpoint. Prefer `observeStream()` for new code.
+
+```typescript
+const stream = await action.observeStreamLegacy({ runId })
+```
+
+### `runs()`
+
+List runs for this action with optional filters.
+
+```typescript
+const runs = await action.runs({ page: 0, perPage: 20 })
+```
+
+Accepts `fromDate`, `toDate`, `page`, `perPage`, `resourceId`, and legacy `limit`/`offset`.
+
+### `runById()`
+
+Fetch a specific run by ID. Use `fields` to limit the returned payload and `withNestedWorkflows` to skip nested workflow data.
+
+```typescript
+const run = await action.runById(runId, {
+  fields: ['result', 'steps'],
+  withNestedWorkflows: false,
+})
+```
+
+### `cancelRun()`
+
+Cancel an in-flight run.
+
+```typescript
+await action.cancelRun(runId)
+```
+
+## Access control
+
+The `/agent-builder/*` routes are gated by the `agent-builder` permission resource. Calling clients need at minimum `agent-builder:read` and `agent-builder:execute`, plus any picker resources the action touches (`stored-agents`, `stored-skills`, `tools`, `workflows`, `memory`). See [Access control](https://mastra.ai/docs/agent-builder/access-control) for the full grant list.

package/.docs/reference/client-js/mastra-client.md

@@ -73,6 +73,10 @@ You can also pass `requestContext` as a `Record<string, any>`.
 
 **getWorkflow(workflowId)** (`Workflow`): Retrieves a specific workflow instance by ID.
 
+**getAgentBuilderActions()** (`Promise<Record<string, WorkflowInfo>>`): Returns all available Agent Builder actions. See \[Agent Builder API]\(/reference/client-js/agent-builder).
+
+**getAgentBuilderAction(actionId)** (`AgentBuilder`): Retrieves an Agent Builder action by ID. See \[Agent Builder API]\(/reference/client-js/agent-builder).
+
 **responses** (`Responses`): Provides OpenAI-style Responses API helpers with \`create()\`, \`retrieve()\`, \`stream()\`, and \`delete()\`.
 
 **conversations** (`Conversations`): Provides conversation helpers with \`create()\`, \`retrieve()\`, \`delete()\`, and \`items.list()\`.

package/.docs/reference/editor/agent-builder/agent-builder-options.md

@@ -0,0 +1,74 @@
+# AgentBuilderOptions
+
+`AgentBuilderOptions` configures the Agent Builder. Pass it as `MastraEditor.builder` to enable the Builder UI, toggle visible surfaces, pin admin defaults, and opt into skill registries.
+
+See the [Configuration](https://mastra.ai/docs/agent-builder/configuration) page for concepts and worked examples.
+
+## Usage example
+
+```typescript
+import { MastraEditor } from '@mastra/editor'
+
+new MastraEditor({
+  builder: {
+    enabled: true,
+    features: {
+      agent: { browser: false },
+    },
+    configuration: {
+      agent: {
+        memory: { observationalMemory: true },
+        models: {
+          allowed: [
+            { provider: 'openai', modelId: 'gpt-5.4-mini' },
+            { provider: 'openai', modelId: 'gpt-5.4' },
+            { provider: 'anthropic', modelId: 'claude-opus-4-7' },
+          ],
+        },
+      },
+    },
+    registries: {
+      skillsSh: { enabled: true },
+    },
+  },
+})
+```
+
+## Properties
+
+**enabled** (`boolean`): Master switch. When false, the Builder UI is disabled and \`MastraEditor.resolveBuilder()\` returns undefined. (Default: `true`)
+
+**features** (`{ agent?: AgentFeatures }`): UI toggles. Each key on \`features.agent\` defaults to true when omitted.
+
+**features.agent.tools** (`boolean`): Show the tools tab in the agent editor.
+
+**features.agent.agents** (`boolean`): Show the sub-agents picker in the agent editor.
+
+**features.agent.workflows** (`boolean`): Show the workflows picker in the agent editor.
+
+**features.agent.skills** (`boolean`): Show the skills tab and library for the agent.
+
+**features.agent.memory** (`boolean`): Show the memory configuration in the agent editor.
+
+**features.agent.model** (`boolean`): Show the model picker in the agent editor. When false, the admin-pinned default model applies.
+
+**features.agent.browser** (`boolean`): Show the browser tab. Resolves to true only when a valid browser provider is registered on \`MastraEditor.browsers\`; otherwise it is downgraded to false and a warning is logged.
+
+**features.agent.avatarUpload** (`boolean`): Allow end users to upload an avatar for stored agents.
+
+**features.agent.favorites** (`boolean`): Show favorite agents and skills with per-user state and aggregate counts.
+
+**configuration** (`{ agent?: BuilderAgentDefaults }`): Admin-pinned defaults applied to every Builder-created agent. End users cannot override these values. See the BuilderAgentDefaults reference for the full schema.
+
+**registries** (`{ skillsSh?: { enabled: boolean } }`): Opt-in third-party skill registries. When no registry is enabled, the Builder hides registry browse UI.
+
+**registries.skillsSh** (`{ enabled: boolean }`): Enable the skills.sh registry. When enabled, the Builder shows registry browse UI for skills.sh skills.
+
+**registries.skillsSh.enabled** (`boolean`): Set to \`true\` to opt in. Defaults to \`false\`.
+
+## Related
+
+- [Configuration](https://mastra.ai/docs/agent-builder/configuration) — concept and worked examples.
+- [BuilderAgentDefaults](https://mastra.ai/reference/editor/agent-builder/builder-agent-defaults) — full schema for `configuration.agent`.
+- [builder.configuration.agent.models](https://mastra.ai/reference/editor/agent-builder/builder-models) — model allowlist and default model.
+- [MastraEditor class](https://mastra.ai/reference/editor/mastra-editor) — the parent surface that hosts `builder`.

package/.docs/reference/editor/agent-builder/builder-agent-defaults.md

@@ -0,0 +1,77 @@
+# 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.