AgentController

beta

AgentController 功能目前處於 Beta 階段；在脫離 Beta 狀態前，minor version 仍可能包含 breaking change。

AgentController 類別是供一或多個 Session instance 使用的共用 host。先初始化 controller 並建立 Session，接著使用 session.* API 管理對話 state 與 run。

引導式介紹請參閱 AgentController 概觀。

使用範例

以下範例會初始化 controller 並建立 Session。它會先訂閱 Session event，再傳送訊息。

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

Constructor 參數

id:

string

不重複的 controller 識別碼，也是預設的 Session 與 resource 識別碼。

modes:

AgentControllerMode[]

每個 Session 都可使用的 mode 定義。至少需要一個 mode。

AgentControllerMode

id:

string

不重複的 mode 識別碼。

name?:

string

顯示名稱。

defaultModelId?:

string

Session 進入此 mode 且沒有已儲存的選擇時，選用的模型。

description?:

string

顯示於 mode selector 的文字。

instructions?:

string

在此 mode 中疊加於底層 Agent instructions 之上的 instructions。

transitionsTo?:

string

核准 submit_plan suspension 後進入的 mode。

availableTools?:

string[]

公開 Tool 名稱的 allowlist。空陣列會在此 mode 隱藏所有 Tool。

metadata?:

Record<string, unknown>

直接傳遞的 mode metadata。metadata.default: true 會標示預設 mode。

tools?:

ToolsInput

Mode Tool。不能與 additionalTools 同時使用。

additionalTools?:

ToolsInput

加入底層 Agent Tool 的 Tool。不能與 tools 同時使用。

agent?:

Agent

已棄用的 mode 專用 Agent。請使用頂層 agent 參數。

default?:

boolean

已棄用的預設標記。請使用 metadata.default 或 defaultModeId。

agent?:

Agent

設定的 mode 所使用的共用底層 Agent。

resourceId?:

string

Session 與 thread 的預設 resource 識別碼。預設為 id。

storage?:

MastraCompositeStore

用於持久化 thread、訊息、設定與可恢復 run 資料的 Storage。

stateSchema?:

PublicSchema<TState, any>

用於驗證 session.state 更新的 schema。

initialState?:

Partial<TState>

每個新 Session 都會與 schema 預設值合併的初始 state。

memory?:

DynamicArgument<MastraMemory>

與未定義自身 Memory 的底層 Agent 共用的 Memory instance。

defaultModeId?:

string

預設 mode 識別碼，優先於 mode metadata。

instructions?:

string

與目前 mode instructions 疊加的 controller instructions。

tools?:

DynamicArgument<ToolsInput | undefined>

controller run 共用，且設定的 subagent 可使用的 Tool。

workspace?:

DynamicArgument<Workspace | undefined>

靜態 Workspace 或各 Session 專用的 Workspace factory。Session 必須解析到有效的 Workspace。

browser?:

DynamicArgument<MastraBrowser | undefined>

靜態瀏覽器或各 Session 專用的瀏覽器 factory。

channels?:

AgentControllerChannelsConfig

用於將 Channel thread 路由至 controller Session 的聊天 Channel 設定。

intervalHandlers?:

IntervalHandler[]

由 init() 啟動，並由 stopIntervals() 或 destroy() 停止的週期性 handler。

idGenerator?:

() => string

用於 thread、訊息與 signal 的自訂識別碼 generator。

modelUseCountProvider?:

ModelUseCountProvider

傳回用於排序可用模型的模型使用次數。

modelUseCountTracker?:

ModelUseCountTracker

在 session.model.switch() 後記錄模型選擇。

subagents?:

AgentControllerSubagent[]

透過內建 subagent Tool 公開的 subagent 型別。

AgentControllerSubagent

id:

string

不重複的 subagent 型別識別碼。

name:

string

顯示名稱。

description:

string

產生的 Tool 所使用的 description。

instructions:

DynamicArgument<AgentInstructions>

Subagent instructions。

tools?:

ToolsInput

Subagent 擁有的 Tool。

allowedControllerTools?:

string[]

加入 subagent Tool 的 controller Tool ID。

allowedWorkspaceTools?:

string[]

subagent 可見的 Workspace Tool 名稱。

defaultModelId?:

string

預設 subagent 模型。

maxSteps?:

number

最大執行 step 數。

stopWhen?:

LoopOptions["stopWhen"]

迴圈停止條件。

forked?:

boolean

subagent 預設是否繼承複製的父 thread。

gateways?:

MastraModelGatewayInterface[]

與內建 gateway 合併的自訂模型 gateway。

omConfig?:

AgentControllerOMConfig

預設的 observational Memory 模型與 threshold。

disableBuiltinTools?:

BuiltinToolId[]

從 run 省略的內建 controller Tool。

toolCategoryResolver?:

(toolName: string) => ToolCategory | null

將 Tool 名稱對應至權限 category。

pubsub?:

PubSub

傳遞至底層 Agent 的 PubSub 實作。

threadLock?:

