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 を設定する

コンソールで設定する

Cloud Agents コンソールの Agents で、連携する各 Agent を作成します。
Coordinator を作成または編集し、Multiagent で委譲先の Agent を選択します。選択した Agent の現在のバージョンが保存されます。
Coordinator のシステムプロンプトで、タスクの分割、委譲条件、出力形式、競合の処理方法を定義します。
Coordinator を保存し、それを使って Session を作成します。

コンソールの選択画面は他の Agent を参照するためのものです。Coordinator 自身をリストに追加する場合は、API または JSON 設定で {"type":"self"} を追加してください。

API で Agent を作成する

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 のみのロスターでは不要です。

API で Agent を更新する

子 Agent の追加・削除やバージョン変更を行うには、まずメイン Agent を取得して現在の設定を確認し、Agent の更新に POST で変更を送信します。次の例はメイン Agent（Coordinator）の子 Agent リストを変更します。Agent ID とバージョン番号を自分の値に置き換えてください。

curl -X POST "https://api.qoder.com/api/v1/cloud/agents/agent_00nc01ht8gcn4w8sb7zx" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 4,
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "agent", "id": "agent_00nc01ht8gcn4w8sb7zv", "version": 3},
        {"type": "agent", "id": "agent_00nc01ht8gcn4w8sb7zw", "version": "latest"}
      ]
    }
  }'

更新時の注意点：

multiagent は設定全体を置き換えます。引き続き使用する子 Agent、self、Advisor をすべて含めてください。null を指定するとオーケストレーションを無効にできます。
トップレベルの version にはメイン Agent の現在のバージョンを指定します。409 が返された場合は設定を再取得し、変更を反映して再試行してください。405 が返された場合は URL を確認し、上記のように POST を使用してください。
更新後の設定は、その Agent の新しいバージョンで作成する新規 Session にのみ適用されます。既存の Session には影響しません。

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

Coordinator の作成例では 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 を作成します。

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "type": "agent",
      "id": "agent_00nc01ht8gcn4w8sb7zx",
      "version": 4
    },
    "environment_id": "env_00l99wwqo8ydc81s4djg",
    "vault_ids": ["vault_00j9owzm7vfnkgckud6o"],
    "title": "ログインモジュールを分析してレビューする"
  }'

agent オブジェクトには type: "agent" が必須です。例の ID と version を、自分のリソース ID とメイン Agent（Coordinator）のバージョン番号に置き換えてください。 Session にタスクメッセージを送信します。Coordinator はシステムプロンプトに基づいて、委譲するかどうかと作業の分割方法を判断します。

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.message",
        "content": [
          {"type": "text", "text": "ログインモジュールの実装とセキュリティリスクを分析し、修正案を提示してください。"}
        ]
      }
    ]
  }'

Agent リストを設定しても、委譲は強制されません。Coordinator が自身の判断とシステムプロンプトに基づいて決定します。子 Agent を列挙するだけでなく、委譲条件を明示してください。 Session の作成と Session イベントの送信を参照してください。

MCP サーバーと Vault を接続する

MCP サーバー、ツール、Skill は Agent の設定に属します。Vault は Session 作成時にバインドします。

対応する MCP サーバーまたはツールセットを設定した Agent だけが、その機能を呼び出せます。
Session 内の全 Thread はバインドされた Vault を共有しますが、各 Agent は自身のツール設定と権限ポリシーに従います。
Vault の認証情報 URL は、Agent に設定した MCP サーバーの URL と一致する必要があります。
Coordinator には通常、作業の調整と結果の集約に必要な機能だけを与えます。強い権限を持つ認証情報は、必要な Agent にだけ付与してください。

ツール、Vault、権限ポリシーを参照してください。

スレッドイベント

Session イベントストリームで連携全体の進捗を確認します。

curl -N "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events/stream" \
  -H "Authorization: Bearer $QODER_PAT"

Multiagent オーケストレーションでは、次の Thread イベントが発生します。

