跳至主要內容

mountAgentControllerOnMastra()

beta

@mastra/code-sdk 套件仍處於實驗階段，次要版本可能包含破壞性變更。

mountAgentControllerOnMastra() 函式會建立 Mastra Code Agent controller（即 mastracode CLI 背後的 Coding Agent，包含其模式、Tool、Memory 與 thread 管理），並將其註冊至伺服器擁有的 Mastra 執行個體。你可以用它將 Mastra Code Agent 提供給自己的 UI（網頁應用程式、編輯器、bot）：每個使用者端都會透過傳回的 AgentController，建立或繼續各自隔離的 session。

若要自行建構 Mastra 執行個體（例如在可部署的進入點檔案中），請使用相同套件中的 prepareAgentControllerMount()；它會傳回建構函式引數與 finalize() callback。

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

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，將 controller 掛載至已託管其他 primitive 的 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 執行個體。省略時，會建立擁有 controller storage 的 Mastra。

controllerId?:

string
在 Mastra 執行個體上註冊 controller 時使用的 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 manager 的行為。observer 錯誤會寫入記錄，不會讓成功的 Tool 呼叫失敗。

inputProcessors?:

InputProcessor[]
前置於 Mastra Code 必要安全性及相容性 processor 的無狀態輸入 processor。自訂 processor 會擴充 pipeline，但無法取代內建 processor。

disabledTools?:

string[]
提供給模型前，從動態 Tool 集合移除的 Tool。

storage?:

StorageConfig
用來取代自動偵測預設值的自訂 storage 設定。

workspace?:

AgentControllerConfig["workspace"]
= local filesystem + local sandbox based on the detected project
覆寫 Workspace。

configDir?:

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

mcpServers?:

Record<string, McpServerConfig>
程式化 MCP 伺服器設定，會與檔案式設定合併並加以覆寫。

buildApiRoutes?:

(deps: { controller, authStorage }) => ApiRoute[]
在建構的 Mastra 上註冊其他 API route。提供 mastra 時會忽略此欄位。

buildServerConfig?:

(deps: { controller, authStorage }) => ServerConfig
合併至所建構 Mastra 的其他伺服器設定（middleware、CORS）。提供 mastra 時會忽略此欄位。

傳回值
「傳回值」的直接連結

mastra:

Mastra
掛載 controller 的 Mastra 執行個體（新建或傳入）。

controller:

AgentController
已初始化的 Mastra Code Agent controller。使用 controller.createSession() 建立 session。

authStorage:

AuthStorage
內建模型 Gateway 使用的認證 storage。
On this page