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-5"}
      ]
    }
  }'

この例では、claude-sonnet-5 で動く「Backend engineer」エージェントに、claude-opus-5-5 のadvisorを1件だけ持つrosterを与えています。system に「主要な設計判断の前にadvisorへ相談する」と書いておくと、エージェントが相談のタイミングを判断しやすくなります。この例のadvisorは claude-opus-5-5 で、結果が暗号化される側のモデルです。クライアントに届く助言は redacted のプレースホルダーになります。

rosterに置けるadvisorエントリは最大1件で、agent 参照や self といった他のroster形式とも共存できます。advisorは予約された名前 anthropic.advisor を占有するため、advisorエントリと、文字どおり anthropic.advisor という名前のメンバーを同じrosterに置くと400エラーで拒否されます。レスポンスでは、送信時の位置に関わらずadvisorエントリが末尾に並びます。

advisorはroster内の他エージェントと違い、コーディネーターの list_agents ツールには見えず、send_to_agent で直接メッセージを送ることもできません。相談できるのはセッションのプライマリスレッドだけです。他の委譲先を一切置かずadvisorだけを加える最小構成も使えるので、委譲は不要でも設計判断の節目でセカンドオピニオンが欲しい、という使い方に向きます。

呼び出される場面は、方針の検討(実装に入る前にアプローチを練る)、行き詰まりの打開(単独では判断がつかないときの助言)、完了前のレビュー(作業を終える前の見直し)などです。

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

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

コンサルテーション中は agent.tool_use イベントが発生せず、セッションのイベントストリームに agent.thread_message_sent も現れません。相談の入力はエージェントではなくプラットフォーム側が組み立てるためです。advisorスレッド自身のイベントを一覧すると、同じ助言が 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 で現れます。

モデルの組み合わせで決まる制約

advisorのモデルは、Claude Sonnet 4.6以上の能力を持つことが条件です。加えて、エージェント自身のモデルがadvisorより高性能であってはいけません。能力が同等のモデル同士(Claude Opus 4.7とOpus 4.8など)は組み合わせられ、無効な組み合わせはエージェント保存時に400エラーで拒否されます。有効な組み合わせの全体は、Messages APIのadvisor toolが持つモデル互換性の表に従います。

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

Messages API側は、リクエストごとに上限や回数を細かく調整できます。Managed Agents側はエージェント定義に一度書けばセッションを跨いで使い回せる代わりに、これらの調整余地がありません。

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

クライアントが助言を読めるかどうかは、advisorモデル側の結果ポリシーで決まります。Messages APIのadvisor toolで結果が暗号化される条件と同じ分岐が、ここでも働きます。プレーンテキストを返すモデルなら読める助言がイベントに載り、redacted resultを返すモデルなら、どのクライアント面でも [{"type": "redacted"}] というプレースホルダーが載ります。どちらの場合も、エージェント自身はサーバー側で助言全文を読んでいます。

どのモデルが暗号化側かは、Messages APIのadvisor toolの説明にまとまっています。Claude Sonnet 5.5・Fable 5.1・Mythos 5.1・Opus 5.5・Opus 5・Fable 5・Mythos 5が暗号化側です。それ以外の互換表のモデル(Opus 4.8・4.7・4.6、Sonnet 5、Sonnet 4.6)は平文を返します。advisorの思考過程(thinking)は、どちらの場合もクライアントには表示されません。クライアントから redacted ブロックを自分で送ることはできず、含むイベントは400エラーで拒否されます。

実行役によっては、読めるadvisorが存在しない

「助言を読みたいならOpus 4.8を選ぶ」は、実行役のモデルによっては成り立ちません。互換性の表を実行役ごとに引くと、平文を返すadvisorを選べる組み合わせは次のとおりです。

最後の行の実行役は、暗号化を返すadvisorとしか組めません。助言の中身をイベントストリームに残したい要件があるなら、実行役のモデルを選ぶ段階で表の下の行を避ける必要があります。冒頭のcurl例のように実行役がSonnet 5なら、advisorを claude-opus-4-8 に替えるだけで助言が読めるようになります。

{"type": "advisor", "model": "claude-opus-4-8"}

このように、Opus 5.5を選べば助言は読めず、Opus 4.8を選べば読める、という取引になります。どちらを優先するかは、助言のログを監査や振り返りに使うかどうかで分かれます。

監視で気をつけること

advisorのイベントは、通常のroster agentと同じ種類のスレッドイベントで流れます。区別する手がかりは予約名 anthropic.advisor で、スレッドの開始・終了などのイベントでは agent_name に、助言の配信イベントでは from_agent_name に入ります。フィールド名が違う点に注意して分岐させないと、advisorへの相談が通常の委譲と同じログに混ざり、コーディネーターがどのエージェントに何を頼んだかを追いにくくなります。

コンサルテーションが失敗してもターンは止まらず、汎用的な通知だけでエージェントが処理を続けるため、失敗は表に出にくくなります。相談が想定どおり働いているかは、agent.thread_message_received の到着数と、anthropic.advisor のスレッドが session.thread_status_terminated に達した回数を並べると見えてきます。両者の差が開いていれば、助言なしで終わった(失敗・中断)相談が含まれている可能性があります。

advisorを外す・課金

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

advisor側のプロンプトキャッシュは自動で有効になり、設定項目はありません。コンサルテーションはadvisorモデルのレートで課金され、そのトークンはadvisorスレッドの使用量と、セッション全体の使用量合計の両方に載ります。実行役より上位のモデルをadvisorにするほど、相談1回あたりの単価は実行役のターンより高くなりやすくなります。

まとめ

Managed Agentsのadvisorは、rosterに1件のエントリを足すだけで、プライマリスレッドが同等以上のモデルへターン途中に相談できる仕組みです。導入の判断で効くのは、助言をクライアント側のログに残したいかどうかで、残したいなら暗号化側の実行役とadvisorを避けた組み合わせを選びます。

Messages APIで先にadvisorを使っているなら、モデル互換性のルールは同じなのでMessages APIのadvisor toolの考え方をそのまま持ち込めます。roster全体の設計とスレッド分離はManaged Agentsでマルチエージェントを編成する方法、Managed Agents全体の設計思想はAgent SDKのManaged Agentsの設計思想にあります。