advisor tool (アドバイザーツール)

アドバイザーは会話全体を読み、計画や軌道修正を返します。そのあとのタスクは実行モデルが続けます。アドバイザーをいつ呼び出すかは、ほかのツールと同じように実行モデルが判断します。

アドバイザーへの相談は、ひとつの /v1/messages リクエストの中で完結し、利用側で追加の往復は発生しません。例外は呼び出しの途中で一時停止したターンで、これは続きのリクエストで再開します。stop_reason が "pause_turn" で終わったターンを再開するには、そのアシスタントメッセージを server_tool_use ブロックを残したまま内容を変えずに messages に追加し、同じアドバイザーツールとベータヘッダーでもう一度リクエストを送ります。

アドバイザー自身はツールもコンテキスト管理も使わずに動きます。アドバイザーの thinking ブロックは結果が返る前に取り除かれ、実行モデルに届くのは助言のテキストだけです。

advisor_redacted_result の場合、encrypted_content フィールドには利用側で読めない不透明なデータが入ります。次のリクエストでサーバーがこれを復号し、平文として実行モデルのプロンプトに組み込みます。

アドバイザーの呼び出しが失敗した場合、実行モデルはエラーを受け取り、それ以降は助言なしで作業を続けます。リクエスト自体は失敗しません。

アドバイザーモデルは Claude Sonnet 4.6 以上の性能のモデルで、かつ実行モデルと同等以上の性能である必要があります。

• 2026 年 5 月 28 日に、advisor tool は Claude Opus 4.8 に対応しました。
• Claude Sonnet 5.5 での変更点として、advisor tool は Claude Opus 4.8、Claude Opus 4.7、Claude Sonnet 5 をアドバイザーとして受け付けません。

• 1 ターンの呼び出し回数: max_uses で 1 ターンに許可するアドバイザー呼び出しの最大回数を設定します。
• 会話全体の呼び出し回数: 会話全体で上限を設けるには、呼び出し回数をクライアント側で数え、上限に達したら tools からアドバイザーツールを外します。このとき、履歴から advisor_tool_result ブロックは削除しません。
• 出力の上限: アドバイザーツール定義の tools[].max_tokens で、呼び出しごとのアドバイザーの出力 (thinking とテキストの合計) に上限を設けます。最小値は 1024 です。アドバイザーモデル自体の出力上限を超える値を設定すると 400 エラーが返ります。
• 呼び出しの強制: 特定のリクエストで必ず相談させるには、tool_choice を {"type": "tool", "name": "advisor"} に設定します。Forcing tool use の制約が適用されます。
• アドバイザー側のキャッシュ: ツール定義に caching を設定すると、同じ会話内の呼び出しをまたいで、アドバイザー自身のやり取りに prompt caching が有効になります。

"caching": {"type": "ephemeral", "ttl": "5m"}

アドバイザーの推論はストリーミングされません。アドバイザーが動いている間、実行モデルのストリームは一時停止し、その後に結果全体がひとつのイベントで届きます。

アドバイザーの使用量は usage.iterations[] 配列に記録されます。トップレベルの usage フィールドは実行モデルのトークンだけを表します。

Claude Managed Agents では、エージェントの multiagent ブロックに "advisor": {"type": "enabled", "model": ...} を設定すると、セッションのプライマリスレッドがターンの途中でそのモデルに相談できます。助言はレスポンス内の advisor_tool_result ブロックではなく、セッションのイベントストリーム上のスレッドイベントとして届きます。

advisor tool はベータとして提供されています。以下は Messages API で使う場合の流れです。

1. リクエストにベータヘッダー advisor-tool-2026-03-01 を含めます。
2. リクエストの tools に、type が advisor_20260301 のアドバイザーツールを、使うアドバイザーモデルを指定して追加します。
3. 以降のリクエストでは、advisor_tool_result ブロックを含むアシスタントの内容全体を、手を加えずにそのまま API に戻します。