跳到主要内容

mountAgentControllerOnMastra()

beta

@mastra/code-sdk 包处于实验阶段，次要版本中可能包含破坏性变更。

mountAgentControllerOnMastra() 函数会构建 Mastra Code Agent Controller（即 mastracode CLI 背后的 Coding Agent，包含其模式、Tool、Memory 和 Thread 管理功能），并将其注册到由服务器持有的 Mastra 实例上。你可以用它将 Mastra Code Agent 提供给自己的 UI（Web 应用、编辑器、Bot）：每个客户端都通过返回的 AgentController 创建或恢复各自隔离的 Session。

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

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。
On this page