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 the Editor overview for an introduction to what the editor does.

Usage example

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {
    /* your agents */
  },
  editor: new MastraEditor({
    toolProviders: {
      composio: new ComposioToolProvider({
        apiKey: process.env.COMPOSIO_API_KEY!,
      }),
    },
  }),
})

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.

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 new draft version with the provided snapshot fields (instructions, tools, memory, and so on) 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.

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.