AgentController

beta

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

AgentController 类是一个共享宿主，可承载一个或多个 Session 实例。初始化控制器并创建 Session 后，使用 session.* API 管理对话状态和运行控制。

有关引导式介绍，请参阅 AgentController 概述。

用法示例

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

src/mastra/agent-controller.ts

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 可用的模式定义。至少需要一种模式。

AgentControllerMode

id:

string

唯一的模式标识符。

name?:

string

显示名称。

defaultModelId?:

string

Session 在没有已存储选择的情况下进入此模式时选用的模型。

description?:

string

模式选择器中显示的文本。

instructions?:

string

此模式叠加在后端 Agent 指令之上的指令。

transitionsTo?:

string

批准 submit_plan 暂停后进入的模式。

availableTools?:

string[]

公开 Tool 名称的允许列表。空数组会在此模式下隐藏所有 Tool。

metadata?:

Record<string, unknown>

透传的模式元数据。metadata.default: true 用于标记默认模式。

tools?:

ToolsInput

模式 Tool。与 additionalTools 互斥。

additionalTools?:

ToolsInput

添加到后端 Agent Tool 中的 Tool。与 tools 互斥。

agent?:

Agent

已弃用的模式专用 Agent。请使用顶层 agent 参数。

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 类型。

AgentControllerSubagent

id:

string

唯一的子 Agent 类型标识符。

name:

string

显示名称。

description:

string

生成的 Tool 所使用的描述。

instructions:

DynamicArgument<AgentInstructions>

子 Agent 指令。

tools?:

ToolsInput

子 Agent 拥有的 Tool。

allowedControllerTools?:

string[]

添加到子 Agent Tool 中的控制器 Tool ID。

allowedWorkspaceTools?:

string[]

对子 Agent 可见的 Workspace Tool 名称。

defaultModelId?:

string

默认子 Agent 模型。

maxSteps?:

number

最大执行步数。

stopWhen?:

LoopOptions["stopWhen"]

循环停止条件。

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()。

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。

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

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

setResourceId(session, { resourceId })

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

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

getKnownResourceIds(session)

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

const resourceIds = await controller.getKnownResourceIds(session)

返回：Promise<string[]>

生命周期

init()

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

await controller.init()

destroy()

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

await controller.destroy()

模式和 Agent

listModes()

返回已配置的模式定义。

const modes = controller.listModes()

返回：AgentControllerMode[]

getCurrentAgent(session)

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

const agent = controller.getCurrentAgent(session)

返回：Agent

Workspace 和浏览器

hasWorkspace()

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

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

返回：boolean

isWorkspaceReady()

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

const ready = controller.isWorkspaceReady()

返回：boolean

getWorkspace()

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

const workspace = controller.getWorkspace()

返回：Workspace | undefined

resolveWorkspace({ session, requestContext? })

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

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

返回：Promise<Workspace | undefined>

setBrowser(browser)

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

controller.setBrowser(browser)

Mastra 和频道

getMastra()

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

const mastra = controller.getMastra()

返回：Mastra | undefined

getChannels()

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

const channels = controller.getChannels()

返回：AgentControllerChannels | null

模型

getCurrentModelAuthStatus(session)

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

const status = await controller.getCurrentModelAuthStatus(session)

返回：Promise<ModelAuthStatus>

listAvailableModels()

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

const models = await controller.listAvailableModels()

返回：Promise<AvailableModel[]>

invalidateAvailableModelsCache()

清除可用模型缓存。

controller.invalidateAvailableModelsCache()

观测记忆和权限

loadOMProgress(session)

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

await controller.loadOMProgress(session)

getObservationalMemoryRecord(session)

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

const record = await controller.getObservationalMemoryRecord(session)

返回：Promise<ObservationalMemoryRecord | null>

getToolCategory({ toolName })

解析 Tool 的权限类别。

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

返回：ToolCategory | null

周期处理程序

registerInterval(handler)

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

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

removeInterval({ id })

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

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

stopIntervals()

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

await controller.stopIntervals()

相关内容

• AgentController 指南
• Session 参考
• Agent
• Workspace
• 频道