跳至主要內容

MastraEditor 類別

MastraEditor 類別用於設定 Editor 系統。將它傳給 Mastra constructor，即可啟用 prompt block、Agent 代碼覆寫、版本控制及 Tool Provider 等 Editor 功能。

Editor 功能簡介請參閱 Editor。

使用範例
使用範例 的直接連結

src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { MastraEditor } from '@mastra/editor'

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

Constructor 參數
Constructor 參數 的直接連結

logger?:

Logger
Logger 實例。如未設定，則改用 Mastra 實例的 logger。

toolProviders?:

Record<string, ToolProvider>
= {}
以 ID 為鍵的整合 Tool Provider（例如 Composio 或 Arcade），讓 Agent 使用透過 Editor 加入的第三方 Tool。

processorProviders?:

Record<string, ProcessorProvider>
= {}
用於可配置 input/output 處理的 processor Provider（例如內容審核或 token 限制）。內置 Provider 一律包括在內。

filesystems?:

Record<string, FilesystemProvider>
= {}
用於檔案存取的檔案系統 Provider（例如 S3 或 GCS）。一律包括本機檔案系統 Provider。

sandboxes?:

Record<string, SandboxProvider>
= {}
用於執行代碼的 Sandbox Provider（例如 E2B）。一律包括本機 Sandbox Provider。

blobStores?:

Record<string, BlobStoreProvider>
= {}
用於二進制資料的 blob storage Provider（例如 S3）。如未指定 Provider，則改用 Mastra storage blob store。

browsers?:

Record<string, BrowserProvider>
= {}
供 Agent 存取瀏覽器的 Browser Provider（例如 Stagehand）。沒有內置 Provider；啟用 builder.features.agent.browser 時必須提供。Provider 介面請參閱 BrowserProvider 參考。

builder?:

AgentBuilderOptions
Agent Builder 配置。請參閱 AgentBuilderOptions 參考。省略此項或設定 enabled: false 可停用 Builder。

source?:

'code' | 'db'
= 'db'
Agent 覆寫的儲存位置。使用 'db' 時，覆寫位於已配置的儲存後端，而 Studio 會顯示儲存及發佈流程。使用 'code' 時，覆寫以每個 Agent 一個 JSON 檔案的形式儲存在磁碟（透過本機 FilesystemStore route），而 Studio 會顯示檔案系統操作。兩者差異請參閱 Editor 儲存選項。

codePath?:

string
= './mastra/editor/'
'code' 來源用來儲存每個 Agent JSON 檔案的目錄。來源不是 'code' 時會忽略。

Provider 介面
Provider 介面 的直接連結

以上每個 Provider 欄位都接受以 Provider id 為鍵的記錄。實作結構請參閱各 Provider 的參考頁面：

Agent Builder
Agent Builder 的直接連結

builder 欄位會啟用 Agent Builder，這是用來建立及編輯已儲存 Agent 的瀏覽器 UI。請參閱：

註冊 Builder Agent
註冊 Builder Agent 的直接連結

Builder UI 會使用由 @mastra/editor/ee 的 createBuilderAgent() factory 建立的 Agent。匯入並呼叫 factory，然後在 Mastra 實例的 agents 下註冊傳回的 Agent：

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

export const mastra = new Mastra({
  agents: { builderAgent: createBuilderAgent() },
  editor: new MastraEditor({
    builder: { enabled: true },
  }),
})

鍵名（builderAgent）只是慣例，任何鍵均可使用。@mastra/editor/ee subpath 在執行階段受 Mastra Enterprise Edition 授權限制。

完整設定清單請參閱 Agent Builder 概覽。

Namespace
Namespace 的直接連結

Editor 提供 namespace 來管理不同 entity 類型。你可在任何 Mastra 實例透過 mastra.getEditor() 存取它們，並在應用程式代碼中直接呼叫 CRUD 方法；亦可使用在內部呼叫這些方法的 Mastra 伺服器 route。

所有 namespace 都擴充共用的 CRUD 基礎類別，因此會提供相同的 create、getById、update、delete、list、listResolved 及 clearCache 方法。以下各 namespace 的屬性表亦會記錄任何額外方法。

agent:

EditorAgentNamespace
已儲存 Agent 的 CRUD 操作及版本管理，負責將已儲存覆寫套用至以代碼定義的 Agent。
EditorAgentNamespace

create:

