跳至主要內容

mountAgentControllerOnMastra()

beta

@mastra/code-sdk 套件屬實驗性質，次要版本可能包含重大變更。

mountAgentControllerOnMastra() 函數會建立 Mastra Code Agent 控制器（即 mastracode CLI 背後的編程 Agent，並包含其模式、Tool、記憶及對話串管理功能），並將其註冊至由伺服器擁有的 Mastra 實例。你可用此函數將 Mastra Code Agent 提供予自己的介面（網頁應用程式、編輯器或機械人）：每個用戶端都可透過傳回的 AgentController，建立或恢復各自獨立的工作階段。

如要自行建構 Mastra 實例（例如在可部署的入口檔案中），請使用同一套件的 prepareAgentControllerMount()。它會傳回建構函數參數及 finalize() 回呼函數。

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

src/mastra/index.ts
import { mountAgentControllerOnMastra } from '@mastra/code-sdk'

const { mastra, controller } = await mountAgentControllerOnMastra({
  cwd: process.cwd(),
})

// Each client drives its own session
const session = await controller.createSession({ resourceId: 'user-123' })

傳入現有的 mastra，即可將控制器掛載至已託管其他基本元件的 Mastra 實例：

import { Mastra } from '@mastra/core/mastra'
import { mountAgentControllerOnMastra } from '@mastra/code-sdk'

const mastra = new Mastra({/* ... */})

const { controller } = await mountAgentControllerOnMastra({ mastra })

參數
參數 的直接連結

cwd?:

string
= process.cwd()
用於偵測項目的工作目錄。

mastra?:

Mastra
要掛載至的現有 Mastra 實例。如省略，系統會建立一個擁有控制器儲存空間的 Mastra。

controllerId?:

string
在 Mastra 實例上註冊控制器時所使用的 ID。

modes?:

AgentControllerMode[]
= build/plan/fast
覆寫 Agent 模式（模型 ID、顏色及可用模式）。

subagents?:

AgentControllerSubagent[]
= explore/plan/execute
覆寫或擴充 subagent 定義。

extraTools?:

Record<string, ToolAction> | (ctx) => Record<string, ToolAction>
合併至動態 Tool 集合的額外 Tool。

postToolObserver?:

(context: ToolAfterHookContext) => void | Promise<void>
觀察已完成的 Tool 呼叫，而不會取代 Tool 或改變 hook 管理器的行為。觀察器錯誤會記錄至日誌，亦不會令成功的 Tool 呼叫失敗。

inputProcessors?:

InputProcessor[]
加插在 Mastra Code 必要的安全及兼容性處理器之前、沒有狀態的輸入處理器。自訂處理器可擴充處理管道，但不能取代內置處理器。

disabledTools?:

string[]
在向模型公開前，從動態 Tool 集合移除的 Tool。

storage?:

StorageConfig
自訂儲存設定，用以取代自動偵測的預設設定。

workspace?:

AgentControllerConfig["workspace"]
= 根據偵測到的項目，使用本機檔案系統及本機 Sandbox
覆寫 Workspace。

configDir?:

string
= '.mastracode'
覆寫所有項目層級及全域設定路徑（MCP、hook、command、database、Skill、Agent 指令）使用的設定目錄名稱。

mcpServers?:

Record<string, McpServerConfig>
以編程方式設定 MCP 伺服器；這些設定會與檔案式設定合併，並優先於後者。

buildApiRoutes?:

(deps: { controller, authStorage }) => ApiRoute[]
在建構的 Mastra 上註冊額外 API 路由。提供 mastra 時會忽略此項。

buildServerConfig?:

(deps: { controller, authStorage }) => ServerConfig
加入建構的 Mastra 的額外伺服器設定（中介軟件、CORS）。提供 mastra 時會忽略此項。

傳回值
傳回值 的直接連結

mastra:

Mastra
控制器所掛載的 Mastra 實例（新建或傳入的實例）。

controller:

AgentController
已初始化的 Mastra Code Agent 控制器。使用 controller.createSession() 建立工作階段。

authStorage:

AuthStorage
內置模型閘道使用的憑證儲存空間。
On this page