{ acquire: (threadId: string) => void | Promise<void>; release: (threadId: string) => void | Promise<void> }

用於協調 thread 擁有權的 lock 實作。

observability?:

ObservabilityEntrypoint

獨立 controller Mastra instance 的 Observability 設定。

屬性

id:

string

傳給 constructor 的 controller 識別碼。

方法

Session

createSession(options)

取得或建立為 (resourceId, scope) pair 註冊的即時 Session。呼叫此方法前，請先呼叫 init()。

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

相同的 resourceId 與 scope 會傳回相同的 Session instance。不同 scope 會為同一 resource 建立隔離的 Session。提供 threadId 時，此方法會將快取的 Session 切換至該 thread；如果 thread 不存在，則加以建立。

resourceId?:

string

Memory resource 與即時 Session registry key。預設為設定的 resourceId 或 controller id。

scope?:

string

選填的 registry namespace，讓一項 resource 可有多個即時 Session。

threadId?:

string

要繫結的確切 thread。缺少的 thread 會以此識別碼建立。

id?:

string

穩定的 Session 識別碼。預設為 controller id。

ownerId?:

string

穩定的 Session owner 識別碼。預設為 id。

tags?:

Record<string, string>

複製至 Session 所建立 thread 的 tag。

workspace?:

Workspace

此 Session 的 Workspace override。

browser?:

MastraBrowser

此 Session 的瀏覽器 override。

requestContext?:

RequestContext

用於解析動態 Workspace 與瀏覽器 factory 的 context。

傳回：Promise<Session<TState>>

getSessionByResource(resourceId, scope?)

傳回為 resource 與選填 scope 註冊的即時 Session。

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

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

setResourceId(session, { resourceId })

將即時 Session 移至其他 resource，並清除有效的 thread 繫結。

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

getKnownResourceIds(session)

列出已儲存 thread 中存在的 resource 識別碼。

const resourceIds = await controller.getKnownResourceIds(session)

傳回：Promise<string[]>

生命週期

init()

初始化共用 Storage、Workspace 服務與設定的 interval handler。重複呼叫會重複使用相同的初始化 promise。

await controller.init()

destroy()

停止 controller 擁有的 interval handler。這不會銷毀 controller 建立的 Session。

await controller.destroy()

Mode 與 Agent

listModes()

傳回設定的 mode 定義。

const modes = controller.listModes()

傳回：AgentControllerMode[]

getCurrentAgent(session)

傳回 Session 有效 mode 的底層 Agent。

const agent = controller.getCurrentAgent(session)

傳回：Agent

Workspace 與瀏覽器

hasWorkspace()

回報 controller 是否具有靜態、動態或物件型 Workspace 設定。

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

傳回：boolean

isWorkspaceReady()

回報 controller 層級的 Workspace 是否準備就緒。

const ready = controller.isWorkspaceReady()

傳回：boolean

getWorkspace()

傳回靜態 controller Workspace。動態 Workspace factory 在解析前會傳回 undefined。

const workspace = controller.getWorkspace()

傳回：Workspace | undefined

resolveWorkspace({ session, requestContext? })

為 Session 解析動態 Workspace，並在 controller 上快取結果。

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

傳回：Promise<Workspace | undefined>

setBrowser(browser)

取代 controller 瀏覽器，並傳遞至底層 Agent。

controller.setBrowser(browser)

Mastra 與 Channel

getMastra()

傳回父 Mastra instance，或由 init() 建立的內部 instance。

const mastra = controller.getMastra()

傳回：Mastra | undefined

getChannels()

傳回設定的聊天 Channel 整合。

const channels = controller.getChannels()

傳回：AgentControllerChannels | null

模型

getCurrentModelAuthStatus(session)

傳回 Session 所選模型的驗證狀態。

const status = await controller.getCurrentModelAuthStatus(session)

傳回：Promise<ModelAuthStatus>

listAvailableModels()

列出設定與內建 gateway 提供的模型。結果會短暫快取；設定 modelUseCountProvider 時，會使用使用資料排序。

const models = await controller.listAvailableModels()

傳回：Promise<AvailableModel[]>

invalidateAvailableModelsCache()

清除可用模型 cache。

controller.invalidateAvailableModelsCache()

Observational Memory 與權限

loadOMProgress(session)

載入有效 thread 已儲存的 observational Memory 進度，並發出 om_status event。

await controller.loadOMProgress(session)

getObservationalMemoryRecord(session)

傳回有效 thread 的 observational Memory 記錄。

const record = await controller.getObservationalMemoryRecord(session)

傳回：Promise<ObservationalMemoryRecord | null>

getToolCategory({ toolName })

解析 Tool 的權限 category。

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

傳回：ToolCategory | null

Interval

registerInterval(handler)

啟動或取代週期性 handler。

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

removeInterval({ id })

停止一個 interval，並執行其選填的 shutdown callback。

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

stopIntervals()

停止所有 interval，並執行其選填的 shutdown callback。

await controller.stopIntervals()

相關內容

• AgentController 指南
• Session 參考文件
• Agent
• Workspace
• Channel