(input: StorageCreateAgentInput) => Promise<Agent>
建立新的已儲存 Agent，並傳回已 hydrate 的 Agent 實例。接受 id、authorId、metadata 及初始 snapshot（name、description、instructions、model、tools、memory 等）。

getById:

(id: string, options?: GetByIdOptions) => Promise<Agent | null>
為已儲存 Agent 傳回已 hydrate 的 Agent 實例。傳入包含 versionId、versionNumber 或 status（"draft" | "published" | "archived"）的選項以指定版本。預設版本請求會被快取。

update:

(input: StorageUpdateAgentInput) => Promise<Agent>
局部更新已儲存 Agent。從提供的 snapshot 欄位建立版本、指派給 activeVersionId，並令快取失效。將 memory 設為 null 可停用 memory。

delete:

(id: string) => Promise<void>
刪除已儲存 Agent，並將它從 Mastra 執行階段 registry 移除。

list:

(args?: StorageListAgentsInput) => Promise<StorageListAgentsOutput>
列出已儲存 Agent，並可選擇使用分頁、orderBy、authorId 及 metadata 篩選。傳回原始已儲存 snapshot。

listResolved:

(args?: StorageListAgentsInput) => Promise<StorageListAgentsResolvedOutput>
與 list 相同，但會傳回引用已解除參照的完整解析配置。

applyStoredOverrides:

(agent: Agent, options?: { versionId?: string; status?: "draft" | "published" }) => Promise<Agent>
原地修改以代碼定義的 Agent，以套用任何已儲存覆寫（instructions、tools、variables）。由 mastra.getAgent() 在內部呼叫，你很少需要直接呼叫它。

clone:

(agent: Agent, options: { newId: string; newName?: string; metadata?: Record<string, unknown>; authorId?: string; requestContext?: RequestContext; }) => Promise<Agent>
複製現有 Agent，以建立新的已儲存 Agent。

clearCache:

(agentId?: string) => void
清除一個或所有 Agent 的記憶體內快取。變更後會自動呼叫。

prompt:

EditorPromptNamespace
Prompt block 的 CRUD 操作，包括以 draft 內容解析 instruction block 的 preview 方法。
EditorPromptNamespace

create:

