Editor

Editor 的工作方式类似 Mastra Agent 的 CMS。协作者无需访问代码库或编写代码，就能在 Studio 中更改 Agent 的 instructions 和 Tool。他们可以在变更上线前进行测试。

TypeScript 定义 Agent 的默认值。Editor 会单独保存变更，而不更新源代码，因此协作者可以改进 Agent，开发者则仍能控制其模型、身份和运行时。

部署后的 Studio 可让本地开发环境之外的协作者使用 Editor。

📹 观看

观看 Mastra Editor workshop，获取分步演示。

何时使用 Editor

如果 Agent 在代码中定义，但负责其行为的人员不应编辑代码库，请使用 Editor。当 instructions 或 Tool 经常变更且需要在提供给用户前进行测试时，Editor 尤其适合。如果每项变更都由开发者负责，并随应用一起发布 Agent 配置，请改为将 Agent 配置保留在代码中。

快速入门

安装 @mastra/editor。本快速入门使用 LibSQL 存储 Editor 变更：

npm

npm install @mastra/editor @mastra/libsql

pnpm

pnpm add @mastra/editor @mastra/libsql

Yarn

yarn add @mastra/editor @mastra/libsql

Bun

bun add @mastra/editor @mastra/libsql

将 MastraEditor 和 Storage 添加到 Mastra 实例。可以复用现有 Storage，无需添加此处所示的 LibSQL Store。

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new LibSQLStore({
    id: 'mastra-storage',
    url: 'file:./mastra.db',
  }),
  editor: new MastraEditor(),
})

在 Studio 中使用 Editor

在 Studio 中打开 Agents，选择一个 Agent，然后选择 Editor。协作者可以根据该 Agent 的 Editor 权限更新其 instructions 和 Tool。

使用数据库 Storage 时，请将变更保存为草稿，以便在不影响线上 Agent 的情况下测试。准备好使用后，再发布草稿。

Instructions

Instructions 部分显示代码中定义的 Agent system prompt。协作者可以覆盖该 prompt 或添加 instruction block。

Instruction block 可以包含当前请求中的值。例如，{{userName}} 会插入通过 request context 提供的名称。显示条件可以让 block 只针对特定客户、角色或 feature flag 显示。

Prompt block

Prompt block 是一段已保存的 instruction 文本，可供多个 Agent 使用。在 Prompts 下创建并发布一个 block，然后打开 Agent 的 Instructions 部分并选择 Add block。

例如，负责支持、退货和订单状态的 Agent 可能都需要相同的退款政策。将该政策保存为 prompt block 并添加到每个 Agent。政策变更时，只需更新并发布该 block 一次，无需编辑三个 Agent。

Prompt block 发生变化时，引用其已发布版本的每个 Agent 都会收到更新。草稿变更只在预览期间使用，因此在 block 发布前不会影响线上 Agent。

有关模板语法、条件、版本和 API，请参阅 prompt block Reference。

Tools

Tool 让 Agent 能够执行操作。协作者从 Editor 可用的 Tool 中进行选择，但无法在 Studio 中实现新 Tool。Tool 的可用方式取决于其来源：

• 项目 Tool 必须由开发者在 Mastra 项目中实现和注册。
• 集成 Tool 会在开发者注册 Composio 或 Arcade 等 Provider 后可用。随后，协作者可以浏览 Provider 的目录并添加 Tool，无需先在代码中逐个添加。
• MCP Tool 会在配置 MCP client 后可用。有访问权限的协作者可以在 Studio 中创建 client，然后从其 Server 公开的 Tool 中选择。

在 Agent 的 Tools 部分中，协作者可以添加所需 Tool，或针对该 Agent 重写 Tool 的 description。更具体的 description 可以帮助 Agent 理解何时使用该 Tool，而无需更改 Tool 本身。

项目 Tool

开发者可以在 Mastra 实例上注册项目 Tool，使其在 Editor 中可用：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'
import { searchOrders } from './tools/search-orders'

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

Studio Tool 选择器会列出该 Tool。当 Agent 允许编辑 Tool 时，协作者可以将它添加到 Agent。Agent 的 Editor 视图还会列出代码中附加的 Tool。

Composio

Composio 为 GitHub、Slack 和 Gmail 等服务提供 Tool。使用 Composio API Key 注册 Provider，使其 Tool 目录在 Editor 中可用：

src/mastra/index.ts

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

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

Composio Tool ID 的形式类似 GITHUB_CREATE_ISSUE。默认情况下，选定 Tool 使用与 Agent 作者关联的连接。要改为使用每个调用方的连接，请参阅连接范围。

Arcade

Arcade 提供另一个内置身份验证的 Tool 目录。使用 Arcade API Key 进行注册：

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* agents */},
  editor: new MastraEditor({
    toolProviders: {
      arcade: new ArcadeToolProvider({
        apiKey: process.env.ARCADE_API_KEY!,
      }),
    },
  }),
})

Arcade Tool ID 使用 Toolkit.ToolName 格式，例如 Github.GetRepository。

MCP client

协作者还可以在 Studio 中创建可复用的 MCP client，并将其 Tool 添加到 Agent。已存储的 client 可以启动本地 stdio Server 或连接到远程 HTTP Server。Tool 过滤器让每个 Agent 只能使用它需要的 Server Tool。

有关 MCP 配置、条件、过滤和解析顺序，请参阅 Editor Tool Reference。有关 Provider 选项，请参阅 ToolProvider。

决定协作者可以编辑哪些内容

默认情况下，协作者可以更改 Agent 的 instructions 并管理其 Tool，包括 Tool description。Agent 的 id、name 和 model 始终来自代码。

使用 Agent 的 editor 字段限制可以更改的内容：

