Editor

Editor 就像 Mastra Agent 的 CMS。協作者不必存取程式碼庫或撰寫程式碼，就能在 Studio 中變更 Agent 的指示與 Tool，並在上線前測試變更。

TypeScript 會定義 Agent 的預設值。Editor 會另外儲存變更，而不更新原始碼，因此協作者能改善 Agent，同時讓開發者保有對模型、身分與執行環境的控制權。

已部署的 Studio 可讓本機開發環境以外的協作者使用 Editor。

📹 觀看

觀看 Mastra Editor 工作坊，跟著導覽逐步操作。

何時使用 Editor

當 Agent 以程式碼定義，但負責其行為的人不應編輯程式碼庫時，請使用 Editor。它適合指示或 Tool 經常變動，且必須在提供給使用者前測試的情境。若所有變更皆由開發者負責，且 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 儲存區。

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。協作者可依 Editor 權限更新 Agent 的指示與 Tool。

使用資料庫 Storage 時，可將變更儲存為草稿進行測試，而不影響上線中的 Agent。準備就緒後再發布草稿。

指示

Instructions 區段會顯示程式碼中定義的 Agent 系統提示詞。協作者可以覆寫該提示詞或新增指示區塊。

指示區塊可以包含目前請求中的值。例如，{{userName}} 會插入透過請求內容提供的名稱。顯示條件可讓區塊只對特定客戶、角色或功能旗標顯示。

提示詞區塊

提示詞區塊是一段已儲存的指示文字，可供多個 Agent 使用。請在 Prompts 下建立並發布區塊，接著開啟 Agent 的 Instructions 區段，再選取 Add block。

例如，客服、退貨與訂單狀態 Agent 可能都需要使用相同的退款政策。將政策儲存為提示詞區塊，再加入各個 Agent。政策變更時，只要更新並發布該區塊一次，不必逐一編輯三個 Agent。

提示詞區塊變更後，所有參照其已發布版本的 Agent 都會收到更新。草稿變更只會在預覽時使用，因此在區塊發布前不會影響上線中的 Agent。

範本語法、條件、版本與 API 的詳細資訊，請參閱提示詞區塊參考資料。

Tool

Tool 可讓 Agent 執行動作。協作者可以從 Editor 提供的 Tool 中選擇，但無法在 Studio 中實作新的 Tool。Tool 的來源會決定其提供方式：

• 專案 Tool 必須由開發者在 Mastra 專案中實作並註冊。
• 整合 Tool 會在開發者註冊 Composio 或 Arcade 等 Provider 後提供。協作者接著可以瀏覽 Provider 的目錄並新增 Tool，不必先在程式碼中逐一加入。
• MCP Tool 會在設定 MCP 用戶端後提供。具備存取權的協作者可以在 Studio 中建立用戶端，再從其伺服器公開的 Tool 中選擇。

協作者可以在 Agent 的 Tools 區段中加入所需的 Tool，或針對該 Agent 改寫 Tool 的說明。更明確的說明能協助 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 金鑰註冊 Provider，即可在 Editor 中使用其 Tool 目錄：

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 金鑰進行註冊：

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 用戶端，並將其 Tool 加入 Agent。已儲存的用戶端可以啟動本機 stdio 伺服器，或連線至遠端 HTTP 伺服器。Tool 篩選器可讓每個 Agent 只使用該伺服器中所需的 Tool。

MCP 設定、條件、篩選與解析順序的詳細資訊，請參閱 Editor Tool 參考資料。Provider 選項請參閱 ToolProvider。

決定協作者可編輯的內容

協作者預設可以變更 Agent 的指示並管理其 Tool，包括 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 允許協作者變更指示，並改善已附加 Tool 的說明，但無法新增或移除 Tool。

editor 值	協作者可變更的內容
省略	指示、Tool 與 Tool 說明
false	無
{ instructions: true }	指示
{ tools: true }	Tool 與 Tool 說明
{ tools: { description: true } }	已在程式碼中加入的 Tool 說明

Studio 會將其他所有內容顯示為唯讀。完整設定請參閱 Editor 覆寫。

選擇變更的儲存位置

Editor 可以將變更儲存在已設定的資料庫中，也能存成程式碼庫內的檔案。

資料庫 Storage

資料庫是預設選項。Editor 會使用 Mastra 執行個體上設定的 Storage，因此應用程式與 Editor 可以共用相同的後端。

若要讓 Editor 資料使用獨立後端，請設定 MastraCompositeStore 的 editor 選項。未明確指定路由的 Storage 網域仍會使用其 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(),
})

程式碼庫檔案

使用程式碼來源，將覆寫內容與應用程式程式碼存放在一起。開發者可以在提取要求中檢閱檔案，並隨應用程式一起部署：

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 的模型、名稱與其他由程式碼管理的欄位會保留在 TypeScript 檔案中。Mastra 會讀取 JSON，並在 Agent 執行時套用這些值。

協作者在 Studio 中儲存時，可以將檔案寫入本機檔案系統或下載檔案。若已整合原始碼控制，Studio 也可以改為建立提取要求，再由 Git 提供檢閱與版本歷程記錄。

檔案位置與來源選項請參閱 MastraEditor。

版本管理

以資料庫為後端的 Agent 與提示詞區塊會使用草稿和已發布版本。儲存會建立草稿，而上線中的 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 測試中比較兩個版本。
• 在向所有人發布前，先讓一小群人使用草稿。
• 讓正式環境維持使用已發布版本，同時讓預備環境使用最新草稿。
• 將客戶固定在特定版本。

監督 Agent 呼叫子 Agent 時，也可使用相同的版本控制。開發者可以測試子 Agent 的草稿，而不必變更系統的其他部分。

版本選擇、子 Agent 行為、REST 端點與 SDK 方法的詳細資訊，請參閱 Editor 版本管理參考資料。

程式化存取

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."
  }'

預設的伺服器前綴為 /api。開發者可以在伺服器設定中自訂前綴。

可用操作請參閱 MastraEditor 命名空間與 Client SDK Agent API。

後續步驟

• MastraEditor 參考資料
• 提示詞區塊參考資料
• Editor Tool 參考資料
• Editor 版本管理參考資料