MastraEditor class

The MastraEditor class sets up the editor system. Pass it to the Mastra constructor to turn on editor features like prompt blocks, agent code override, versioning, and tool providers.

See Editor for an introduction to what the editor does.

Usage example

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'

export const mastra = new Mastra({
  agents: {/* your agents */},
  editor: new MastraEditor(),
})

Constructor parameters

logger?:

Logger

Logger instance. Falls back to the Mastra instance logger if not set.

toolProviders?:

Record<string, ToolProvider>

= {}

Integration tool providers keyed by ID (for example, Composio or Arcade). Lets agents use third-party tools added through the editor.

processorProviders?:

Record<string, ProcessorProvider>

= {}

Processor providers for configurable input/output processing (for example, moderation or token limiting). Built-in providers are always included.

filesystems?:

Record<string, FilesystemProvider>

= {}

Filesystem providers for file access (for example, S3 or GCS). A local filesystem provider is always included.

sandboxes?:

Record<string, SandboxProvider>

= {}

Sandbox providers for code execution (for example, E2B). A local sandbox provider is always included.

blobStores?:

Record<string, BlobStoreProvider>

= {}

Blob storage providers for binary data (for example, S3). Falls back to the Mastra storage blob store if no provider is specified.

browsers?:

Record<string, BrowserProvider>

= {}

Browser providers for agent browser access (for example, Stagehand). No built-ins — required when builder.features.agent.browser is enabled. See the BrowserProvider reference for the provider interface.

builder?:

AgentBuilderOptions

Agent Builder configuration. See the AgentBuilderOptions reference. Omit or set enabled: false to disable the Builder.

source?:

'code' | 'db'

= 'db'

Where agent overrides are stored. With 'db', overrides live in the configured storage backend and Studio shows the save and publish flow. With 'code', overrides live as per-agent JSON files on disk (routed through a local FilesystemStore) and Studio shows filesystem actions. See Editor storage options for the difference.

codePath?:

string

= './mastra/editor/'

Directory used by the 'code' source for per-agent JSON files. Ignored when source is not 'code'.

Provider interfaces

Each provider field above takes a record keyed by provider id. See the per-provider reference pages for the implementation shape:

• ProcessorProvider
• FilesystemProvider
• SandboxProvider
• BlobStoreProvider
• BrowserProvider

Agent Builder

The builder field enables the Agent Builder, a browser-based UI for creating and editing stored agents. See:

• Agent Builder overview: Concepts and getting started.
• AgentBuilderOptions: Full options schema.
• BuilderAgentDefaults: Admin-pinned defaults for new agents.
• builder.configuration.agent.models: Model allowlist and default model.

Registering the Builder agent

The Builder UI runs against an agent created by the createBuilderAgent() factory from @mastra/editor/ee. Import the factory, invoke it, and register the returned agent under agents on your Mastra instance:

import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { createBuilderAgent } from '@mastra/editor/ee'

export const mastra = new Mastra({
  agents: { builderAgent: createBuilderAgent() },
  editor: new MastraEditor({
    builder: { enabled: true },
  }),
})

The key name (builderAgent) is conventional. Any key works. The @mastra/editor/ee subpath is gated by the Mastra Enterprise Edition license at runtime.

See the Agent Builder overview for the full setup checklist.

Namespaces

The editor exposes namespaces for managing different entity types. Access them from any Mastra instance with mastra.getEditor() and call the CRUD methods directly in application code, or rely on the Mastra server routes that use them under the hood.

All namespaces extend a shared CRUD base class, so they expose the same create, getById, update, delete, list, listResolved, and clearCache methods. The namespace-specific property tables below also document any additional methods.

agent:

EditorAgentNamespace

CRUD operations and version management for stored agents. Handles applying stored overrides to code-defined agents.

EditorAgentNamespace

create:

(input: StorageCreateAgentInput) => Promise<Agent>

Create a new stored agent and return a hydrated Agent instance. Accepts an id, authorId, metadata, and the initial snapshot (name, description, instructions, model, tools, memory, and so on).