(input: StorageCreatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>
建立新的已儲存 prompt block。接受 id、authorId、metadata 及初始 snapshot（name、description、content、rules、requestContextSchema）。

getById:

(id: string, options?: GetByIdOptions) => Promise<StorageResolvedPromptBlockType | null>
傳回已解析的 prompt block。傳入選項以指定版本或狀態。

update:

(input: StorageUpdatePromptBlockInput) => Promise<StorageResolvedPromptBlockType>
局部更新已儲存 prompt block。使用提供的 snapshot 欄位建立新 draft 版本。

delete:

(id: string) => Promise<void>
刪除已儲存 prompt block，並將它從 Mastra 執行階段 registry 移除。

list:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksOutput>
列出已儲存 prompt block，並可選擇使用分頁、orderBy、authorId、metadata 及 status 篩選。

listResolved:

(args?: StorageListPromptBlocksInput) => Promise<StorageListPromptBlocksResolvedOutput>
與 list 相同，但會傳回完整解析的 prompt block 內容。

preview:

(blocks: AgentInstructionBlock[], context: Record<string, unknown>) => Promise<string>
根據 context 解析 instruction block 陣列、呈現 template 變數及評估顯示條件。包括所引用 prompt block 的 draft 內容。

clearCache:

(id?: string) => void
清除一個或所有 prompt block 的記憶體內快取。

mcp:

EditorMCPNamespace
已儲存 MCP client 配置的 CRUD 操作。
EditorMCPNamespace

create:

(input: StorageCreateMCPClientInput) => Promise<MCPClient>
建立新的已儲存 MCP client。接受 id、authorId、metadata 及初始 snapshot（servers、Tool 篩選）。

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPClient | null>
為已儲存 MCP client 傳回已 hydrate 的 MCPClient 實例。

update:

(input: StorageUpdateMCPClientInput) => Promise<MCPClient>
局部更新已儲存 MCP client，並令快取失效。

delete:

(id: string) => Promise<void>
刪除已儲存 MCP client，並將它從 Mastra 執行階段 registry 移除。

list:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsOutput>
列出已儲存 MCP client，並可選擇使用分頁及篩選。

listResolved:

(args?: StorageListMCPClientsInput) => Promise<StorageListMCPClientsResolvedOutput>
與 list 相同，但會傳回完整解析的 MCP client 配置。

clearCache:

(id?: string) => void
清除一個或所有 MCP client 的記憶體內快取。

mcpServer:

EditorMCPServerNamespace
MCP 伺服器配置的 CRUD 操作。
EditorMCPServerNamespace

create:

(input: StorageCreateMCPServerInput) => Promise<MCPServerBase>
建立新的已儲存 MCP 伺服器配置，並傳回已 hydrate 的伺服器實例。

getById:

(id: string, options?: GetByIdOptions) => Promise<MCPServerBase | null>
傳回指定 id 的已 hydrate MCP 伺服器。

update:

(input: StorageUpdateMCPServerInput) => Promise<MCPServerBase>
局部更新已儲存 MCP 伺服器配置。

delete:

(id: string) => Promise<void>
刪除已儲存 MCP 伺服器配置。

list:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersOutput>
列出已儲存 MCP 伺服器配置。

listResolved:

(args?: StorageListMCPServersInput) => Promise<StorageListMCPServersResolvedOutput>
與 list 相同，但會傳回完整解析的伺服器配置。

clearCache:

(id?: string) => void
清除一個或所有 MCP 伺服器的記憶體內快取。

scorer:

EditorScorerNamespace
Scorer 配置的 CRUD 操作。
EditorScorerNamespace

create:

(input: StorageCreateScorerInput) => Promise<MastraScorer>
建立新的已儲存 scorer，並傳回已 hydrate 的 MastraScorer 實例。

getById:

(id: string, options?: GetByIdOptions) => Promise<MastraScorer | null>
傳回指定 id 的已 hydrate scorer。

update:

(input: StorageUpdateScorerInput) => Promise<MastraScorer>
局部更新已儲存 scorer。

delete:

(id: string) => Promise<void>
刪除已儲存 scorer，並將它從 Mastra 執行階段 registry 移除。

list:

(args?: StorageListScorersInput) => Promise<StorageListScorersOutput>
列出已儲存 scorer，並可選擇使用分頁及篩選。

listResolved:

(args?: StorageListScorersInput) => Promise<StorageListScorersResolvedOutput>
與 list 相同，但會傳回完整解析的 scorer 配置。

clearCache:

(id?: string) => void
清除一個或所有 scorer 的記憶體內快取。

Agent namespace 範例
Agent namespace 範例 的直接連結

為現有以代碼定義的 Agent 建立已儲存覆寫：

src/scripts/seed-agent.ts
import { mastra } from '../mastra'

const editor = mastra.getEditor()!

await editor.agent.create({
  id: 'support-agent',
  instructions: 'You are a friendly support agent for Acme.',
  tools: {
    search_kb: { description: 'Search the Acme knowledge base' },
  },
})

方法
方法 的直接連結

存取 Provider
存取 Provider 的直接連結

getToolProvider(id)
gettoolproviderid 的直接連結

按 ID 傳回已註冊的 Tool Provider。

const composio = mastra.getEditor()?.getToolProvider('composio')

getToolProviders()
gettoolproviders 的直接連結

以 Record<string, ToolProvider> 傳回所有已註冊的 Tool Provider。

getProcessorProvider(id)
getprocessorproviderid 的直接連結

按 ID 傳回已註冊的 processor Provider。

getProcessorProviders()
getprocessorproviders 的直接連結

傳回所有已註冊的 processor Provider。

getFilesystemProviders()
getfilesystemproviders 的直接連結

傳回所有已註冊的檔案系統 Provider。

getSandboxProviders()
getsandboxproviders 的直接連結

傳回所有已註冊的 Sandbox Provider。

getBlobStoreProviders()
getblobstoreproviders 的直接連結

傳回所有已註冊的 blob store Provider。

來源
來源 的直接連結

getSource()
getsource 的直接連結

傳回已配置的來源（'code' 或 'db'）；如果建立 Editor 時未明確指定 source，則傳回 undefined。

const source = mastra.getEditor()?.getSource()

傳回：'code' | 'db' | undefined

省略 source 時，即使 getSource() 傳回 undefined，Editor 仍會使用已配置的資料庫儲存。儲存工作流程請參閱 Editor 儲存選項，啟用及 Git 歷史行為則請參閱代碼來源版本控制。

On this page