イベントタイプ	説明
`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 を特定できます。Session 内の Thread を一覧表示します。

curl "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/threads" \
  -H "Authorization: Bearer $QODER_PAT"

子 Agent の実行全体を確認するには、その Thread のイベントストリームに接続します。

curl -N "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/threads/sthr_xxx/stream" \
  -H "Authorization: Bearer $QODER_PAT"

Session イベントストリームは Thread 間の進捗や Coordinator の集約結果の確認に、Thread イベントストリームは個々の子 Agent のデバッグに使います。Session Threads 一覧、Thread イベント一覧、Thread イベントストリームを参照してください。

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

user.interrupt に session_thread_id を指定すると対象 Thread だけを中断できます。省略すると Session 全体の現在の作業を中断します。通常の子 Thread は中断してもアーカイブされません。Advisor Thread は相談の完了、失敗、中断後に自動的にアーカイブされますが、履歴は引き続き参照できます。

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.interrupt",
        "session_thread_id": "sthr_xxx"
      }
    ]
  }'

ツールの権限と対話

各 Thread は、自身の Agent スナップショットに含まれるツール設定と権限ポリシーを使用します。確認が必要なツール呼び出しは agent.tool_use を送信します。クライアントは user.tool_confirmation で応答し、tool_use_id と result を指定します。Custom Tool の呼び出しは agent.custom_tool_use を送信します。クライアントで実行した後、user.custom_tool_result で応答し、custom_tool_use_id を指定します。処理待ちの操作がある場合、イベントストリームは session.status_idle を送信します。stop_reason.type は requires_action となり、stop_reason.event_ids に応答が必要なイベント ID が列挙されます。関連する Agent イベントの session_thread_id で、要求元の Thread を特定できます。次の例は、確認が必要なツール呼び出しを許可します。

curl -X POST "https://api.qoder.com/api/v1/cloud/sessions/sess_00neihyybhw5csymr2ju/events" \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "type": "user.tool_confirmation",
        "tool_use_id": "evt_01JZ6Q3FB6SG8F7J1M2N",
        "result": "allow"
      }
    ]
  }'

ツール操作への応答には session_thread_id を含めないでください。プラットフォームは tool_use_id または custom_tool_use_id に基づいて、元の Thread に応答を返します。stop_reason.event_ids に複数の ID がある場合は、各 ID に応答してください。未処理の操作が残っている間、現在の turn は一時停止したままです。requires_action は入力待ちを意味し、Session の完了を意味しません。子 Thread をアーカイブする前に、応答待ちのツール操作がないことを確認してください。Session イベントの送信を参照してください。

制限

項目	制限
Agent ロスター	最大 20 個の一意な通常の Agent と 1 個の Advisor。空にはできません
Session あたりの未アーカイブ Thread 数	通常の Thread は最大 25 個（Coordinator を含む）。Advisor Thread はこの上限に含まれません
委譲階層	Child Agent はさらに子 Thread を作成できません
Session アイドル条件	すべてのスレッドが実行を停止している必要がある
Agent の参照	存在しない、アーカイブ済み、またはアクセスできない Agent やバージョンを参照すると、設定に失敗します
ツールセット	通常の Agent または `self` を含む場合は `agent_toolset_20260401` が必須です。Advisor のみの場合は不要です

トラブルシューティング

Coordinator が委譲しない

現在の Coordinator バージョンの multiagent.agents が空でないことを確認します。設定規則は Agent スキーマを参照してください。
システムプロンプトに委譲条件と各 Agent の役割が明記されていることを確認します。

Coordinator の作成または更新で 400 が返る

Agent またはバージョンの参照が無効、あるいは multiagent 設定が検証に失敗している可能性があります。API のエラーメッセージから該当フィールドを確認します。完全な規則は Agent スキーマを参照してください。

次のステップ

multiagent を設定

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

Agent スキーマ

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

Session Threads 一覧

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

Session Thread オブジェクト

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

​仕組み

​委譲に適した作業

​Coordinator を設定する

​コンソールで設定する

​API で Agent を作成する

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

​API で Agent を更新する

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

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

​Advisor の設定

​相談の流れ

​イベントと失敗

​中断と削除

​コストとコンテキスト

​Session を作成して実行する

​MCP サーバーと Vault を接続する

​スレッドイベント

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

​ツールの権限と対話

​制限

​トラブルシューティング

​Coordinator が委譲しない

​Coordinator の作成または更新で 400 が返る

​次のステップ

multiagent を設定

Agent スキーマ

Session Threads 一覧

Session Thread オブジェクト

仕組み

委譲に適した作業

Coordinator を設定する

コンソールで設定する

API で Agent を作成する

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

API で Agent を更新する

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

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

Advisor の設定

相談の流れ

イベントと失敗

中断と削除

コストとコンテキスト

Session を作成して実行する

MCP サーバーと Vault を接続する

スレッドイベント

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

ツールの権限と対話

制限

トラブルシューティング

Coordinator が委譲しない

Coordinator の作成または更新で 400 が返る

次のステップ