Editor

Editor 的運作方式就像 Mastra Agent 的 CMS。協作者無需存取程式碼庫或編寫程式碼，便可在 Studio 更改 Agent 的指示和 Tool。他們可以先測試變更，再正式套用。

TypeScript 定義 Agent 的預設值。Editor 會另行儲存變更，而非更新源程式碼，因此協作者可以改進 Agent，同時開發人員仍可掌控其模型、身分和執行環境。

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

📹 觀看

觀看 Mastra Editor 工作坊，了解完整操作流程。

何時使用 Editor

如果 Agent 在程式碼中定義，但負責其行為的人員不應編輯程式碼庫，便可使用 Editor。若指示或 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 和儲存空間加入 Mastra 實例。你可以重用現有儲存空間，無需加入此處所示的 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 權限更新其指示和 Tool。

使用數據庫儲存空間時，可將變更儲存為草稿以作測試，而不影響正式運行的 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，無需先在程式碼中逐一加入每個 Tool。
• 配置 MCP client 後，便會提供 MCP Tool。具有存取權限的協作者可以在 Studio 建立 client，然後從其伺服器公開的 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 的 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 client

協作者也可在 Studio 建立可重用的 MCP client，並將其 Tool 加入 Agent。已儲存的 client 可以啟動本機 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 可以將變更儲存在已配置的數據庫，或儲存為程式碼庫中的檔案。

數據庫儲存空間

數據庫選項是預設設定。Editor 使用 Mastra 實例上配置的儲存空間，因此應用程式和 Editor 可以共用相同的後端。

如要為 Editor 數據使用獨立後端，請在 MastraCompositeStore 設定 editor 選項。沒有明確路由的儲存空間網域會繼續使用其 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(),
})

程式碼庫檔案

使用程式碼來源，將覆寫內容與應用程式碼一同保存。開發人員可以在 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 的模型、名稱和其他由程式碼管理的欄位會保留在其 TypeScript 檔案中。Mastra 會讀取 JSON，並在 Agent 運行時套用這些值。

協作者在 Studio 儲存時，可以將檔案寫入本機檔案系統或下載檔案。透過源程式碼控制整合，Studio 可以改為開啟 pull request。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 測試中比較兩個版本。
• 在向所有人發佈前，先讓一小群人使用草稿。
• 讓生產環境繼續使用已發佈版本，同時在預備環境使用最新草稿。
• 將客戶固定在特定版本。

當 supervisor 調用 sub-agent 時，同樣可以使用這些版本控制功能。開發人員可以測試草稿 sub-agent，而不更改系統其他部分。

有關版本選擇、sub-agent 行為、REST endpoint 和 SDK 方法，請參閱 Editor 版本控制參考。

以程式方式存取

Studio 中的所有功能亦可透過 mastra.getEditor()、REST API 或 Client SDK，以程式方式使用。你可以用它編寫大量更新的 script，或透過程式碼為已儲存的配置植入初始數據。它也可支援根據評估結果調整 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 namespace 和 Client SDK Agent API。

下一步

• MastraEditor 參考
• 提示區塊參考
• Editor Tool 參考
• Editor 版本控制參考