> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# mountAgentControllerOnMastra()

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

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

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

## 使用範例

```typescript
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 實例：

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

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

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

## 參數

**cwd** (`string`): 用於偵測項目的工作目錄。 (Default: `process.cwd()`)

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

**controllerId** (`string`): 在 Mastra 實例上註冊控制器時所使用的 ID。

**modes** (`AgentControllerMode[]`): 覆寫 Agent 模式（模型 ID、顏色及可用模式）。 (Default: `build/plan/fast`)

**subagents** (`AgentControllerSubagent[]`): 覆寫或擴充 subagent 定義。 (Default: `explore/plan/execute`)

**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"]`): 覆寫 Workspace。 (Default: `根據偵測到的項目，使用本機檔案系統及本機 Sandbox`)

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

**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`): 內置模型閘道使用的憑證儲存空間。

## 相關內容

- [AgentController 類別](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/agent-controller-class)
- [Session 類別](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/session)