Managed Agentsのadvisorがプライマリスレッドの判断を助ける仕組み

Managed Agentsのadvisorは、セッションのプライマリスレッドがターンの途中で相談できるモデルです。roster(委譲先の一覧)に {"type": "advisor", "model": ...} を1件加えるだけで有効になり、方針の検討・行き詰まりの打開・完了前のレビューといった場面で呼び出されます。roster内の他のエージェントとは扱いが異なり、コーディネーターからは見えず、相談できるのはプライマリスレッドだけです。マルチエージェント全体の委譲を使わないシンプルな構成でも、advisorだけを単独で足せます。

advisorとは何か

roster内の advisor エントリは type と model の2フィールドだけを持つ特殊な形式です。

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": "Backend engineer",
    "model": "claude-sonnet-5",
    "system": "You implement backend features end to end. Consult the advisor before major backend design decisions.",
    "multiagent": {
      "type": "coordinator",
      "agents": [
        {"type": "advisor", "model": "claude-opus-5"}
      ]
    }
  }'

rosterに置けるadvisorエントリは最大1件です。advisorは予約された名前 anthropic.advisor を占有するため、advisorエントリと、文字どおり anthropic.advisor という名前のメンバーを同じrosterに両方置くと400エラーで拒否されます。レスポンス内では、送信時の位置に関わらずadvisorエントリが常にroster末尾に表示されます。

advisorはroster内の他エージェントと違い、コーディネーターの list_agents ツールには見えず、send_to_agent で直接メッセージを送ることもできません。相談できるのはセッションのプライマリスレッドだけで、roster内の他のエージェントからは相談できません。

この例では、claude-sonnet-5 で動く「Backend engineer」エージェントに、claude-opus-5 のadvisorを1件だけ持つrosterを与えています。他のroster形式(agent 参照や self)と併用してもよく、advisorは常にその他のエントリと共存できます。単体のエージェントに他の委譲先を一切置かず、advisorだけを加える最小構成も可能です。マルチエージェントの委譲は不要でも、設計判断の節目でセカンドオピニオンだけ欲しい、という使い方に向いています。

advisorへ相談すべき場面は、公式が例示している範囲では次の3つに整理できます。

システムプロンプト側で「主要な設計判断の前にadvisorへ相談する」のように明示しておくと、エージェントが自発的に相談のタイミングを判断しやすくなります。

モデルの組み合わせには下限がある

advisorのモデルには最低限の能力基準があり、エージェント自身のモデルはadvisorより高性能であってはいけません。能力が同等のモデル同士は組み合わせ可能です。無効な組み合わせは、エージェント保存時に400エラーで拒否されます。有効な組み合わせの一覧は、Messages APIのadvisor toolが持つモデル互換性の表に従います。

advisorはMessages APIのサーバーツールとしても提供されています。同じadvisorという機能でも、Managed Agentsとメッセージ単位のAPI呼び出しでは設定項目と配信経路が違います。

設定を都度書くMessages API側に対し、Managed Agents側はエージェント定義に一度書けばセッションを跨いで使い回せる分、キャッシュや利用回数の細かい調整余地は手放す設計です。

なぜ実行役より弱いadvisorを許さないのか

実行役のモデルがadvisorより高性能な組み合わせを禁じているのは、相談の意味を保つためです。実行役より弱いadvisorに相談しても、実行役が既に知っている以上の判断材料は出てきません。逆に実行役と同格以上のモデルに相談させることで、advisorは「もう一段上の視点からの検算」として機能します。コストをかけてでも判断の質を上げたい場面にだけadvisorを足す、という前提の制約です。

コンサルテーションはどう進むか

各コンサルテーションは、完了すると自動終了する専用スレッド(名前は anthropic.advisor)として実行されます。助言はプライマリスレッドに agent.thread_message_received イベントとして届きます。典型的なイベント順序は次のとおりです。

コンサルテーション中は agent.tool_use イベントが発生せず、セッションのイベントストリームに agent.thread_message_sent も現れません。相談の入力はエージェントではなくプラットフォーム側が組み立てるためです。助言(イベント3)がadvisorスレッドのidle・terminatedより先に届く保証はありません。idle・terminatedを助言配信済みの合図として扱わないよう注意します。