src/mastra/agents/support-agent.ts

import { Agent } from '@mastra/core/agent'

export const supportAgent = new Agent({
  id: 'support-agent',
  name: 'Support agent',
  instructions: 'Help customers with Acme products.',
  model: 'openai/gpt-5.6-sol',
  editor: {
    instructions: true,
    tools: {
      description: true,
    },
  },
})

此 Agent 允许协作者更改其 instructions，并改进已附加 Tool 的 description，但不能添加或移除 Tool。

editor 值	协作者可以更改的内容
省略	Instructions、Tool 和 Tool description
false	无
{ instructions: true }	Instructions
{ tools: true }	Tool 和 Tool description
{ tools: { description: true } }	已在代码中添加的 Tool description

Studio 会将其他所有内容显示为只读。有关完整配置，请参阅 editor override。

选择变更的存储位置

Editor 可以将变更保存在配置的数据库中，也可以作为文件保存在仓库中。

数据库 Storage

数据库选项是默认设置。Editor 使用 Mastra 实例上配置的 Storage，因此应用和 Editor 可以共享同一后端。

要为 Editor 数据使用单独的后端，请在 MastraCompositeStore 上设置 editor 选项。未显式指定路由的 Storage domain 会继续使用其 default Store。

以下示例将应用和 Editor 数据分别保存在不同的 LibSQL 文件中：

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { MastraCompositeStore } from '@mastra/core/storage'
import { MastraEditor } from '@mastra/editor'
import { LibSQLStore } from '@mastra/libsql'

export const mastra = new Mastra({
  agents: {/* existing agents */},
  storage: new MastraCompositeStore({
    id: 'mastra-storage',
    default: new LibSQLStore({
      id: 'app-storage',
      url: 'file:./mastra.db',
    }),
    editor: new LibSQLStore({
      id: 'editor-storage',
      url: 'file:./editor.db',
    }),
  }),
  editor: new MastraEditor(),
})

仓库文件

使用代码源将 override 与应用代码一起保存。开发者可以在 pull request 中审查文件，并随应用一起部署：

src/mastra/index.ts

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

export const mastra = new Mastra({
  agents: {/* existing agents */},
  editor: new MastraEditor({
    source: 'code',
    codePath: './mastra/editor',
  }),
})

在此模式下，每个已编辑的 Agent 都有一个 JSON override 文件。Editor 不会生成 TypeScript，也不会更改创建 Agent 的文件。默认情况下，ID 为 support-agent 的 Agent 会获得以下文件：

mastra/editor/agents/support-agent.json

该文件只包含由 Editor 管理的部分。例如：

mastra/editor/agents/support-agent.json

{
  "instructions": "Help customers with Acme products and answer in their language.",
  "tools": {
    "searchOrders": {
      "description": "Look up an order by its number"
    }
  }
}

Agent 的模型、名称和其他由代码管理的字段仍保留在其 TypeScript 文件中。Agent 运行时，Mastra 会读取 JSON 并应用这些值。

协作者在 Studio 中保存时，可以将文件写入本地文件系统或下载。通过源代码控制集成，Studio 还可以改为打开 pull request。随后，Git 会提供审查和版本历史记录。

有关文件位置和源选项，请参阅 MastraEditor。

版本控制

由数据库支持的 Agent 和 prompt block 使用草稿版本和已发布版本。保存会创建草稿，而线上 Agent 会继续使用已发布版本。发布会使草稿上线。恢复旧版本会创建草稿，协作者可以先测试再发布。

由代码支持的 Agent override 使用 JSON 文件和 Git 历史记录。

选择版本

应用可以通过传入状态（published 或 draft）或确切的版本 ID，为每个请求选择已存储版本：

Version selection

const publishedAgent = await mastra.getAgentById('support-agent', {
  status: 'published',
})

const draftAgent = await mastra.getAgentById('support-agent', {
  status: 'draft',
})

const versionedAgent = await mastra.getAgentById('support-agent', {
  versionId: 'abc-123',
})

版本选择支持：

• 在 A/B 测试中比较两个版本。
• 在向所有人发布草稿前，先提供给小范围群组。
• 让生产环境保持在已发布版本，而 staging 使用最新草稿。
• 将客户固定到特定版本。

Supervisor 调用 Subagent 时，同样的版本控制也能正常工作。开发者可以测试 Subagent 草稿，而不改变系统的其余部分。

有关版本选择、Subagent 行为、REST 端点和 SDK 方法，请参阅 Editor 版本控制 Reference。

以编程方式访问

Studio 中提供的所有功能也可以通过 mastra.getEditor()、REST API 或 Client SDK 以编程方式使用。可用它编写批量更新脚本，或从代码植入已存储配置。它还可以支持根据评估结果调优 Agent 的自动化。

当应用代码可以访问 Mastra 实例时，请调用 mastra.getEditor()：

src/scripts/update-agent.ts

import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.update({
  id: 'support-agent',
  instructions: 'Help customers with Acme products. Reply in their language.',
})

直接调用 editor.agent.update() 方法会立即激活新版本。要创建草稿而不更改线上 Agent，请改用已存储 Agent REST API 或 Client SDK：

Create a draft through the REST API

curl -X PATCH http://localhost:4111/api/stored/agents/support-agent \
  -H "Content-Type: application/json" \
  -d '{
    "instructions": "Help customers with Acme products. Reply in their language."
  }'

默认 Server 前缀为 /api。开发者可以在 Server 配置中设置自定义前缀。

有关可用操作，请参阅 MastraEditor namespace 和 Client SDK Agent API。

后续步骤

• MastraEditor Reference
• Prompt block Reference
• Editor Tool Reference
• Editor 版本控制 Reference