マルチエージェントセッション

マルチエージェントはResearch Preview機能です。試すにはアクセスをリクエストしてください。

マルチエージェントオーケストレーションにより、1つのエージェントが他のエージェントと連携して複雑な作業を完了できます。エージェントはそれぞれ独立したコンテキストで並行して動作でき、出力品質の向上と完了までの時間短縮に役立ちます。

すべてのManaged Agents APIリクエストにはmanaged-agents-2026-04-01ベータヘッダーが必要です。Research Preview機能には追加のベータヘッダーが必要です。SDKはこれらのベータヘッダーを自動的に設定します。

仕組み

すべてのエージェントは同じコンテナとファイルシステムを共有しますが、各エージェントは独自のセッションスレッド（独自の会話履歴を持つコンテキスト分離されたイベントストリーム）で実行されます。コーディネーターはプライマリスレッド（セッションレベルのイベントストリームと同じ）でアクティビティを報告し、コーディネーターが委任を決定すると追加のスレッドが実行時に生成されます。

スレッドは永続的です。コーディネーターは以前に呼び出したエージェントにフォローアップを送信でき、そのエージェントは以前のターンからすべてを保持しています。

各エージェントは、そのエージェントが作成されたときに定義された独自の設定（モデル、システムプロンプト、ツール、MCPサーバー、スキル）を使用します。ツールとコンテキストは共有されません。

委任すべき内容

マルチエージェントセッションは、全体的な目標の中に複数の明確にスコープされた専門タスクがある場合に最も効果的です：

コードレビュー： 集中したシステムプロンプトと読み取り専用ツールを持つレビュアーエージェント。
テスト生成： 本番コードに触れずにテストを作成・実行するテストエージェント。
リサーチ： Webツールを持ち、調査結果をコーディネーターに要約して返す検索エージェント。

呼び出し可能なエージェントの宣言

エージェントを定義する際に、呼び出しが許可されている追加のエージェントIDを列挙します：

orchestrator=$(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 @- <<EOF
{
  "name": "Engineering Lead",
  "model": "claude-sonnet-4-6",
  "system": "You coordinate engineering work. Delegate code review to the reviewer agent and test writing to the test agent.",
  "tools": [
    {
      "type": "agent_toolset_20260401"
    }
  ],
  "callable_agents": [
    {"type": "agent", "id": "$REVIEWER_AGENT_ID", "version": $REVIEWER_AGENT_VERSION},
    {"type": "agent", "id": "$TEST_WRITER_AGENT_ID", "version": $TEST_WRITER_AGENT_VERSION}
  ]
}
EOF
)

callable_agentsの各エントリは既存のエージェントのIDである必要があります。サポートされる委任は1レベルのみです。コーディネーターは他のエージェントを呼び出せますが、それらのエージェントは独自のエージェントを呼び出すことはできません。

次に、オーケストレーターを参照するセッションを作成します：

呼び出し可能なエージェントはオーケストレーターの設定から解決されます。セッション作成時にそれらを参照する必要はありません。

セッションスレッド

セッションレベルのイベントストリーム（/v1/sessions/:id/stream）はプライマリスレッドとみなされ、すべてのスレッドにわたるすべてのアクティビティの要約ビューを含みます。呼び出されたエージェントの個別のトレースは表示されませんが、それらの作業の開始と終了は確認できます。セッションスレッドは、特定のエージェントの推論とツール呼び出しを詳しく調べる場所です。

セッションのステータスもすべてのエージェントアクティビティの集約です。少なくとも1つのスレッドがrunning状態であれば、全体的なセッションステータスもrunningになります。

セッション内のすべてのスレッドを一覧表示するには：

特定のスレッドからイベントをストリーミングする：

スレッドの過去のイベントを一覧表示する：

マルチエージェントイベントタイプ

これらのイベントは、トップレベルのセッションストリームにマルチエージェントアクティビティを表示します。

タイプ	説明
`session.thread_created`	コーディネーターが新しいスレッドを生成しました。`session_thread_id`と`model`を含みます。
`session.thread_idle`	エージェントスレッドが現在の作業を完了しました。
`agent.thread_message_sent`	エージェントが別のスレッドにメッセージを送信しました。`to_thread_id`と`content`を含みます。
`agent.thread_message_received`	エージェントが別のスレッドからメッセージを受信しました。`from_thread_id`と`content`を含みます。

スレッドにおけるツール権限とカスタムツール

callable_agentスレッドがクライアントから何か（always_askツールを実行する権限、またはカスタムツールの結果）を必要とする場合、リクエストはsession_thread_idフィールドとともにセッションストリームに表示されます。プラットフォームが待機中のスレッドにルーティングできるよう、応答を投稿する際に同じsession_thread_idを含めてください。

session_thread_idが存在する場合： イベントはサブエージェントスレッドから発生しました。返信にそれをエコーしてください。
session_thread_idが存在しない場合： イベントはプライマリスレッドから来ました。フィールドなしで返信してください。
リクエストと応答を対応付けるためにtool_use_idでマッチングしてください。

以下の例は、返信をルーティングするためにツール確認ハンドラーを拡張しています。同じパターンがuser.custom_tool_resultにも適用されます。

session=$(curl -fsS https://api.anthropic.com/v1/sessions \
  -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 '{"agent": "'$ORCHESTRATOR_ID'", "environment_id": "'$ENVIRONMENT_ID'"}')

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.agent_name)] \(.status)"'

curl -fsSN "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/stream" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" |
  while IFS= read -r line; do
    [[ $line == data:* ]] || continue
    json=${line#data: }
    case $(jq -r '.type' <<<"$json") in
      agent.message)
        printf '%s' "$(jq -j '.content[] | select(.type == "text") | .text' <<<"$json")"
        ;;
      session.thread_idle)
        break
        ;;
    esac
  done

curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/threads/$THREAD_ID/events" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: managed-agents-2026-04-01" \
  | jq -r '.data[] | "[\(.type)] \(.processed_at)"'

while IFS= read -r event_id; do
  pending=$(jq -r --arg id "$event_id" '.[$id]' <<<"$events_by_id")
  thread_id=$(jq -r '.session_thread_id // empty' <<<"$pending")
  jq -n --arg id "$event_id" --arg thread "$thread_id" '
    {events: [
      {type: "user.tool_confirmation", tool_use_id: $id, result: "allow"}
      + (if $thread != "" then {session_thread_id: $thread} else {} end)
    ]}' |
    curl -fsS "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?beta=true" \
      -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 @-
done < <(jq -r '.stop_reason.event_ids[]' <<<"$data")