> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Managed Agents
> Coordinator Agent でサブタスクを child Agent に並列・直列に委譲します。
Managed Agents は、1 つの Agent を Coordinator として動作させ、他の Agent にタスクを管理・委譲することで、マルチ Agent 協調を実現する機能です。Coordinator Agent は子 Agent スレッドの作成、メッセージ送信、結果の待機が可能で、複雑なタスクを複数の独立したサブタスクに分解し、並列または直列で実行できます。
## コアコンセプト
Managed Agents は Session Thread モデル上に構築されています。1 つの Session には複数のスレッドを同時に保持でき、各スレッドは独立した Agent スナップショットにバインドされ、独自の対話履歴と実行コンテキストを持ちます。
| 概念 | 説明 |
| -------------- | ------------------------------------------------------------------------------------------------------------------ |
| Coordinator | Coordinator スレッド。各 Session につき 1 つだけ存在します。Session 作成時に指定された Agent を使用し、オーケストレーションとタスク委譲を担います |
| Child thread | 子スレッド。Coordinator がツール呼び出しを通じて作成します。`multiagent.agents` ロスターの Agent にバインドされ、独立してタスクを実行し、`send_to_parent` で結果を報告します |
| Session Thread | スレッドエンティティ。ID プレフィックスは `sthr_`。`role`（coordinator または child）、独立した Agent スナップショット、ステータスを含みます |
| Mailbox | スレッド間のメッセージキュー。CAS が内部で管理します。メッセージはキューイングされ、ターゲットスレッドのステータスに応じてスケジューラが自動的に配信します |
## Managed Agents の設定
Managed Agents 機能を有効にするには、Agent 設定で `multiagent` フィールドを設定します:
```bash theme={null}
curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
-H "Authorization: Bearer $QODER_PAT" \
-H "Content-Type: application/json" \
-d '{
"name": "task-coordinator",
"model": "ultimate",
"system": "You are a task coordinator responsible for delegating tasks to sub-agents.",
"tools": [
{
"type": "agent_toolset_20260401",
"enabled_tools": ["Bash", "Read", "Write"]
}
],
"multiagent": {
"type": "coordinator",
"agents": [
{"type": "agent", "id": "agent_019f000000000000000000000000001a", "name": "Research Agent"},
{"type": "agent", "id": "agent_019f000000000000000000000000002b"},
{"type": "self"}
]
}
}'
```
### `multiagent` フィールドリファレンス
| フィールド | 型 | 必須 | 説明 |
| -------- | ------ | -- | --------------------------------- |
| `type` | string | はい | `"coordinator"` 固定 |
| `agents` | array | はい | 委譲可能な Agent ロスター。1-20 個のユニークなエントリ |
`agents` 配列の要素は以下の 3 つの形式をサポートします:
| 形式 | 例 | 説明 |
| ---------------------- | ------------------------------------------------------------------------ | -------------------------------------------- |
| オブジェクト `type: "agent"` | `{"type": "agent", "id": "agent_xxx", "version": 2, "name": "Reviewer"}` | 他の Agent を参照。`id` は必須、`version` と `name` は任意 |
| オブジェクト `type: "self"` | `{"type": "self"}` | Coordinator 自身を子 Agent として参照 |
| 文字列ショートハンド | `"agent_xxx"` | `{"type": "agent", "id": "agent_xxx"}` と等価 |
`multiagent` を設定する場合、`tools` には `agent_toolset_20260401` エントリを含める必要があります。システムは実行時に `create_agent`、`send_to_agent`、`list_agents`、`Agent` 制御ツールを自動的に注入します。
## Coordinator 制御ツール
Session の Agent が `multiagent` を設定しており、現在のスレッドロールが Coordinator の場合、以下のツールが自動的に注入されます:
### `create_agent`
新しい子 Agent スレッドを作成し、初期タスクを送信します。子 Agent の完了を待たずに、スレッド ID を即座に返却します。
| パラメータ | 型 | 必須 | 説明 |
| ------------ | ------ | --- | ----------------------------------------------------------- |
| `agent_id` | string | はい | ロスター内の Agent ID、または `"self"`。値は `multiagent.agents` で決定されます |
| `agent_name` | string | いいえ | 子スレッドの表示名 |
| `task` | string | はい | 子 Agent に送信する初期タスク記述 |
返却例: `"Created agent thread: sthr_019f..."`
### `Agent`
子 Agent にフォーカスされたタスクを委譲し、同期的に結果を待ちます。これはブロッキング型ツールで、Coordinator のターンは子 Agent が完了する（`send_to_parent` を呼び出す）か中断されるまで一時停止します。
| パラメータ | 型 | 必須 | 説明 |
| ---------- | ------ | -- | ---------------------------- |
| `agent_id` | string | はい | ロスター内の Agent ID、または `"self"` |
| `prompt` | string | はい | 子 Agent に委譲するタスクプロンプト |
### `send_to_agent`
既存の子スレッドに後続メッセージを送信します。
| パラメータ | 型 | 必須 | 説明 |
| ----------- | ------ | -- | ------------------------------ |
| `thread_id` | string | はい | ターゲット子スレッド ID（`sthr_` プレフィックス） |
| `message` | string | はい | 送信するメッセージ内容 |
返却例: `"Message queued for agent thread: sthr_019f..."`
### `list_agents`
現在の Session 内のすべての子スレッドのステータス、保留中メッセージ数、および利用可能な Agent ロスターを一覧表示します。パラメータは不要です。
## Child 制御ツール
スレッドロールが child の場合、システムは以下のツールを 1 つ自動的に注入します:
### `send_to_parent`
結果、ステータス更新、または質問を Coordinator に送信します。この呼び出し後、子スレッドは `idle` ステータスに遷移します。
| パラメータ | 型 | 必須 | 説明 |
| --------- | ------ | -- | ---------------------- |
| `message` | string | はい | Coordinator に送信するメッセージ |
## Session Thread ライフサイクル
クライアントが `multiagent` 設定済みの Agent を参照する Session を作成します。
クライアントが `user.message` イベントを送信します。CAS は自動的に Coordinator スレッド（`role: coordinator`）を作成します。
モデルが `create_agent` または `Agent` ツールを呼び出します。CAS は子スレッドを作成し、タスクメッセージを mailbox にキューイングします。
CAS スケジューラが mailbox メッセージを子スレッドに配信します。CAW は子の Agent スナップショットをロードし、独立して実行します。
Child が `send_to_parent` を呼び出します。メッセージは mailbox 経由で Coordinator にルーティングされ、子スレッドは `idle` に遷移します。
Coordinator は child の報告を受け取り、結果を統合して処理を継続するか、新たな委譲を開始します。
実行中のすべてのスレッドが停止すると、Session は `idle` ステータスに遷移します。
## スレッドイベント
Managed Agents シナリオでは、イベントストリームに以下の新しいイベントタイプが現れます:
| イベントタイプ | 説明 |
| ---------------------------------- | ------------------------------------------------ |
| `session.thread_created` | 新しい子スレッドが作成された |
| `session.thread_status_running` | スレッドが実行を開始した |
| `session.thread_status_idle` | スレッドが完了または一時停止した |
| `session.thread_status_terminated` | スレッドがアーカイブ/終了された |
| `agent.thread_message_sent` | スレッド間メッセージが送信された（coordinator → child または後続メッセージ） |
| `agent.thread_message_received` | スレッド間メッセージが受信された（child → coordinator） |
すべてのイベントには所属スレッドを識別する `session_thread_id` フィールドが含まれます。[スレッドイベント一覧](/ja/cloud-agents/api/sessions/list-thread-events)と[スレッドイベントストリーム](/ja/cloud-agents/api/sessions/stream-thread-events)エンドポイントを使用して、スレッド単位でイベントをフィルタリングできます。
## 制限
| 項目 | 制限 |
| ----------------------- | ----------------------- |
| Agent 設定あたりの最大子 Agent 数 | 20 個のユニークなエントリ |
| Session あたりの最大同時スレッド数 | 25 個（Coordinator を含む） |
| Session アイドル条件 | すべてのスレッドが実行を停止している必要がある |
## 次のステップ
Agent 作成時に `multiagent` フィールドを設定します。
`multiagent` と agent entry のフィールドリファレンス。
Session 内のすべてのスレッドを表示します。
Session Thread オブジェクトのフィールドとライフサイクル。