Managed Agentsでマルチエージェントを編成する方法 — コーディネーターとスレッド設計

Managed Agentsのマルチエージェント編成は、1つのコーディネーターが複数のエージェントへ作業を分担させる仕組みです。各エージェントは独立したコンテキストで動き、並列に処理を進められます。連携の要は multiagent フィールドとスレッド分離の2つです。roster(委譲先の一覧)を宣言し、コーディネーターが実行時にスレッドを生成して作業を渡します。

Managed Agentsのマルチエージェントとは何か

複数のエージェントが同じサンドボックス・ファイルシステム・vault認証情報を共有しつつ、それぞれ独自のセッションスレッドで動く仕組みです。セッションスレッドはコンテキストが分離された独立の会話履歴で、モデル・システムプロンプト・ツール・MCPサーバー・skillsもエージェントごとに個別設定できます。

コーディネーターの活動はプライマリスレッド(セッションレベルのイベントストリームと同一)に集約されます。委譲が発生すると、そのつどスレッドが実行時に生成される仕組みです。スレッドは永続します。コーディネーターは以前呼び出したエージェントへ追加の指示を送れて、相手はそれまでの会話をすべて覚えています。

向いているパターンは3つあります。

コーディネーターを設定する

multiagent に type: "coordinator" と委譲先の agents 配列を指定します。

curl -fsS https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "Engineering Lead",
    "model": "claude-opus-5",
    "tools": [{"type": "agent_toolset_20260401"}],
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "agent", "id": "'"$REVIEWER_AGENT_ID"'"},
        {"type": "agent", "id": "'"$TEST_WRITER_AGENT_ID"'"}
      ]
    }
  }'

CLIの ant apply を使う場合、コーディネーターとroster内の各エージェントを別々のMarkdownファイルとして定義し、まとめて適用できます。

ant apply engineering-lead.md reviewer.md test-writer.md

engineering-lead.md のfrontmatterで multiagent.agents に ./reviewer.md のようなファイルパスを書くと、applyがそのエージェントを先に作成し、パスを固定済みの {"type": "agent", "id": ..., "version": ...} 参照へ自動的に置き換えます。エージェント定義をリポジトリでバージョン管理したいチームには、このパス参照の方がID直書きより扱いやすい構成です。

multiagent.agents の各エントリには4つの形式があります。

roster内の参照はコーディネーター作成・更新時点でスナップショットされます。参照先エージェントを後から更新しても、rosterのバージョン固定は自動追随しません。新しいバージョンへ委譲したい場合は、コーディネーター側を更新してrosterの参照を差し替えます。

委譲は1階層までです。roster内のエージェントがさらに自分の multiagent.agents を持っていると、コーディネーターの作成・更新自体が検証エラーで失敗します。rosterに列挙できるエージェントは最大20体ですが、同じエージェントの複数コピーを呼び出すことは可能です。

エージェント間はどう連携するか — スレッドとイベント

セッションの status は全スレッドの活動を集約したものです。1つでも running のスレッドがあれば、セッション全体のstatusも running になります。同時に持てるスレッド数は最大25で、これはアドバイザーの相談スレッドを除いた上限です。

セッションのbudgetは、セッション内の全スレッドで共有する単一の上限です。上限に達すると各スレッドは個別に一時停止し、それぞれのコストはそのスレッドが実際に使ったモデルの単価で計算されます。エージェントごとにモデルを変えている構成では、高性能なモデルのスレッドほど先にbudgetを消費しやすい点に注意します。

プライマリスレッドで観測できる主なイベントは次のとおりです。

プライマリスレッドには全スレッドの要約(開始・終了・ツール権限リクエストなどのブロッキングイベント)しか流れません。特定エージェントの詳細な思考やツール呼び出しを追いたい場合は、そのエージェント専用のスレッドイベントストリーム(/v1/sessions/{session_id}/threads/{thread_id}/stream)を個別に購読します。子スレッドのプレビューはセッションレベルのストリームには出てこないため、サブエージェントの生成過程をリアルタイムで見たいなら、そのスレッド自体を開く必要があります。

特定のスレッドだけを止めたいときは user.interrupt に session_thread_id を指定します。省略すると、プライマリを含む全ての非アーカイブスレッドが対象になります。

MCPサーバーとvaultはエージェントごとに接続する

MCPサーバーはエージェント定義ごとにスコープされ、vault認証情報はセッション単位でスコープされます(セッション作成時に渡す vault_ids は全スレッドに適用)。この非対称から、実装上の注意点が2つ出てきます。

