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 フィールドを設定します:
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 ライフサイクル
Session を作成
クライアントが multiagent 設定済みの Agent を参照する Session を作成します。
ターン開始
クライアントが user.message イベントを送信します。CAS は自動的に Coordinator スレッド（role: coordinator）を作成します。
Coordinator が委譲
モデルが create_agent または Agent ツールを呼び出します。CAS は子スレッドを作成し、タスクメッセージを mailbox にキューイングします。
Child が実行
CAS スケジューラが mailbox メッセージを子スレッドに配信します。CAW は子の Agent スナップショットをロードし、独立して実行します。
Child が結果を報告
Child が send_to_parent を呼び出します。メッセージは mailbox 経由で Coordinator にルーティングされ、子スレッドは idle に遷移します。
Coordinator が継続
Coordinator は child の報告を受け取り、結果を統合して処理を継続するか、新たな委譲を開始します。
Session アイドル
実行中のすべてのスレッドが停止すると、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 フィールドが含まれます。スレッドイベント一覧とスレッドイベントストリームエンドポイントを使用して、スレッド単位でイベントをフィルタリングできます。
| 項目 | 制限 |
|---|
| Agent 設定あたりの最大子 Agent 数 | 20 個のユニークなエントリ |
| Session あたりの最大同時スレッド数 | 25 個（Coordinator を含む） |
| Session アイドル条件 | すべてのスレッドが実行を停止している必要がある |
次のステップ
multiagent を設定
Agent 作成時に multiagent フィールドを設定します。
Agent スキーマ
multiagent と agent entry のフィールドリファレンス。
Session Threads 一覧
Session 内のすべてのスレッドを表示します。
Session Thread オブジェクト
Session Thread オブジェクトのフィールドとライフサイクル。
