Multiagent オーケストレーション

Multiagent オーケストレーションでは、1 つの Agent が Coordinator として他の Agent に作業を委譲します。各 Child Agent は独立した Session Thread で実行され、Coordinator が結果をまとめて最終応答を生成します。Advisor を設定すると、重要な段階でメイン Agent が独立した助言を得られます。責任ごとに分割できる複雑なタスク、並列実行できる作業、段階的に進める作業に適しています。1 ステップで終わる作業や、複数の担当が同じファイルを頻繁に編集する作業では、単一 Agent のほうが簡潔です。

仕組み

Multiagent オーケストレーションは Session Thread モデル上に構築されています。Session 作成時に選択した Agent が Coordinator となり、システムプロンプトに従って multiagent.agents の Agent に作業を委譲します。

概念	説明
Coordinator	Coordinator スレッド。各 Session につき 1 つだけ存在します。Session 作成時に指定された Agent を使用し、オーケストレーションとタスク委譲を担います
Child thread	`multiagent.agents` ロスターの Agent にバインドされる子スレッド。独立してタスクを実行し、Coordinator に結果を報告します
Advisor	メインスレッドが相談できるモデル。助言のみを返し、ツール実行やタスクの引き継ぎは行いません。相談ごとに一時的な Thread を使用します
Session Thread	スレッドエンティティ。ID プレフィックスは `sthr_`。`role`（coordinator または child）、独立した Agent スナップショット、ステータスを含みます

同じ Session の Thread は Environment、Sandbox、ファイルシステム、Session にバインドされた Vault を共有します。一方、対話履歴と Agent 設定スナップショットは Thread ごとに分離されます。Session イベントストリームはメインスレッドとスレッド間連携のイベントを公開し、全子スレッドのイベントの和集合ではありません。個別の Thread のイベントは Thread エンドポイントで取得します。

並列の Child Agent は同じファイルシステムを共有します。複数の Agent が同じファイルを同時に編集しないよう、Coordinator のシステムプロンプトで担当範囲を明確にしてください。

委譲に適した作業

独立した調査、モジュール実装、データ収集を別々の Agent に割り当てて並列実行します。
実装、テスト、レビューを責任ごとに分けます。
実装後にレビューするなど、依存関係がある作業を段階的に実行します。

Coordinator のシステムプロンプトには、委譲条件、各 Agent の出力形式、Coordinator 自身が処理する作業を明記します。

Coordinator を設定する

コンソールでは連携する Agent を先に作成し、Coordinator の Multiagent セクションで委譲先を選択します。API では Agent 設定の multiagent フィールドを設定します。

curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -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_00nc01ht8gcn4w8sb7zv", "version": 3},
        {"type": "agent", "id": "agent_00nc01ht8gcn4w8sb7zw", "version": "latest"},
        {"type": "self"}
      ]
    }
  }'

`multiagent` フィールドリファレンス

フィールド	型	必須	説明
`type`	string	はい	`"coordinator"` 固定
`agents`	array	はい	空でないロスター。最大 20 個の一意な通常の Agent と 1 個の Advisor

agents 配列の要素は以下の 4 つの形式をサポートします:

形式	例	説明
オブジェクト `type: "agent"`	`{"type": "agent", "id": "agent_xxx", "version": 2}`	他の Agent を参照。`id` は必須、`version` は任意
オブジェクト `type: "self"`	`{"type": "self"}`	Coordinator 自身を子 Agent として参照
Advisor オブジェクト	`{"type":"advisor","model":"ultimate"}`	メインスレッドが相談するモデル。ロスターあたり最大 1 件。Advisor の設定を参照
文字列ショートハンド	`"agent_xxx"`	`{"type": "agent", "id": "agent_xxx"}` と等価

通常の Agent または self を含む場合は tools に agent_toolset_20260401 が必要です。Advisor のみのロスターでは不要です。

Agent のバージョンと Session スナップショット

上の例では 3 つの方法を示しています：

"latest"：新しい Session で子 Agent の最新バージョンを使用します。
整数：検証済みのバージョンに固定し、ロールバックや再現を可能にします。
self：現在の Session の Coordinator 設定で子 Thread を作成します。

例えば、親 Agent が multiagent.agents で子 Agent を "version": "latest" として参照している場合、子 Agent を v2 から v3 に更新すると、その親 Agent で新しく作成する Session は子 Agent v3 を使用します。更新前に作成した Session と、その後に同じ Session 内で作成する子 Thread は v2 を使い続けます。 API で version を省略すると、Coordinator 保存時の子 Agent の最新バージョンに固定されます。その後に子 Agent を更新しても、新しい Session は保存済みのバージョンを使用します。詳しくは子 Agent のバージョン規則を参照してください。

子 Agent を更新しても新しい Session が古いバージョンを使う場合

子 Agent の version に数値を指定するか、省略した場合（既定の動作）、Coordinator には固定バージョンが保存されます。子 Agent を更新しても参照は変わりません。multiagent.agents の子 Agent の version を "latest" に変更して保存し、新しい Session を作成してください。

Advisor の設定

