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

# mountAgentControllerOnMastra()

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

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

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

## 使用範例

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

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

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

**disabledTools** (`string[]`): 提供給模型前，從動態 Tool 集合移除的 Tool。

**storage** (`StorageConfig`): 用來取代自動偵測預設值的自訂 storage 設定。

**workspace** (`AgentControllerConfig["workspace"]`): 覆寫 Workspace。 (Default: `local filesystem + local sandbox based on the detected project`)

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

**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。

## 相關內容

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