失敗または中断したコンサルテーションはエージェントのターン自体を失敗させません。汎用的な失敗通知のあと、エージェントは処理を続けます。コンサルテーション中にセッションレベルの user.interrupt を送るとadvisorスレッドは助言なしで終了し、advisorスレッドの session_thread_id を指定した場合はそのコンサルテーションだけが打ち切られます。

advisorのコンサルテーションスレッドは、roster内の通常エージェントに課される同時実行数の上限(合計25スレッド)の対象外です。スレッド一覧には、設定どおりの {"type": "advisor", "model": ...} という agent の値と、プライマリスレッドを指す parent_thread_id で現れます。

助言が読めないことがある — redacted result

クライアントが助言を読めるかどうかは、advisorモデル側のポリシーで決まります。これはMessages APIのadvisor toolにおける結果が暗号化される条件と同じ分岐です。プレーンテキストの結果を返すadvisorモデルは、ここでも読める形の助言をテキストコンテンツとして届けます。一方、redacted resultを返すadvisorモデルは、どのクライアント面でも [{"type": "redacted"}] というプレースホルダーをメッセージ内容として届けます。この場合もエージェント自身はサーバー側で助言全文を読んでいます。

Claude Opus 5をadvisorに使うとredacted結果になるため、クライアント側は先ほどのプレースホルダーしか見えません。イベントストリーム上で助言を読めるようにしたい場合は、Claude Opus 4.8をadvisorに選びます。advisorの思考過程(thinking)はどちらの場合もクライアントには表示されません。クライアント側から redacted ブロックを自分で送ることはできず、それを含むイベントは400エラーで拒否されます。

監視で気をつけること

advisorのイベントは通常のroster agentのイベントと形が同じため、監視コードを書くときは agent_name が予約名 anthropic.advisor かどうかで分岐させます。取り違えると、advisorへの相談を通常の委譲と同じログに混ぜてしまい、後から「コーディネーターがどのエージェントに何を頼んだか」を追いにくくなります。

失敗が静かに握りつぶされる点にも注意が必要です。コンサルテーションが失敗してもターンは止まらず、汎用的な通知だけでエージェントは処理を続けます。advisorへの相談が想定どおり効いているかを確認したいなら、agent.thread_message_received の有無をログで見張るか、anthropic.advisor という名前のスレッドがどのくらいの頻度で session.thread_status_terminated に到達しているかを別途集計する必要があります。エラーが表に出ないぶん、動作確認はクライアント側の責任になります。

advisorを外す・課金

advisorを外すには、advisorエントリを含まないrosterでエージェントを更新します。rosterの唯一のエントリがadvisorだった場合は、"multiagent": null を設定してroster自体を空にします。

advisor側のプロンプトキャッシュは自動で有効になり、設定項目はありません。コンサルテーションはadvisorモデルのレート課金で計算され、そのトークンはadvisorスレッドの使用量とセッション全体の使用量合計の両方に反映されます。頻繁に相談させるほどこの合計は積み上がるため、セッションのbudgetを設定している場合は消費ペースに含めて見積もっておきます。

まとめ

Managed Agentsのadvisorは、rosterに1件の {"type": "advisor", "model": ...} を加えるだけで、プライマリスレッドが自分と同等以上の能力のモデルへターン途中に相談できる仕組みです。相談は専用スレッドで自動的に発生・終了し、助言はイベントとして届きますが、advisorモデルの結果ポリシー次第ではクライアント側にプレースホルダーしか見えないことがあります。Messages APIのadvisor toolと同じモデル互換性ルールを共有するため、Messages APIのadvisor toolを先に使っているチームは設定の考え方をそのまま持ち込めます。

roster全体の設計・スレッド分離の基本はManaged Agentsでマルチエージェントを編成する方法、Managed Agents全体の設計思想はAgent SDKのManaged Agentsの設計思想を参照してください。

導入コストが低い一方、動作確認は自前でやる必要がある機能でもあります。コンサルテーションが失敗してもエージェントのターンは止まらず、advisorモデルの結果ポリシー次第では助言そのものがクライアントから見えないこともあるためです。導入するなら、まずはClaude Opus 4.8のようなプレーンテキスト応答のモデルをadvisorに選び、イベントストリーム上で助言の中身をひととおり確認しながら運用を固めるのが手堅い進め方です。