getById:

(id: string, options?: GetByIdOptions) => Promise<Agent | null>

Return a hydrated Agent instance for a stored agent. Pass options with versionId, versionNumber, or status ("draft" | "published" | "archived") to target a specific version. Default version requests are cached.

update:

(input: StorageUpdateAgentInput) => Promise<Agent>

Partially update a stored agent. Creates a version from the provided snapshot fields, assigns it to activeVersionId, and invalidates the cache. Set memory to null to disable memory.

delete:

(id: string) => Promise<void>

Delete a stored agent and remove it from the Mastra runtime registry.

list:

(args?: StorageListAgentsInput) => Promise<StorageListAgentsOutput>

List stored agents with optional pagination, orderBy, authorId, and metadata filters. Returns raw stored snapshots.

listResolved:

(args?: StorageListAgentsInput) => Promise<StorageListAgentsResolvedOutput>

Same as list, but returns fully resolved configurations with references dereferenced.

applyStoredOverrides:

(agent: Agent, options?: { versionId?: string; status?: "draft" | "published" }) => Promise<Agent>

Mutate a code-defined agent in place to apply any stored overrides (instructions, tools, variables). Called internally by mastra.getAgent() — you rarely call it directly.

clone:

(agent: Agent, options: { newId: string; newName?: string; metadata?: Record<string, unknown>; authorId?: string; requestContext?: RequestContext; }) => Promise<Agent>

Create a new stored agent by cloning an existing agent.

clearCache:

(agentId?: string) => void

Clear the in-memory cache for one agent or all agents. Called automatically after mutations.

prompt:

EditorPromptNamespace

CRUD operations for prompt blocks. Includes a preview method for resolving instruction blocks with draft content.

EditorPromptNamespace

create:

