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

# AgentController

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

`AgentController` 類別是一個共享主機，可供一個或多個 [`Session`](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/session) 實例使用。先初始化控制器並建立工作階段，然後使用 `session.*` API 管理對話狀態及執行控制。

如需引導式介紹，請參閱 [AgentController 概覽](https://mastra.zisheng.pro/zh-HK/docs/harness/agent-controller)。

## 使用範例

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

```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`): 唯一的控制器識別符，同時也是預設的工作階段及資源識別符。

**modes** (`AgentControllerMode[]`): 每個工作階段均可使用的模式定義。至少需要一個模式。

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

**modes.name** (`string`): 顯示名稱。

**modes.defaultModelId** (`string`): 工作階段進入此模式而沒有已儲存的選擇時所選用的模型。

**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`): 工作階段及執行緒的預設資源識別符。預設為 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 類型。

**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`): 傳遞至建構函數的控制器識別符。

## 方法

### 工作階段

#### `createSession(options)`

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

```typescript
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?)`

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

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

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

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

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

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

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

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

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

```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/zh-HK/docs/harness/agent-controller)
- [Session 參考](https://mastra.zisheng.pro/zh-HK/reference/agent-controller/session)
- [Agent](https://mastra.zisheng.pro/zh-HK/docs/agents/overview)
- [Workspace](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)
- [頻道](https://mastra.zisheng.pro/zh-HK/docs/capabilities/channels/overview)