AgentController

beta

AgentController 功能目前處於 beta 階段，在脫離 beta 狀態之前，次要版本可能會包含破壞性變更。

AgentController 類別是一個共享主機，可供一個或多個 Session 實例使用。先初始化控制器並建立工作階段，然後使用 session.* API 管理對話狀態及執行控制。

如需引導式介紹，請參閱 AgentController 概覽。

使用範例

以下範例會初始化控制器並建立工作階段。它會先訂閱工作階段事件，然後才傳送訊息。

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

唯一的控制器識別符，同時也是預設的工作階段及資源識別符。

modes:

AgentControllerMode[]

每個工作階段均可使用的模式定義。至少需要一個模式。

AgentControllerMode

id:

string

唯一的模式識別符。

name?:

string

顯示名稱。

defaultModelId?:

string

工作階段進入此模式而沒有已儲存的選擇時所選用的模型。

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

工作階段及執行緒的預設資源識別符。預設為 id。

storage?:

MastraCompositeStore

用於持久化執行緒、訊息、設定及可恢復執行資料的儲存空間。

stateSchema?:

PublicSchema<TState, any>

用於驗證 session.state 更新的結構描述。

initialState?:

Partial<TState>

為每個新工作階段與結構描述預設值合併的初始狀態。

memory?:

DynamicArgument<MastraMemory>

與未定義自身記憶體的後端 Agent 共享的記憶體實例。

defaultModeId?:

string

預設模式識別符，優先於模式中繼資料。

instructions?:

string

與目前模式指示疊加的控制器指示。

tools?:

DynamicArgument<ToolsInput | undefined>

由控制器執行共享，並可供已設定子 Agent 使用的 Tool。

workspace?:

DynamicArgument<Workspace | undefined>

靜態 Workspace 或按工作階段建立 Workspace 的工廠。工作階段必須解析為有效的 Workspace。

browser?:

DynamicArgument<MastraBrowser | undefined>

靜態瀏覽器或按工作階段建立瀏覽器的工廠。

channels?:

AgentControllerChannelsConfig

用於將聊天頻道執行緒路由至控制器工作階段的聊天頻道設定。

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

傳遞至建構函數的控制器識別符。

方法

工作階段

createSession(options)

取得或建立已為 (resourceId, scope) 配對登記的即時工作階段。請先呼叫 init()，再呼叫此方法。

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

相同的 resourceId 及 scope 會傳回同一個 Session 實例。不同的範圍會為同一資源建立隔離的工作階段。提供 threadId 時，此方法會將快取的工作階段切換至該執行緒；如果執行緒不存在，則會建立該執行緒。

resourceId?:

string

記憶體資源及即時工作階段登記鍵。預設為已設定的 resourceId 或控制器 id。

scope?:

string

選用的登記命名空間，讓一個資源可以有多個即時工作階段。

threadId?:

string

要綁定的確切執行緒。缺少的執行緒會使用此識別符建立。

id?:

string

穩定的工作階段識別符。預設為控制器 id。

ownerId?:

string

穩定的工作階段擁有者識別符。預設為 id。

tags?:

Record<string, string>

複製至工作階段所建立執行緒的標籤。

workspace?:

Workspace

此工作階段的 Workspace 覆寫。

browser?:

MastraBrowser

此工作階段的瀏覽器覆寫。

requestContext?:

RequestContext

用於解析動態 Workspace 及瀏覽器工廠的上下文。

傳回：Promise<Session<TState>>

getSessionByResource(resourceId, scope?)

傳回已為資源及選用範圍登記的即時工作階段。

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

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

setResourceId(session, { resourceId })

將即時工作階段移至另一個資源，並清除其作用中執行緒綁定。

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)

傳回工作階段作用中模式的後端 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? })

為工作階段解析動態 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)

傳回工作階段所選模型的驗證狀態。

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
• 頻道