Advisor は設計レビューや複雑な問題の分析などでメイン Agent に助言します。相談するタイミングと助言を採用するかどうかはメイン Agent が判断します。相談条件をシステムプロンプトで指定できます。コンソールで Agent を作成または編集するときに、Multiagent で Add Advisor を選び、モデルを指定します。API でも設定できます。

curl -X POST "https://api.qoder.com/api/v1/cloud/agents" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "backend-engineer",
    "model": "auto",
    "system": "Analyze backend designs. Consult the Advisor before data migrations or irreversible changes, then incorporate its advice into your response.",
    "multiagent": {
      "type": "coordinator",
      "agents": [{"type": "advisor", "model": "ultimate"}]
    }
  }'

各 Agent には最大 1 個の Advisor を設定でき、通常の子 Agent と併用できます。enabled_tools に追加する必要はありません。モデル一覧からモデルを選び、設定フィールドは Agent スキーマを参照してください。

相談の流れ

Advisor はメイン Agent の現在の対話コンテキストを使って助言し、ツールは実行しません。メイン Agent は結果を受け取った後に作業を続けます。同じ Advisor に複数回相談でき、コンソールでは相談ごとに記録が表示されます。

イベントと失敗

相談が失敗してもメイン Agent はタスクを続行します。エラーの詳細は Advisor のイベント履歴で確認できます。API で結果と状態を取得する方法は Advisor イベントを参照してください。

中断と削除

個別の相談を中断するか、Agent を更新して Advisor を削除できます。設定変更は新しい Session にのみ適用されます。

コストとコンテキスト

Advisor は現在の対話コンテキストを使用し、相談のたびにモデル料金と待ち時間が発生します。

Session を作成して実行する

multiagent を設定した Coordinator で Session を作成し、通常どおりタスクメッセージを送信します。Agent リストを設定しても委譲は強制されず、Coordinator がシステムプロンプトに基づいて判断します。 MCP サーバー、ツール、Skill は Agent 単位で設定されます。Vault は Session 作成時にバインドされ、各 Agent は自身のツール設定と権限ポリシーに従います。

スレッドイベント

Multiagent オーケストレーションでは、イベントストリームに以下の新しいイベントタイプが現れます:

イベントタイプ	説明
`session.thread_created`	新しい子スレッドが作成された
`session.thread_status_running`	スレッドが実行を開始した
`session.thread_status_rescheduled`	スレッドのタスクが再試行され、再スケジュールされた
`session.thread_status_idle`	スレッドが完了または一時停止した
`session.thread_status_terminated`	スレッドがアーカイブ/終了された
`agent.thread_message_sent`	スレッド間メッセージが送信された（coordinator → child または後続メッセージ）
`agent.thread_message_received`	スレッド間メッセージが受信された（child → coordinator）

すべてのイベントには所属スレッドを識別する session_thread_id フィールドが含まれます。スレッドイベント一覧とスレッドイベントストリームエンドポイントを使用して、スレッド単位でイベントをフィルタリングできます。

単一 Thread の中断とツール操作

user.interrupt に session_thread_id を指定すると対象 Thread だけを中断できます。省略すると Session 全体の現在の作業を中断します。通常の子 Thread は中断してもアーカイブされません。Advisor Thread は相談の完了、失敗、中断後に自動的にアーカイブされますが、履歴は引き続き参照できます。確認が必要な agent.tool_use には user.tool_confirmation、Custom Tool の agent.custom_tool_use には user.custom_tool_result で応答します。ID によって元の Thread へルーティングされるため、応答に session_thread_id を含めないでください。

制限

項目	制限
Agent ロスター	最大 20 個の一意な通常の Agent と 1 個の Advisor。空にはできません
Session あたりの未アーカイブ Thread 数	通常の Thread は最大 25 個（Coordinator を含む）。Advisor Thread はこの上限に含まれません
委譲階層	Child Agent はさらに子 Thread を作成できません
Session アイドル条件	すべてのスレッドが実行を停止している必要がある

次のステップ

multiagent を設定

Agent 作成時に multiagent フィールドを設定します。

Agent スキーマ

multiagent と agent entry のフィールドリファレンス。

Session Threads 一覧

Session 内のすべてのスレッドを表示します。

Session Thread オブジェクト

Session Thread オブジェクトのフィールドとライフサイクル。

​仕組み

​委譲に適した作業

​Coordinator を設定する

​multiagent フィールドリファレンス

​Agent のバージョンと Session スナップショット

​子 Agent を更新しても新しい Session が古いバージョンを使う場合

​Advisor の設定

​相談の流れ

​イベントと失敗

​中断と削除

​コストとコンテキスト

​Session を作成して実行する

​スレッドイベント

​単一 Thread の中断とツール操作

​制限

​次のステップ

multiagent を設定

Agent スキーマ

Session Threads 一覧

Session Thread オブジェクト

仕組み

委譲に適した作業

Coordinator を設定する

`multiagent` フィールドリファレンス

Agent のバージョンと Session スナップショット

子 Agent を更新しても新しい Session が古いバージョンを使う場合

Advisor の設定

相談の流れ

イベントと失敗

中断と削除

コストとコンテキスト

Session を作成して実行する

スレッドイベント

単一 Thread の中断とツール操作

制限

次のステップ