> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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/reference/core/mastra-class) 实例上。你可以用它将 Mastra Code Agent 提供给自己的 UI（Web 应用、编辑器、Bot）：每个客户端都通过返回的 [`AgentController`](https://mastra.zisheng.pro/reference/agent-controller/agent-controller-class) 创建或恢复各自隔离的 Session。

如需自行构造 `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`，可将 Controller 挂载到已经托管其他原语的 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 之前的无状态 Input 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、命令、数据库、Skill、Agent 指令）使用的配置目录名称。 (Default: `'.mastracode'`)

**mcpServers** (`Record<string, McpServerConfig>`): 以编程方式配置 MCP Server；会与基于文件的配置合并，并覆盖后者。

**buildApiRoutes** (`(deps: { controller, authStorage }) => ApiRoute[]`): 在构造的 Mastra 上注册的额外 API Route。提供 mastra 时忽略此项。

**buildServerConfig** (`(deps: { controller, authStorage }) => ServerConfig`): 合并到所构造 Mastra 的额外 Server 配置（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/reference/agent-controller/agent-controller-class)
- [Session 类](https://mastra.zisheng.pro/reference/agent-controller/session)