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

# AgentController

> **Beta:** `AgentController` 功能目前处于 beta 阶段。在正式脱离 beta 状态之前，次要版本中可能会包含破坏性变更。

`AgentController` 类是一个共享宿主，可承载一个或多个 [`Session`](https://mastra.zisheng.pro/reference/agent-controller/session) 实例。初始化控制器并创建 Session 后，使用 `session.*` API 管理对话状态和运行控制。

有关引导式介绍，请参阅 [AgentController 概述](https://mastra.zisheng.pro/docs/harness/agent-controller)。

## 用法示例

以下示例初始化控制器并创建 Session。它会在发送消息之前订阅 Session 事件。

```typescript
import { Agent } from '@mastra/core/agent'
import { AgentController } from '@mastra/core/agent-controller'
import { Workspace } from '@mastra/core/workspace'

const agent = new Agent({
  id: 'coding-agent',
  name: 'Coding agent',
  instructions: 'Help with software engineering tasks.',
  model: 'anthropic/claude-sonnet-4-6',
})

const controller = new AgentController({
  id: 'coding-controller',
  agent,
  workspace: new Workspace({ id: 'coding-workspace' }),
  modes: [{ id: 'build', name: 'Build', metadata: { default: true } }],
})

await controller.init()

const session = await controller.createSession({ resourceId: 'project-42' })
const unsubscribe = session.subscribe(event => {
  if (event.type === 'message_update') {
    console.log(event.message)
  }
})

await session.sendMessage({ content: 'Review the project structure.' })
unsubscribe()
```

## 构造函数参数

**id** (`string`): 唯一的控制器标识符。它也是默认的 Session 和资源标识符。

**modes** (`AgentControllerMode[]`): 每个 Session 可用的模式定义。至少需要一种模式。

**modes.id** (`string`): 唯一的模式标识符。

**modes.name** (`string`): 显示名称。

**modes.defaultModelId** (`string`): Session 在没有已存储选择的情况下进入此模式时选用的模型。

**modes.description** (`string`): 模式选择器中显示的文本。

**modes.instructions** (`string`): 此模式叠加在后端 Agent 指令之上的指令。

**modes.transitionsTo** (`string`): 批准 submit\_plan 暂停后进入的模式。

**modes.availableTools** (`string[]`): 公开 Tool 名称的允许列表。空数组会在此模式下隐藏所有 Tool。

**modes.metadata** (`Record<string, unknown>`): 透传的模式元数据。metadata.default: true 用于标记默认模式。

**modes.tools** (`ToolsInput`): 模式 Tool。与 additionalTools 互斥。

**modes.additionalTools** (`ToolsInput`): 添加到后端 Agent Tool 中的 Tool。与 tools 互斥。

**modes.agent** (`Agent`): 已弃用的模式专用 Agent。请使用顶层 agent 参数。

**modes.default** (`boolean`): 已弃用的默认标记。请使用 metadata.default 或 defaultModeId。

**agent** (`Agent`): 已配置模式使用的共享后端 Agent。

**resourceId** (`string`): Session 和线程的默认资源标识符。默认为 id。

**storage** (`MastraCompositeStore`): 用于持久化线程、消息、设置和可恢复运行数据的存储。

**stateSchema** (`PublicSchema<TState, any>`): 用于验证 session.state 更新的 schema。

**initialState** (`Partial<TState>`): 为每个新 Session 与 schema 默认值合并的初始状态。

**memory** (`DynamicArgument<MastraMemory>`): 与未自行定义 memory 的后端 Agent 共享的 memory 实例。

**defaultModeId** (`string`): 默认模式标识符。其优先级高于模式元数据。

**instructions** (`string`): 与当前模式指令叠加的控制器指令。

**tools** (`DynamicArgument<ToolsInput | undefined>`): 控制器运行共享且可供已配置子 Agent 使用的 Tool。

**workspace** (`DynamicArgument<Workspace | undefined>`): 静态 Workspace 或按 Session 创建 Workspace 的工厂。Session 必须解析出有效的 Workspace。

**browser** (`DynamicArgument<MastraBrowser | undefined>`): 静态浏览器或按 Session 创建浏览器的工厂。

**channels** (`AgentControllerChannelsConfig`): 用于将频道线程路由到控制器 Session 的聊天频道配置。

**intervalHandlers** (`IntervalHandler[]`): 由 init() 启动、由 stopIntervals() 或 destroy() 停止的周期处理程序。

**idGenerator** (`() => string`): 用于线程、消息和信号的自定义标识符生成器。

**modelUseCountProvider** (`ModelUseCountProvider`): 返回用于对可用模型排序的模型使用次数。

**modelUseCountTracker** (`ModelUseCountTracker`): 在 session.model.switch() 后记录模型选择。

**subagents** (`AgentControllerSubagent[]`): 通过内置 subagent Tool 公开的子 Agent 类型。

**subagents.id** (`string`): 唯一的子 Agent 类型标识符。

**subagents.name** (`string`): 显示名称。

**subagents.description** (`string`): 生成的 Tool 所使用的描述。

**subagents.instructions** (`DynamicArgument<AgentInstructions>`): 子 Agent 指令。

**subagents.tools** (`ToolsInput`): 子 Agent 拥有的 Tool。

**subagents.allowedControllerTools** (`string[]`): 添加到子 Agent Tool 中的控制器 Tool ID。

**subagents.allowedWorkspaceTools** (`string[]`): 对子 Agent 可见的 Workspace Tool 名称。

**subagents.defaultModelId** (`string`): 默认子 Agent 模型。

**subagents.maxSteps** (`number`): 最大执行步数。

**subagents.stopWhen** (`LoopOptions["stopWhen"]`): 循环停止条件。

**subagents.forked** (`boolean`): 子 Agent 默认是否继承克隆的父线程。

**gateways** (`MastraModelGatewayInterface[]`): 与内置网关合并的自定义模型网关。

**omConfig** (`AgentControllerOMConfig`): 默认观测记忆模型和阈值。

**disableBuiltinTools** (`BuiltinToolId[]`): 要从运行中省略的内置控制器 Tool。

**toolCategoryResolver** (`(toolName: string) => ToolCategory | null`): 将 Tool 名称映射到权限类别。

**pubsub** (`PubSub`): 传播到后端 Agent 的 PubSub 实现。

**threadLock** (`{ acquire: (threadId: string) => void | Promise<void>; release: (threadId: string) => void | Promise<void> }`): 用于协调线程所有权的锁实现。

**observability** (`ObservabilityEntrypoint`): 独立控制器 Mastra 实例的可观测性配置。

## 属性

**id** (`string`): 传给构造函数的控制器标识符。

## 方法

### Session

#### `createSession(options)`

获取或创建为 `(resourceId, scope)` 组合注册的实时 Session。请先调用 `init()`。

```typescript
const session = await controller.createSession({
  resourceId: 'project-42',
  scope: 'editor-window-1',
  threadId: 'thread-7',
})
```

相同的 `resourceId` 和 `scope` 会返回同一个 `Session` 实例。不同的作用域会为同一资源创建隔离的 Session。提供 `threadId` 时，该方法会将缓存的 Session 切换到该线程；若线程不存在，则创建它。

**resourceId** (`string`): Memory 资源和实时 Session 注册表键。默认为已配置的 resourceId 或控制器 id。

**scope** (`string`): 可选注册表命名空间，允许一个资源拥有多个实时 Session。

**threadId** (`string`): 要绑定的确切线程。缺失的线程会使用此标识符创建。

**id** (`string`): 稳定的 Session 标识符。默认为控制器 id。

**ownerId** (`string`): 稳定的 Session 所有者标识符。默认为 id。

**tags** (`Record<string, string>`): 复制到 Session 所创建线程的标签。

**workspace** (`Workspace`): 此 Session 的 Workspace 覆盖项。

**browser** (`MastraBrowser`): 此 Session 的浏览器覆盖项。

**requestContext** (`RequestContext`): 用于解析动态 Workspace 和浏览器工厂的上下文。

返回：`Promise<Session<TState>>`

#### `getSessionByResource(resourceId, scope?)`

返回为某个资源和可选作用域注册的实时 Session。

```typescript
const session = await controller.getSessionByResource('project-42', 'editor-window-1')
```

返回：`Promise<Session<TState> | undefined>`

#### `setResourceId(session, { resourceId })`

将实时 Session 移到另一个资源，并清除其活动线程绑定。

```typescript
await controller.setResourceId(session, { resourceId: 'project-43' })
```

#### `getKnownResourceIds(session)`

列出已存储线程中存在的资源标识符。

```typescript
const resourceIds = await controller.getKnownResourceIds(session)
```

返回：`Promise<string[]>`

### 生命周期

#### `init()`

初始化共享存储、Workspace 服务和已配置的周期处理程序。重复调用会复用同一个初始化 Promise。

```typescript
await controller.init()
```

#### `destroy()`

停止控制器拥有的周期处理程序。这不会销毁控制器创建的 Session。

```typescript
await controller.destroy()
```

### 模式和 Agent

#### `listModes()`

返回已配置的模式定义。

```typescript
const modes = controller.listModes()
```

返回：`AgentControllerMode[]`

#### `getCurrentAgent(session)`

返回 Session 活动模式对应的后端 Agent。

```typescript
const agent = controller.getCurrentAgent(session)
```

返回：`Agent`

### Workspace 和浏览器

#### `hasWorkspace()`

报告控制器是否具有静态、动态或基于对象的 Workspace 配置。

```typescript
if (controller.hasWorkspace()) {
  console.log('Workspace configured')
}
```

返回：`boolean`

#### `isWorkspaceReady()`

报告控制器级 Workspace 是否已就绪。

```typescript
const ready = controller.isWorkspaceReady()
```

返回：`boolean`

#### `getWorkspace()`

返回静态控制器 Workspace。动态 Workspace 工厂在解析完成前返回 `undefined`。

```typescript
const workspace = controller.getWorkspace()
```

返回：`Workspace | undefined`

#### `resolveWorkspace({ session, requestContext? })`

为 Session 解析动态 Workspace，并将结果缓存在控制器上。

```typescript
const workspace = await controller.resolveWorkspace({ session, requestContext })
```

返回：`Promise<Workspace | undefined>`

#### `setBrowser(browser)`

替换控制器浏览器，并将其传播到后端 Agent。

```typescript
controller.setBrowser(browser)
```

### Mastra 和频道

#### `getMastra()`

返回父 Mastra 实例或由 `init()` 创建的内部实例。

```typescript
const mastra = controller.getMastra()
```

返回：`Mastra | undefined`

#### `getChannels()`

返回已配置的聊天频道集成。

```typescript
const channels = controller.getChannels()
```

返回：`AgentControllerChannels | null`

### 模型

#### `getCurrentModelAuthStatus(session)`

返回 Session 所选模型的身份验证状态。

```typescript
const status = await controller.getCurrentModelAuthStatus(session)
```

返回：`Promise<ModelAuthStatus>`

#### `listAvailableModels()`

列出已配置网关和内置网关中的模型。结果会短暂缓存；配置 `modelUseCountProvider` 后，还会结合使用数据排序。

```typescript
const models = await controller.listAvailableModels()
```

返回：`Promise<AvailableModel[]>`

#### `invalidateAvailableModelsCache()`

清除可用模型缓存。

```typescript
controller.invalidateAvailableModelsCache()
```

### 观测记忆和权限

#### `loadOMProgress(session)`

加载活动线程已存储的观测记忆进度，并发出 `om_status` 事件。

```typescript
await controller.loadOMProgress(session)
```

#### `getObservationalMemoryRecord(session)`

返回活动线程的观测记忆记录。

```typescript
const record = await controller.getObservationalMemoryRecord(session)
```

返回：`Promise<ObservationalMemoryRecord | null>`

#### `getToolCategory({ toolName })`

解析 Tool 的权限类别。

```typescript
const category = controller.getToolCategory({ toolName: 'execute_command' })
```

返回：`ToolCategory | null`

### 周期处理程序

#### `registerInterval(handler)`

启动或替换周期处理程序。

```typescript
controller.registerInterval({
  id: 'refresh',
  intervalMs: 60_000,
  handler: async () => refreshData(),
})
```

#### `removeInterval({ id })`

停止一个周期处理程序并运行其可选关闭回调。

```typescript
await controller.removeInterval({ id: 'refresh' })
```

#### `stopIntervals()`

停止所有周期处理程序并运行其可选关闭回调。

```typescript
await controller.stopIntervals()
```

## 相关内容

- [AgentController 指南](https://mastra.zisheng.pro/docs/harness/agent-controller)
- [Session 参考](https://mastra.zisheng.pro/reference/agent-controller/session)
- [Agent](https://mastra.zisheng.pro/docs/agents/overview)
- [Workspace](https://mastra.zisheng.pro/docs/workspace/overview)
- [频道](https://mastra.zisheng.pro/docs/capabilities/channels/overview)