• MCPサーバーを認証するには、全エージェントが使うMCPサーバーの数だけvault認証情報をセッションに含める
• エージェントのアクセス範囲を絞るには、そのエージェント定義に必要なサーバーだけを宣言する

セッション作成時のエージェント設定オーバーライドは、コーディネーターとその self コピーのMCPサーバーを置き換えられますが、roster内の他エージェントには適用されません。

委譲に向くタスクと向かないタスク

コーディネーターへ何を任せるかは、タスクの性質で判断します。

inference_geo(推論地域)をピン留めしているエージェントが混在する場合も制約があります。コーディネーターとroster内の全メンバーは、ピンを全員同じ値に揃えるか、全員未設定にする必要があります。混在は400エラーで拒否されます。

サブエージェントが権限確認を求めたらどうなるか

委譲先のエージェントが always_ask 設定のツールを実行しようとしたり、カスタムツールの結果をクライアントから受け取る必要があったりすると、そのイベントは発生元の session_thread_id を添えてプライマリスレッドにも転送されます。

{
  "type": "session.thread_status_idle",
  "id": "sevt_01ABC...",
  "session_thread_id": "sth_01DEF...",
  "agent_name": "code-reviewer",
  "stop_reason": {
    "type": "requires_action",
    "event_ids": ["sevt_01XYZ..."]
  }
}

stop_reason.type が requires_action のとき、クライアントは user.tool_confirmation(tool_use_id を指定)または user.custom_tool_result(custom_tool_use_id を指定)を送り返します。サーバー側が自動的に該当スレッドへルーティングするため、クライアントはどのスレッドが発行元かを気にせず単一のハンドラーで処理を書けます。プライマリスレッドを監視しているだけで、末端のサブエージェントが止まっている理由と再開に必要な応答の両方が分かる設計です。

特定のスレッドだけを止めて片づけたい場合は、user.interrupt でそのスレッドを中断したあと、archive エンドポイントでスレッドをアーカイブします。アーカイブ済みスレッドは一覧のデフォルト表示から外れますが、IDを指定すれば引き続き参照できます。

Claude Codeのサブエージェントとは何が違うか

Claude Codeのサブエージェント(ファイルベースで定義し、メインの会話コンテキストから起動する)と、Managed Agentsのマルチエージェントは似た発想に見えますが、運用の単位が違います。Claude Codeのサブエージェントは1つのローカルセッション内の並列実行が主眼で、深さ・並列数・支出の上限をハーネス側の設定で縛る運用が前提です。Managed Agentsのコーディネーターは、APIリソースとして永続化したエージェント定義同士をrosterで結び、スレッド単位で課金・イベント・権限を分離する設計です。1階層までという委譲の制約も、この「エージェント定義をAPIリソース化する」設計と裏表の関係にあります。

観測性の作り方も異なります。Claude Codeのサブエージェントはローカルプロセスの出力をそのまま見られますが、Managed Agentsではプライマリスレッドが要約だけを受け取り、詳細を見るには子スレッド自身のイベントストリームを個別に開く必要があります。API経由で複数チームやサービスが同じコーディネーターを共有する運用を前提にした分だけ、観測の粒度を意識的に分けている設計です。

サンドボックス・ファイルシステム・vaultは共有される

roster内の全エージェントは同じサンドボックスとファイルシステムを見ます。あるエージェントが書き込んだファイルは、別のエージェントも同じパスで参照できます。vault認証情報もセッション単位で共有されるため、認証が必要な外部サービスへ複数のエージェントが同じ資格情報でアクセスする構成が組めます。共有されないのはツール・MCPサーバー・会話コンテキストの3つで、これらはエージェントごとに独立しています。役割ごとにアクセス範囲を絞りたいときは、共有されるもの(ファイル・vault)ではなく、独立しているもの(ツール定義・MCPサーバーの宣言)側で制御する設計だと理解しておくと迷いません。

まとめ

Managed Agentsのマルチエージェント編成は、multiagent.agents にroster(agent参照 / self / advisor)を宣言し、コーディネーターが実行時にスレッドを生成する仕組みです。エージェントごとにモデル・ツール・MCPサーバーを独立させられる一方、委譲は1階層まで、rosterは最大20体、同時スレッドは25までという制約があります。並列化・専門化・エスカレーションのいずれかに当てはまるタスクなら委譲を検討する価値があり、単一の直線的な作業ならコーディネーターを挟まないほうがシンプルです。

rosterにアドバイザーを加えてコーディネーターの判断そのものを補助する構成は、Managed Agentsのマルチエージェントにアドバイザーをつけるで扱います。Managed Agents全体の設計思想はAgent SDKのManaged Agentsの設計思想を参照してください。