(input: StorageCreatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>

Create a new stored prompt block. Accepts an id, authorId, metadata, and the initial snapshot (name, description, content, rules, requestContextSchema).

getById:

(id: string, options?: GetByIdOptions) => Promise<StorageResolvedPromptBlockType | null>

Return a resolved prompt block. Pass options to target a specific version or status.

update:

(input: StorageUpdatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>

Partially update a stored prompt block. Creates a new draft version with the provided snapshot fields.

delete:

(id: string) => Promise<void>

Delete a stored prompt block and remove it from the Mastra runtime registry.

list:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksOutput>

List stored prompt blocks with optional pagination, orderBy, authorId, metadata, and status filters.

listResolved:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksResolvedOutput>

Same as list, but returns fully resolved prompt block content.

preview:

(blocks: AgentInstructionBlock[], context: Record<string, unknown>) => Promise<string>

Resolve an array of instruction blocks against a context, rendering template variables and evaluating display conditions. Includes draft content for referenced prompt blocks.

clearCache:

(id?: string) => void

Clear the in-memory cache for one prompt block or all prompt blocks.

mcp:

EditorMCPNamespace

CRUD operations for stored MCP client configurations.

EditorMCPNamespace

create:

(input: StorageCreateMCPClientInput) => Promise<MCPClient>

Create a new stored MCP client. Accepts an id, authorId, metadata, and the initial snapshot (servers, tool filtering).

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPClient | null>

Return a hydrated MCPClient instance for a stored MCP client.

update:

(input: StorageUpdateMCPClientInput) => Promise<MCPClient>

Partially update a stored MCP client and invalidate the cache.

delete:

(id: string) => Promise<void>

Delete a stored MCP client and remove it from the Mastra runtime registry.

list:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsOutput>

List stored MCP clients with optional pagination and filters.

listResolved:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsResolvedOutput>

Same as list, but returns fully resolved MCP client configurations.

clearCache:

(id?: string) => void

Clear the in-memory cache for one MCP client or all MCP clients.

mcpServer:

EditorMCPServerNamespace

CRUD operations for MCP server configurations.

EditorMCPServerNamespace

create:

(input: StorageCreateMCPServerInput) => Promise<MCPServerBase>

Create a new stored MCP server configuration and return a hydrated server instance.

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>

Return a hydrated MCP server for a given id.

update:

(input: StorageUpdateMCPServerInput) => Promise<MCPServerBase>

Partially update a stored MCP server configuration.

delete:

(id: string) => Promise<void>

Delete a stored MCP server configuration.

list:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersOutput>

List stored MCP server configurations.

listResolved:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersResolvedOutput>

Same as list, but returns fully resolved server configurations.

clearCache:

(id?: string) => void

Clear the in-memory cache for one MCP server or all MCP servers.

scorer:

EditorScorerNamespace

CRUD operations for scorer configurations.

EditorScorerNamespace

create:

(input: StorageCreateScorerInput) => Promise<MastraScorer>

Create a new stored scorer and return a hydrated MastraScorer instance.

getById:

(id: string, options?: GetByIdOptions) => Promise<MastraScorer | null>

Return a hydrated scorer for a given id.

update:

(input: StorageUpdateScorerInput) => Promise<MastraScorer>

Partially update a stored scorer.

delete:

(id: string) => Promise<void>

Delete a stored scorer and remove it from the Mastra runtime registry.

list:

(args?: StorageListScorersInput) => Promise<StorageListScorersOutput>

List stored scorers with optional pagination and filters.

listResolved:

(args?: StorageListScorersInput) => Promise<StorageListScorersResolvedOutput>

Same as list, but returns fully resolved scorer configurations.

clearCache:

(id?: string) => void

Clear the in-memory cache for one scorer or all scorers.

Agent namespace examples

Create a stored override for an existing code-defined agent:

src/scripts/seed-agent.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.create({
  id: 'support-agent',
  instructions: 'You are a friendly support agent for Acme.',
  tools: {
    search_kb: { description: 'Search the Acme knowledge base' },
  },
})

Stored agent memory

The memory field of a stored agent accepts one of these shapes:

• { type: 'id', memoryId: string }: Uses a memory instance registered on the Mastra instance. The editor looks up memoryId as a registry key first, then as the memory instance's id. The agent uses that exact instance, including its storage, processors, and working memory settings.
• { type: 'inline', config: SerializedMemoryConfig }: Builds a new memory instance from a serializable config.
• SerializedMemoryConfig: The untagged inline config. Existing stored agents use this shape and keep working.

Reference a registered memory instance so many stored agents share one configuration:

src/scripts/seed-agent.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.create({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'You are a friendly support agent for Acme.',
  model: { provider: 'openai', name: 'gpt-5' },
  memory: { type: 'id', memoryId: 'supportMemory' },
})

The reference is resolved when the editor loads the agent. If no registered memory matches memoryId, the agent loads without memory and the editor logs a warning that names the missing key. The stored reference isn't changed. In conditional memory, a variant whose reference isn't registered is skipped. If you register memory with mastra.addMemory() after an agent has loaded, call editor.agent.clearCache(id) so the next load picks it up. Renaming or removing a key in the Mastra memory config detaches memory from every stored agent that references it, so keep keys stable across deployments.

editor.agent.clone() stores a reference when the source agent uses a registered memory instance, and an inline config otherwise.

Methods

Provider access

getToolProvider(id)

Returns a registered tool provider by its ID.

const composio = mastra.getEditor()?.getToolProvider('composio')

getToolProviders()

Returns all registered tool providers as a Record<string, ToolProvider>.

getProcessorProvider(id)

Returns a registered processor provider by its ID.

getProcessorProviders()

Returns all registered processor providers.

getFilesystemProviders()

Returns all registered filesystem providers.

getSandboxProviders()

Returns all registered sandbox providers.

getBlobStoreProviders()

Returns all registered blob store providers.

Source

getSource()

Returns the configured source ('code' or 'db'), or undefined when the editor was constructed without an explicit source.

const source = mastra.getEditor()?.getSource()

Returns: 'code' | 'db' | undefined

When source is omitted, Editor uses the configured database storage even though getSource() returns undefined. See Editor storage options for the storage workflows and code-source versioning for activation and Git history behavior.