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

# AgentController

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

`AgentController` 類別是供一或多個 [`Session`](https://mastra.zisheng.pro/zh-TW/reference/agent-controller/session) instance 使用的共用 host。先初始化 controller 並建立 Session，接著使用 `session.*` API 管理對話 state 與 run。

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

## 使用範例

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

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

## Constructor 參數

**id** (`string`): 不重複的 controller 識別碼，也是預設的 Session 與 resource 識別碼。

**modes** (`AgentControllerMode[]`): 每個 Session 都可使用的 mode 定義。至少需要一個 mode。

**modes.id** (`string`): 不重複的 mode 識別碼。

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

**modes.defaultModelId** (`string`): Session 進入此 mode 且沒有已儲存的選擇時，選用的模型。

**modes.description** (`string`): 顯示於 mode selector 的文字。

**modes.instructions** (`string`): 在此 mode 中疊加於底層 Agent instructions 之上的 instructions。

**modes.transitionsTo** (`string`): 核准 submit\_plan suspension 後進入的 mode。

**modes.availableTools** (`string[]`): 公開 Tool 名稱的 allowlist。空陣列會在此 mode 隱藏所有 Tool。

**modes.metadata** (`Record<string, unknown>`): 直接傳遞的 mode metadata。metadata.default: true 會標示預設 mode。

**modes.tools** (`ToolsInput`): Mode Tool。不能與 additionalTools 同時使用。

**modes.additionalTools** (`ToolsInput`): 加入底層 Agent Tool 的 Tool。不能與 tools 同時使用。

**modes.agent** (`Agent`): 已棄用的 mode 專用 Agent。請使用頂層 agent 參數。

**modes.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 型別。

**subagents.id** (`string`): 不重複的 subagent 型別識別碼。

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

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

**subagents.instructions** (`DynamicArgument<AgentInstructions>`): Subagent instructions。

**subagents.tools** (`ToolsInput`): Subagent 擁有的 Tool。

**subagents.allowedControllerTools** (`string[]`): 加入 subagent Tool 的 controller Tool ID。

**subagents.allowedWorkspaceTools** (`string[]`): subagent 可見的 Workspace Tool 名稱。

**subagents.defaultModelId** (`string`): 預設 subagent 模型。

**subagents.maxSteps** (`number`): 最大執行 step 數。

**subagents.stopWhen** (`LoopOptions["stopWhen"]`): 迴圈停止條件。

**subagents.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()`。

```typescript
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。

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

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

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

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

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

#### `getKnownResourceIds(session)`

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

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

傳回：`Promise<string[]>`

### 生命週期

#### `init()`

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

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

#### `destroy()`

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

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

### Mode 與 Agent

#### `listModes()`

傳回設定的 mode 定義。

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

傳回：`AgentControllerMode[]`

#### `getCurrentAgent(session)`

傳回 Session 有效 mode 的底層 Agent。

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

傳回：`Agent`

### Workspace 與瀏覽器

#### `hasWorkspace()`

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

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

傳回：`boolean`

#### `isWorkspaceReady()`

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

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

傳回：`boolean`

#### `getWorkspace()`

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

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

傳回：`Workspace | undefined`

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

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

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

傳回：`Promise<Workspace | undefined>`

#### `setBrowser(browser)`

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

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

### Mastra 與 Channel

#### `getMastra()`

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

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

傳回：`Mastra | undefined`

#### `getChannels()`

傳回設定的聊天 Channel 整合。

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

傳回：`AgentControllerChannels | null`

### 模型

#### `getCurrentModelAuthStatus(session)`

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

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

傳回：`Promise<ModelAuthStatus>`

#### `listAvailableModels()`

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

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

傳回：`Promise<AvailableModel[]>`

#### `invalidateAvailableModelsCache()`

清除可用模型 cache。

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

### Observational Memory 與權限

#### `loadOMProgress(session)`

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

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

#### `getObservationalMemoryRecord(session)`

傳回有效 thread 的 observational Memory 記錄。

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

傳回：`Promise<ObservationalMemoryRecord | null>`

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

解析 Tool 的權限 category。

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

傳回：`ToolCategory | null`

### Interval

#### `registerInterval(handler)`

啟動或取代週期性 handler。

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

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

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

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

#### `stopIntervals()`

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

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

## 相關內容

- [AgentController 指南](https://mastra.zisheng.pro/zh-TW/docs/harness/agent-controller)
- [Session 參考文件](https://mastra.zisheng.pro/zh-TW/reference/agent-controller/session)
- [Agent](https://mastra.zisheng.pro/zh-TW/docs/agents/overview)
- [Workspace](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)
- [Channel](https://mastra.zisheng.pro/zh-TW/docs/capabilities/channels/overview)