Editor

Editor 的工作方式类似于 Mastra agents 的 CMS。协作者可以在 Studio 中更改 agent 的指令和 tools，而无需访问代码库或编写代码。他们可以在让更改生效之前先进行测试。

TypeScript 定义 agent 的默认值。Editor 将更改单独保存，而不是更新源代码，因此协作者可以改进 agent，同时开发者仍然掌控其模型、身份和运行时。

已部署的 Studio使 Editor 可供本地开发之外的协作者使用。

📹 观看

观看 Mastra Editor 研讨会获取引导式演练。

何时使用 Editor

当 agent 在代码中定义，但负责其行为的人员不应该编辑代码库时，使用 Editor。当指令或 tools 经常变化且需要在到达用户之前进行测试时，它非常适用。如果开发者拥有每一个变更，并将 agent 配置随应用一起发布，请继续使用代码中的 agent 配置。

当协作者需要在浏览器中创建和管理完全存储的 agents，而不是从代码中定义的 agents 开始时，请改用 Agent Builder。

快速开始

安装 @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 和存储添加到 Mastra 实例中。可以复用现有存储，而不必添加这里展示的 LibSQL 存储。

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 权限更新其指令和 tools。

使用数据库存储时，可以将更改保存为草稿，在不影响线上 agent 的情况下进行测试。当草稿准备好使用时再发布。

指令

Instructions 部分显示代码中定义的 agent 系统提示。协作者可以覆盖它，或添加指令块。

指令块可以包含来自当前请求的值。例如，{{userName}} 会插入通过请求上下文提供的名称。显示条件可以让指令块仅对某个客户、角色或功能开关显示。

提示词块

提示词块是一段保存的指令文本，可供多个 agents 使用。在 Prompts 下创建并发布一个提示词块。然后打开 agent 的 Instructions 部分，选择 Add block。

例如，support、returns 和 order status 的 agents 可能都需要相同的退款政策。将政策保存为一个提示词块，并添加到每个 agent 中。当政策变化时，只需更新并发布一次该块，而不必编辑三个 agents。

当提示词块发生变化时，每个引用其已发布版本的 agent 都会收到更新。草稿更改仅在预览时使用，因此在提示词块发布之前不会影响线上 agents。

关于模板语法、条件、版本和 API，参见提示词块参考。

Tools

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

• 项目 tools 必须由开发者在 Mastra 项目中实现并注册。
• 集成 tools 在开发者注册 Composio 或 Arcade 等提供方后可用。协作者随后可以浏览提供方的目录并添加 tools，而无需先在代码中逐个添加。
• MCP tools 在配置 MCP 客户端后可用。有权限的协作者可以在 Studio 中创建客户端，然后从该客户端服务器暴露的 tools 中进行选择。

在 agent 的 Tools 部分，协作者可以添加所需的 tools，或为该 agent 重写某个 tool 的描述。更具体的描述有助于 agent 理解何时使用该 tool，而无需更改 tool 本身。

项目 tools

开发者可以在 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 允许编辑 tools 时，协作者可以将其添加到该 agent。agent 的 Editor 视图还会列出在代码中附加的 tools。

Composio

Composio 提供用于 GitHub、Slack 和 Gmail 等服务的 tools。使用 Composio API key 注册该提供方，使其 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 客户端

协作者还可以在 Studio 中创建可复用的 MCP 客户端，并将其 tools 添加到 agent。存储的客户端可以启动本地 stdio 服务器，或连接到远程 HTTP 服务器。Tool 过滤器让每个 agent 只使用该服务器中它需要的 tools。

关于 MCP 配置、条件、过滤和解析顺序，参见 Editor tools 参考。关于提供方选项，参见 ToolProvider。

决定协作者可以编辑什么

默认情况下，协作者可以更改 agent 的指令并管理其 tools，包括 tool 描述。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 允许协作者更改其指令，并改进已附加 tools 的描述。他们无法添加或移除 tools。

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

Studio 会将其他所有内容显示为只读。完整配置参见 editor 覆盖项。

选择更改的存储位置

Editor 可以将更改保存到配置的数据库中，或保存为仓库中的文件。

数据库存储

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

要为 Editor 数据使用单独的后端，请在 MastraCompositeStore 上设置 editor 选项。没有显式路由的存储域会继续使用其 default 存储。

以下示例将应用数据和 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(),
})

仓库文件

使用 code source 将覆盖项与应用代码放在一起。开发者可以在 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 覆盖文件。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 的 model、name 和其他由代码拥有的字段仍保留在其 TypeScript 文件中。Mastra 会读取 JSON，并在 agent 运行时应用这些值。

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

关于文件位置和 source 选项，参见 MastraEditor。

版本管理

基于数据库的 agents 和提示词块使用草稿和已发布版本。保存会创建草稿，而线上 agent 继续使用已发布版本。发布会使草稿生效。恢复旧版本会创建一个草稿，协作者可以在发布前进行测试。

基于代码的 agent 覆盖项使用 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 测试中比较两个版本。
• 在向所有人发布之前，先将草稿提供给一小部分用户。
• 让生产环境使用已发布版本，而预发布环境使用最新草稿。
• 将某个客户固定到特定版本。

当 supervisor 调用 sub-agents 时，同样的版本控制也有效。开发者可以测试草稿 sub-agent，而无需更改系统其余部分。

关于版本选择、sub-agent 行为、REST 端点和 SDK 方法，参见 Editor 版本管理参考。

编程访问

Studio 中可用的所有功能也可以通过 mastra.getEditor()、REST API 或 Client SDK 以编程方式使用。使用它来编写批量更新脚本，或从代码填充存储的配置。它还可以驱动基于评估结果调整 agents 的自动化流程。

当应用代码可以访问 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."
  }'

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

关于可用操作，参见 MastraEditor 命名空间和 Client SDK agents API。

后续步骤

• MastraEditor 参考
• 提示词块参考
• Editor tools 参考
• Editor 版本管理参考