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

# AgentController

> **Beta:** `AgentController` 機能はベータ段階です。ベータを終了するまでは、マイナーバージョンで破壊的変更が行われる可能性があります。

`AgentController` クラスは、1つ以上の [`Session`](https://mastra.zisheng.pro/ja/reference/agent-controller/session) インスタンスを共有するホストです。Controller を初期化して Session を作成したら、会話の状態と実行制御には `session.*` API を使用します。

手順を追った概要については、[AgentController の概要](https://mastra.zisheng.pro/ja/docs/harness/agent-controller)を参照してください。

## 使用例

次の例では、Controller を初期化して Session を作成します。メッセージを送信する前に Session イベントを購読します。

```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`): Controller の一意な識別子。Session と Resource のデフォルト識別子としても使用されます。

**modes** (`AgentControllerMode[]`): すべての Session で使用できる Mode 定義。少なくとも1つの Mode が必要です。

**modes.id** (`string`): Mode の一意な識別子。

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

**modes.defaultModelId** (`string`): 保存済みの選択がない状態で Session がこの Mode に入ったときに選択されるモデル。

**modes.description** (`string`): Mode セレクターに表示するテキスト。

**modes.instructions** (`string`): この Mode で、基盤となる Agent の指示より上位に重ねる指示。

**modes.transitionsTo** (`string`): 承認済みの submit\_plan Suspension の後に移行する Mode。

**modes.availableTools** (`string[]`): 公開する Tool 名の許可リスト。空の配列にすると、この Mode ではすべての Tool が非表示になります。

**modes.metadata** (`Record<string, unknown>`): そのまま渡される Mode メタデータ。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、メッセージ、設定、再開可能な実行データの永続化に使用するストレージ。

**stateSchema** (`PublicSchema<TState, any>`): session.state の更新を検証するためのスキーマ。

**initialState** (`Partial<TState>`): 新しい各 Session でスキーマのデフォルト値と統合される初期状態。

**memory** (`DynamicArgument<MastraMemory>`): 独自の Memory を定義していない基盤 Agent と共有する Memory インスタンス。

**defaultModeId** (`string`): デフォルトの Mode 識別子。Mode メタデータより優先されます。

**instructions** (`string`): 現在の Mode の指示と重ねて使用する Controller の指示。

**tools** (`DynamicArgument<ToolsInput | undefined>`): Controller の実行で共有され、設定済みのサブ Agent で使用できる Tool。

**workspace** (`DynamicArgument<Workspace | undefined>`): 静的 Workspace または Session ごとの Workspace Factory。Session は有効な Workspace を解決する必要があります。

**browser** (`DynamicArgument<MastraBrowser | undefined>`): 静的 Browser または Session ごとの Browser Factory。

**channels** (`AgentControllerChannelsConfig`): Channel の Thread を Controller の Session にルーティングするための Chat Channel 設定。

**intervalHandlers** (`IntervalHandler[]`): init() で開始し、stopIntervals() または destroy() で停止する定期 Handler。

**idGenerator** (`() => string`): Thread、メッセージ、Signal 用のカスタム識別子 Generator。

**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 に追加する Controller Tool ID。

**subagents.allowedWorkspaceTools** (`string[]`): サブ Agent から参照できる Workspace Tool 名。

**subagents.defaultModelId** (`string`): サブ Agent のデフォルトモデル。

**subagents.maxSteps** (`number`): 実行ステップの最大数。

**subagents.stopWhen** (`LoopOptions["stopWhen"]`): ループの停止条件。

**subagents.forked** (`boolean`): サブ Agent がデフォルトで複製された親 Thread を継承するかどうか。

**gateways** (`MastraModelGatewayInterface[]`): 組み込み Gateway と統合するカスタムモデル Gateway。

**omConfig** (`AgentControllerOMConfig`): Observational Memory のデフォルトモデルとしきい値。

**disableBuiltinTools** (`BuiltinToolId[]`): 実行から除外する組み込み Controller Tool。

**toolCategoryResolver** (`(toolName: string) => ToolCategory | null`): Tool 名を権限カテゴリーに対応付けます。

**pubsub** (`PubSub`): 基盤 Agent に伝播する PubSub 実装。

**threadLock** (`{ acquire: (threadId: string) => void | Promise<void>; release: (threadId: string) => void | Promise<void> }`): Thread の所有権を調整するための Lock 実装。

**observability** (`ObservabilityEntrypoint`): スタンドアロンの Controller Mastra インスタンスに使用する Observability 設定。

## プロパティ

**id** (`string`): コンストラクターに渡された Controller 識別子。

## メソッド

### Session

#### `createSession(options)`

`(resourceId, scope)` の組に対して登録されたライブ Session を取得または作成します。このメソッドより先に `init()` を呼び出してください。

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

同じ `resourceId` と `scope` を指定すると、同じ `Session` インスタンスが返されます。Scope が異なる場合、同じ Resource に対して分離された Session が作成されます。`threadId` を指定すると、キャッシュ済み Session をその Thread に切り替えます。Thread が存在しない場合は作成します。

**resourceId** (`string`): Memory Resource とライブ Session レジストリのキー。デフォルトでは、設定された resourceId または Controller の id が使用されます。

**scope** (`string`): 1つの Resource に複数のライブ Session を作成できる、省略可能なレジストリ名前空間。

**threadId** (`string`): バインドする特定の Thread。存在しない Thread はこの識別子で作成されます。

**id** (`string`): 安定した Session 識別子。デフォルトでは Controller の id が使用されます。

**ownerId** (`string`): 安定した Session 所有者識別子。デフォルトは id です。

**tags** (`Record<string, string>`): Session が作成する Thread にコピーされるタグ。

**workspace** (`Workspace`): この Session で使用する Workspace のオーバーライド。

**browser** (`MastraBrowser`): この Session で使用する Browser のオーバーライド。

**requestContext** (`RequestContext`): 動的な Workspace Factory と Browser 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()`

共有ストレージ、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 と Browser

#### `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 の Browser を置き換え、基盤 Agent に伝播します。

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

### Mastra と Channel

#### `getMastra()`

親 Mastra インスタンス、または `init()` が作成した内部インスタンスを返します。

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

戻り値：`Mastra | undefined`

#### `getChannels()`

設定済みの Chat Channel 統合を返します。

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

戻り値：`AgentControllerChannels | null`

### モデル

#### `getCurrentModelAuthStatus(session)`

Session で選択されているモデルの認証ステータスを返します。

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

戻り値：`Promise<ModelAuthStatus>`

#### `listAvailableModels()`

設定済みの Gateway と組み込み Gateway からモデルを一覧表示します。結果は短時間キャッシュされ、`modelUseCountProvider` が設定されている場合は利用状況データを使用して並べ替えられます。

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

戻り値：`Promise<AvailableModel[]>`

#### `invalidateAvailableModelsCache()`

利用可能なモデルのキャッシュを消去します。

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

### Observational Memory と権限

#### `loadOMProgress(session)`

アクティブな Thread について保存されている Observational Memory の進行状況を読み込み、`om_status` イベントを発行します。

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

#### `getObservationalMemoryRecord(session)`

アクティブな Thread の Observational Memory レコードを返します。

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

戻り値：`Promise<ObservationalMemoryRecord | null>`

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

Tool の権限カテゴリーを解決します。

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

1つの Interval を停止し、省略可能なシャットダウンコールバックを実行します。

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

#### `stopIntervals()`

すべての Interval を停止し、省略可能なシャットダウンコールバックを実行します。

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

## 関連情報

- [AgentController ガイド](https://mastra.zisheng.pro/ja/docs/harness/agent-controller)
- [Session リファレンス](https://mastra.zisheng.pro/ja/reference/agent-controller/session)
- [Agent](https://mastra.zisheng.pro/ja/docs/agents/overview)
- [Workspace](https://mastra.zisheng.pro/ja/docs/workspace/overview)
- [Channels](https://mastra.zisheng.pro/ja/docs/capabilities/channels/overview)