アドバイザーツール

「advisor tool」（アドバイザーツール）を使用すると、より高速で低コストな「executor model」（エグゼキューターモデル）が、生成の途中でより高知能な「advisor model」（アドバイザーモデル）に戦略的なガイダンスを求めることができます。アドバイザーは会話全体を読み取り、計画や軌道修正を作成し、エグゼキューターはタスクを続行します。

このパターンは、ほとんどのターンが機械的な作業である一方で、優れた計画を持つことが極めて重要となる長期的なエージェントワークロード（コーディングエージェント、コンピューター使用、多段階のリサーチパイプライン）に適しています。トークン生成の大部分はエグゼキューターモデルの料金で行われながら、アドバイザー単独に近い品質を得られます。エグゼキューター自身の能力がアドバイザーに近づくにつれてメリットがどのように縮小するかを含む測定結果については、コストと知能の最適化を参照してください。

使用すべき場面

アドバイザーは次の構成に適しています。

• 現在、複雑なタスクにSonnetを使用している場合： 上位ティアのアドバイザーを追加します。Opusを使えば総コストを同程度かそれ以下に抑えられ、Claude Fable 5.1を使えば品質の向上を最大化できます。
• 現在Haikuを使用しており、知能を一段階引き上げたい場合： OpusまたはFableのアドバイザーを追加します。Haiku単独よりもコストは高くなりますが、エグゼキューターをより大きなモデルに切り替えるよりは低く抑えられます。

結果はタスクに依存します。ご自身のワークロードで評価してください。

アドバイザーは、シングルターンのQ&A（計画すべきものがない）、ユーザーがすでに自分でコストと品質のトレードオフを選択している純粋なパススルー型のモデル選択機能、またはすべてのターンで本当にアドバイザーモデルの能力を最大限に必要とするワークロードにはあまり適していません。

クイックスタート

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-5",
        }
    ],
    messages=[
        {
            "role": "user",
            "content": "Build a concurrent worker pool in Go with graceful shutdown.",
        }
    ],
)

print(response)

レスポンスの content には、アドバイザーのガイダンスを含む advisor_tool_result ブロックが含まれます。このクイックスタートのように claude-opus-5 をアドバイザーとして使用する場合、ブロックの content フィールドは advisor_redacted_result バリアントになります（暗号化されており、エグゼキューターはサーバー側でそれを読み取りますが、クライアントは読み取れません）。レスポンス内でアドバイスのテキストを直接確認するには、代わりに claude-opus-4-8 をアドバイザーモデルとして使用してください。こちらはプレーンテキストの advisor_result バリアントを返します。両方の形式の比較と、どのアドバイザーモデルがどちらを返すかについては結果バリアントを、有効な組み合わせの完全な一覧についてはモデルの互換性を参照してください。

仕組み

アドバイザーツールを tools 配列に追加すると、他のツールと同様に、エグゼキューターモデルがいつそれを呼び出すかを判断します。エグゼキューターがアドバイザーを呼び出すと、次のように処理されます。

1. エグゼキューターが、name: "advisor" と空の input を持つ server_tool_use ブロックを出力します。エグゼキューターはタイミングを通知し、コンテキストはサーバーが提供します。
2. Anthropicがサーバー側でアドバイザーモデルに対して別個の推論パスを実行します。アドバイザーはAnthropicが提供する独自のシステムプロンプトの下で実行され、エグゼキューターの完全なトランスクリプトを引用されたコンテキストとして入力に受け取ります。このトランスクリプトには、あなたのシステムプロンプト、ツール定義、これまでのターンとツール結果、そしてこのターンでエグゼキューターがこれまでに生成したテキストが含まれます。
3. アドバイザーの応答は advisor_tool_result ブロックとしてエグゼキューターに返されます。
4. エグゼキューターはアドバイスを踏まえて生成を続行します。

これらはすべて単一の /v1/messages リクエスト内で行われ、あなたの側で追加のラウンドトリップは発生しません。例外は呼び出しの途中で一時停止したターンで、これはフォローアップリクエストで再開します（一時停止したターンの再開を参照）。

アドバイザー自体はツールもコンテキスト管理もなしで実行されます。その思考ブロックは結果が返される前に破棄されます。エグゼキューターに届くのはアドバイスのテキストのみです。

ツールパラメータ

caching オブジェクトの形式は {"type": "ephemeral", "ttl": "5m" | "1h"} です。コンテンツブロックの cache_control とは異なり、これはブレークポイントのマーカーではありません。オン/オフのスイッチです。キャッシュの境界をどこに置くかはサーバーが決定します。

アドバイザーツールは、任意のツール定義で使用できる汎用プロパティ cache_control、allowed_callers、defer_loading、strict（構造化出力で説明）も受け付けます。これらのセマンティクスについてはツールリファレンスを参照してください。

レスポンス構造

アドバイザー呼び出しの成功

アドバイザーが呼び出されると、アシスタントのコンテンツ内で server_tool_use ブロックの後に advisor_tool_result ブロックが続きます。次の例は、Claude Opus 4.8アドバイザーが返すプレーンテキストの advisor_result バリアントを示しています。クイックスタートではClaude Opus 5を使用しており、こちらは代わりに暗号化された advisor_redacted_result バリアントを返します。両方の形式の比較については結果バリアントを参照してください。

{
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": "Let me consult the advisor on this."
    },
    {
      "type": "server_tool_use",
      "id": "srvtoolu_abc123",
      "name": "advisor",
      "input": {}
    },
    {
      "type": "advisor_tool_result",
      "tool_use_id": "srvtoolu_abc123",
      "content": {
        "type": "advisor_result",
        "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
      }
    },
    {
      "type": "text",
      "text": "Here's the implementation. I'm using a channel-based coordination pattern to avoid writer starvation..."
    }
  ]
}

server_tool_use.input は常に空です。サーバーは完全なトランスクリプトからアドバイザーのビューを自動的に構築します。エグゼキューターが input に入れたものは、何もアドバイザーに届きません。

結果バリアント

advisor_tool_result.content フィールドは判別共用体（discriminated union）です。呼び出しが成功した場合、バリアントはアドバイザーモデルによって異なります。

以下は、ツール定義内のアドバイザーの model 以外は同一のリクエストを2回送信し、両方のバリアントを示したものです。

"model": "claude-opus-4-8" の場合、アドバイスはプレーンテキストです。

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is draining in-flight work during shutdown: close the input channel first, then wait on a WaitGroup..."
  }
}

"model": "claude-opus-5" の場合、アドバイスは暗号化されています。

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ5ZjE0N2M2OC0yYWIxLTRkZTktYjA3ZC1hZTUyMzkxYjhkMmU..."
  }
}

どちらの結果バリアントも、ツール定義で max_tokens を設定した場合は stop_reason フィールドを持ち、設定しない場合は省略されます。これにはアドバイザーのサブ呼び出しの停止理由が格納され、通常は "end_turn"、上限に達した場合は "max_tokens" です。値はトップレベルのMessages APIの stop_reason と一致します。

advisor_result の場合、text フィールドには人間が読めるアドバイスが含まれます。advisor_redacted_result の場合、encrypted_content フィールドには読み取ることのできない不透明なblobが含まれます。次のターンで、サーバーがそれを復号し、プレーンテキストをエグゼキューターのプロンプトにレンダリングします。

どちらの場合も、以降のターンではコンテンツをそのまま往復させてください。会話の途中でアドバイザーモデルを切り替える場合は、content.type で分岐して両方の形式を処理してください。

エラー結果

アドバイザーの呼び出しが失敗した場合、結果にはエラーが含まれます。

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_tool_result_error",
    "error_code": "overloaded"
  }
}

エグゼキューターはエラーを確認し、それ以上のアドバイスなしで続行します。リクエスト自体は失敗しません。

アドバイザーのレート制限は、アドバイザーモデルへの直接呼び出しと同じモデルごとのバケットから消費されます。アドバイザーのレート制限は、ツール結果内の too_many_requests として表れます。エグゼキューターのレート制限は、HTTP 429でリクエスト全体を失敗させます。

マルチターン会話

後続のターンでは、advisor_tool_result ブロックを含むアシスタントのコンテンツ全体をAPIに返してください。結果ブロックはそのまま往復させます。Claude Opus 5アドバイザーの場合、結果ブロックの content は暗号化された advisor_redacted_result バリアントであり、次のターンでサーバーがそれを復号してアドバイスをエグゼキューターのプロンプトに展開します（結果バリアントを参照）。仕組みはどのアドバイザーモデルでも同じです。

client = anthropic.Anthropic()

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
    }
]

messages = [
    {
        "role": "user",
        "content": "Build a concurrent worker pool in Go with graceful shutdown.",
    }
]

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

# advisor_tool_result ブロックを含む、レスポンスの内容全体を追加します
messages.append({"role": "assistant", "content": response.content})

# 会話を続けます
messages.append({"role": "user", "content": "Now add a max-in-flight limit of 10."})

response = client.beta.messages.create(
    model="claude-sonnet-5",
    max_tokens=1024,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

メッセージ履歴に advisor_tool_result ブロックが含まれたままでも、フォローアップのターンで tools からアドバイザーツールを削除できます。リクエストは受け付けられ、履歴内のブロックは保持されますが、そのターンではモデルはアドバイザーを呼び出せません。これらの履歴ブロックが受け付けられるためには、引き続き advisor-tool-2026-03-01 ベータヘッダーを送信する必要があります。

一時停止したターンの再開

アドバイザーの呼び出しがまだ保留中の状態で、レスポンスが stop_reason: "pause_turn" で終了することがあります。その場合、レスポンスにはアドバイザーの server_tool_use ブロックが含まれますが、それに対応する advisor_tool_result はありません。再開するには、そのアシスタントメッセージをコンテンツを変更せずに（server_tool_use ブロックを保持したまま）messages に追加し、同じアドバイザーツールとベータヘッダーを付けてリクエストを再送信します。ユーザーメッセージや tool_result ブロックを追加する必要はありません。APIは保留中のアドバイザー呼び出しを実行し、新しいレスポンスでエグゼキューターのターンを続行します。再開したターンが再び一時停止することもあります。その場合は同じ手順を繰り返してください。再開リクエストからアドバイザーツールを省略すると、保留中の server_tool_use ブロックに実行対象のツール定義がないため、400 invalid_request_error が返されます。呼び出しが保留中の場合は必ずツールを含めてください。一方、エグゼキューターが同じターンであなたのツールのいずれかを呼び出した場合、アドバイザーの呼び出しがまだ保留中のまま、レスポンスは stop_reason: "tool_use" で終了します。通常どおり tool_result ブロックを送信すると、保留中のアドバイザー呼び出しはその次のリクエストの開始時に実行されます。1つのターンでのサーバーツールとクライアントツールの混在を参照してください。

呼び出しが少ないエグゼキューターへの会話途中のナッジ

Haikuエグゼキューターが最初のアシスタントターンでアドバイザーを呼び出さなかった場合は、2番目のアシスタントターンの前に、追加のユーザーメッセージとして短いリマインダーを追加してください。Claude Haiku 4.5エグゼキューターに対するAnthropicの内部行動評価では、これによりタスクの合格率が約7パーセントポイント向上しました。Sonnetエグゼキューターでは、Anthropicのテストにおいてプレーンテキストのナッジに測定可能な効果はありませんでした。以下で説明する呼び出しタイミングに関する考慮事項は、特にSonnetに関連します。Opusエグゼキューターにはナッジを適用しないでください。Opusでは合格率がわずかに低下しました。

デフォルトの NUDGE_TURN が2の場合、リマインダーは通常、モデルがタスクを把握した後、アプローチを確定する前に届きます。

client = anthropic.Anthropic()

NUDGE_TURN = 2  # inject before this assistant turn if no advisor call yet
NUDGE_TEXT = (
    "You have not consulted the advisor yet. If the task has a non-obvious "
    "design decision or a failure mode you haven't ruled out, call advisor "
    "now before committing to an approach."
)
MAX_TURNS = 10  # agent loop cap


def run_your_tools(content):
    # 独自のツールディスパッチに置き換えてください。tool_use ブロックごとに tool_result ブロックを1つ返します。
    return [
        {
            "type": "tool_result",
            "tool_use_id": block.id,
            "content": "Replace with your tool output.",
        }
        for block in content
        if block.type == "tool_use"
    ]


tools = [
    {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},
    # ... その他のツール
]
task = "Build a concurrent worker pool in Go with graceful shutdown."
messages = [{"role": "user", "content": task}]
advisor_called = False

for turn in range(1, MAX_TURNS + 1):
    response = client.beta.messages.create(
        model="claude-haiku-5-5",
        max_tokens=4096,
        betas=["advisor-tool-2026-03-01"],
        tools=tools,
        messages=messages,
    )
    messages.append({"role": "assistant", "content": response.content})
    advisor_called = advisor_called or any(
        block.type == "server_tool_use" and block.name == "advisor"
        for block in response.content
    )
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it
    if response.stop_reason != "tool_use":
        break  # end_turn, or a stop such as max_tokens that needs handling (see below)

    results = run_your_tools(response.content)  # list of tool_result blocks
    if results:
        messages.append({"role": "user", "content": results})
    # システムプロンプトですでに呼び出しを控えるようモデルに指示している場合は、これを省略してください。
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

ループは tool_use または pause_turn 以外の停止理由で終了します。max_tokens によってレスポンスが途中で切れた場合は、切り詰められたアシスタントターンを messages から削除し、より大きな max_tokens で再試行してください。そのターンに tool_use ブロックが含まれていない場合は、代わりにそれを保持し、新しいユーザーメッセージでレスポンスを続行することもできます。切り詰められたアシスタントターンを最後のメッセージとして再送信することはプリフィルにあたり、Claude 4.6以降のモデルでは拒否されます。

ナッジは、同じメッセージ内の兄弟ブロックとしてではなく、ツール結果の後に独立したユーザーメッセージとして追加してください。連続するユーザーメッセージは有効です。Claude Haiku 4.5およびSonnetエグゼキューターに対するAnthropicのテストでは、兄弟ブロックと同等に動作しました。別メッセージの形式にすることで、リマインダーがツール出力と明確に区別されます。

トレードオフ： ナッジは呼び出し率を高めるため、ごく単純なタスクで不要な相談が発生する可能性があります。ワークロードに単純なタスクと複雑なタスクが混在している場合は、NUDGE_TURN を3に引き上げて2ターンのタスクがナッジの発動前に完了するようにするか、すでに計算しているタスクの複雑さのシグナルに基づいてナッジを制御することを検討してください。システムプロンプトにすでに抑制的な文言（「アドバイザーは本当に不確実な場合のために取っておく」など）が含まれている場合は、2つの指示が矛盾するため、ナッジは完全に省略してください。

プレーンテキストのナッジは、Claude Haiku 4.5およびSonnetエグゼキューターに対して非常に強く作用します。Anthropicのテストでは、ナッジを受けた試行の74パーセント（Sonnet）から98パーセント（Claude Haiku 4.5）が、ターン2で即座にアドバイザーを呼び出しました。それがエグゼキューターが問題を読んだりコンテキストを収集したりする前に起こると、結果として生じるアドバイザー呼び出しはコンテキストが乏しく、より適切なタイミングの後の呼び出しを押しのけてしまう可能性があります。ナッジを追加する前に、エグゼキューターのベースラインの初回呼び出しターンを測定してください。エグゼキューターがすでに確実にアドバイザーを呼び出しており、初回呼び出しが通常ターンNで行われる場合は、NUDGE_TURN をNより大きく設定してください。Anthropicのテストでは、ベースラインの初回呼び出しがターン7以降であるワークロードでターン2のナッジを行うと、タスクパフォーマンスが3〜4パーセントポイント低下することと相関していました。ベースラインの呼び出し率が86パーセントだったブラウズワークロードでは、同じナッジによってタスクパフォーマンスを損なうことなくエンゲージメントが向上しました。

ナッジの代わりに特定のリクエストで相談を強制するには、ツール使用の強制の制約に従って、tool_choice を {"type": "tool", "name": "advisor"} に設定します。ツール使用の強制は、手動の拡張思考（thinking: {type: "enabled"}）と組み合わせることはできません。両方を有効にすると、APIは 400 invalid_request_error を返します。適応型思考はツール使用の強制をサポートしています。Claude Opus 5.5、Claude Sonnet 5.5、Claude Fable 5.1、Claude Mythos 5.1のエグゼキューターは tool_choice のタイプ tool と any を拒否するため、これらのモデルでは代わりにプロンプトによるナッジを使用してください。

ストリーミング

アドバイザーのサブ推論はストリーミングされません。アドバイザーの実行中はエグゼキューターのストリームが一時停止し、その後、完全な結果が単一のイベントで届きます。

name: "advisor" を持つ server_tool_use ブロックは、アドバイザー呼び出しの開始を示します。一時停止は、そのブロックが閉じたとき（content_block_stop）に始まります。一時停止中、ストリームは約30秒ごとに送信される標準のSSE ping キープアライブ以外は静かになります。短いアドバイザー呼び出しでは、pingが表示されない場合があります。

アドバイザーが完了すると、advisor_tool_result が単一の content_block_start イベントで完全な形で届きます（デルタはありません）。その後、エグゼキューターの出力のストリーミングが再開されます。

続いて、アドバイザーのトークン数を反映した更新済みの usage.iterations 配列を含む message_delta イベントが送信されます。

使用量と課金

アドバイザーの呼び出しは、アドバイザーモデルの料金で課金される別個のサブ推論として実行されます。使用量は usage.iterations[] 配列で報告されます。

{
  "usage": {
    "input_tokens": 1760,
    "cache_read_input_tokens": 412,
    "cache_creation_input_tokens": 0,
    "output_tokens": 531,
    "iterations": [
      {
        "type": "message",
        "input_tokens": 412,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 89
      },
      {
        "type": "advisor_message",
        "model": "claude-opus-5",
        "input_tokens": 823,
        "cache_read_input_tokens": 0,
        "cache_creation_input_tokens": 0,
        "output_tokens": 1612
      },
      {
        "type": "message",
        "input_tokens": 1348,
        "cache_read_input_tokens": 412,
        "cache_creation_input_tokens": 0,
        "output_tokens": 442
      }
    ]
  }
}

トップレベルの usage フィールドは、エグゼキューターのトークンのみを反映します。アドバイザーのトークンは異なる料金で課金されるため、トップレベルの合計には含まれません。type: "advisor_message" のイテレーションはアドバイザーモデルの料金で、type: "message" のイテレーションはエグゼキューターモデルの料金で課金されます。

トップレベルの各 usage フィールドは、input_tokens、output_tokens、cache_read_input_tokens を含め、すべてのエグゼキューターイテレーションにわたるそのフィールドの合計です。各エグゼキューターイテレーションは増大していく会話を再送信するため、後のイテレーションの入力には前のイテレーションの出力が含まれます。そのため、合計された input_tokens は単一のプロンプトのサイズを上回ります。コスト追跡ロジックを構築する際は、イテレーションごとの完全な内訳として usage.iterations を使用してください。

アドバイザーの出力は通常、テキストトークンで400〜700、思考を含めた合計で1,400〜1,800トークンです。コスト削減は、アドバイザーが最終出力全体を生成しないことによって生まれます。最終出力はエグゼキューターがより低い料金で生成します。

トップレベルの max_tokens はエグゼキューターの出力にのみ適用されます。アドバイザーのサブ推論のトークンは制限しません。アドバイザーの出力を直接制限するには、ツール定義で max_tokens を設定してください。アドバイザーのトークンは、エグゼキューターに適用されたタスク予算からも消費されません。

Priority Tierは各モデルに個別に適用されます。エグゼキューターモデルに対するPriority Tierのコミットメントは、アドバイザーには適用されません。アドバイザーの呼び出しがPriority Tierで実行されるのは、組織がアドバイザーモデルに対してもコミットメントを保有している場合のみです。

アドバイザーのプロンプトキャッシング

独立した2つのキャッシング層があります。

エグゼキューター側のキャッシング

advisor_tool_result ブロックは、他のコンテンツブロックと同様にキャッシュ可能です。後続のターンでその後ろに配置された cache_control ブレークポイントはヒットします。クライアントが受け取ったのが text か encrypted_content かにかかわらず、エグゼキューターのプロンプトには常にプレーンテキストのアドバイスが含まれるため、キャッシングの動作は両方の結果バリアントで同一です。

アドバイザー側のキャッシング

同じ会話内の呼び出し間でアドバイザー自身のトランスクリプトに対するプロンプトキャッシングを有効にするには、ツール定義で caching を設定します。

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "caching": {"type": "ephemeral", "ttl": "5m"},
    }
]

N回目の呼び出しにおけるアドバイザーのプロンプトは、(N-1)回目の呼び出しのプロンプトにセグメントを1つ追加したものであるため、プレフィックスは呼び出し間で安定しています。caching を有効にすると、各アドバイザー呼び出しがキャッシュエントリを書き込み、次の呼び出しはその地点まで読み取り、差分に対してのみ支払います。2回目以降の advisor_message イテレーションで cache_read_input_tokens がゼロ以外になることが確認できます。

有効にすべき場面： アドバイザーが会話ごとに2回以下しか呼び出されない場合、キャッシュ書き込みのコストが読み取りによる節約を上回ります。キャッシングはおよそ3回のアドバイザー呼び出しで損益分岐点に達し、それ以降は改善します。長いエージェントループでは有効にし、短いタスクではオフのままにしてください。

一貫性を保つ： caching は一度設定したら、会話全体でそのままにしてください。会話の途中でオフとオンを切り替えると、キャッシュミスが発生します。

他のツールとの組み合わせ

アドバイザーツールは、他のサーバー側およびクライアント側のツールと組み合わせることができます。それらすべてを同じ tools 配列に追加してください。

tools = [
    {
        "type": "web_search_20250305",
        "name": "web_search",
        "max_uses": 5,
    },
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

エグゼキューターは、同じターン内でウェブを検索し、アドバイザーを呼び出し、カスタムツールを使用できます。アドバイザーの計画は、エグゼキューターが次にどのツールを使うかの判断材料になります。

ベストプラクティス

コーディングおよびエージェントタスク向けのプロンプト

アドバイザーツールには、複雑なタスクの開始付近や困難に直面したときにエグゼキューターがアドバイザーを呼び出すよう促す、組み込みの説明が付属しています。リサーチタスクでは、通常、追加のプロンプトは必要ありません。

コーディングおよびエージェントタスクでは、アドバイザーがツール呼び出しの総数と会話の長さを削減する場合に、同程度のコストでより高い知能を発揮します。この改善をもたらすタイミングは2つあります。

1. いくつかの探索的な読み取りがトランスクリプトに含まれた後の、早い段階での最初のアドバイザー呼び出し。
2. 難しいタスクの場合、ファイルの書き込みとテスト出力がトランスクリプトに含まれた後の、最後のアドバイザー呼び出し。

エージェントが他のプランナー的なツール（例：ToDoリストツール）を公開している場合は、アドバイザーの計画がそれらに流れ込むように、それらのツールより先にアドバイザーを呼び出すようモデルにプロンプトで指示してください。推奨システムプロンプトは、早期呼び出しのパターンを強化します。エージェントが公開しているプランナーツールを指す、計画を流し込むための一文を独自に追加してください。

コーディングタスク向けの推奨システムプロンプト

システムプロンプトによる誘導がない場合、エグゼキューターは一部のドメイン、特にコーディングタスクでアドバイザーの呼び出しが少なくなる傾向があります。アドバイザーのタイミングを一貫させ、タスクごとに2〜3回程度の呼び出しを行いたいコーディングタスクでは、アドバイザーに言及する他の文よりも前に、以下のブロックをエグゼキューターのシステムプロンプトの先頭に追加してください。

タイミングに関するガイダンス：

You have access to an `advisor` tool backed by a stronger reviewer model. It takes NO parameters — when you call advisor(), your entire conversation history is automatically forwarded. They see the task, every tool call you've made, every result you've seen.

Call advisor BEFORE substantive work — before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck — errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling — the advisor adds most of its value on the first call, before the approach crystallizes.

エグゼキューターがアドバイスをどのように扱うべきか（タイミングのブロックの直後に配置）：

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong — it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call — "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

コーディングワークロードにおけるHaiku向けの代替システムプロンプト

Claude Haiku 4.5は、デフォルトのアドバイザーガイダンスを控えめに適用します。これにより、リサーチや検索のワークロードでは呼び出し率が適切に低く保たれますが、早期のアドバイザー相談が確実に元を取れるコーディングワークロードでは品質が犠牲になります。内部のコーディングベンチマークでは、以下のブロックに近いバリアント（Hard ruleの読み取り専用の例外は測定後に追加されたもの）により、Haikuの合格率が組み込みのデフォルトと比べて約7.5パーセントポイント向上しました。

Haikuエグゼキューターが主にコーディングや書き込みタスクのワークロードを実行する場合は、前述のタイミングとアドバイスのブロックの代わりにこのブロックを使用してください。

Consult a stronger reviewer who sees your full conversation transcript.

No parameters. When you call advisor(), your entire history -- task, every tool call and result, your reasoning -- is automatically forwarded. The advisor sees exactly what you've done.

Call advisor BEFORE substantive work -- before writing, before committing to an interpretation, before building on an assumption. If the task requires orientation first (finding files, fetching a source, seeing what's there), do that, then call advisor. Orientation is not substantive work. Writing, editing, and declaring an answer are.

Also call advisor:
- When you believe the task is complete. BEFORE this call, make your deliverable durable: write the file, save the result, commit the change. The advisor call takes time; if the session ends during it, a durable result persists and an unwritten one doesn't.
- When stuck -- errors recurring, approach not converging, results that don't fit.
- When considering a change of approach.

On tasks longer than a few steps, call advisor at least once before committing to an approach and once before declaring done. On short reactive tasks where the next action is dictated by tool output you just read, you don't need to keep calling -- the advisor adds most of its value on the first call, before the approach crystallizes.

Give the advice serious weight. If you follow a step and it fails empirically, or you have primary-source evidence that contradicts a specific claim (the file says X, the paper states Y), adapt. A passing self-test is not evidence the advice is wrong -- it's evidence your test doesn't check what the advice is checking.

If you've already retrieved data pointing one way and the advisor points another: don't silently switch. Surface the conflict in one more advisor call -- "I found X, you suggest Y, which constraint breaks the tie?" The advisor saw your evidence but may have underweighted it; a reconcile call is cheaper than committing to the wrong branch.

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first -- that judgment call is exactly where a second opinion is highest-value.

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

注意点： 内部のブラウズ理解ベンチマーク（n = 1,266）では、このブロックに近いバリアントにより、組み込みのデフォルトと比べて精度が約4パーセントポイント低下しました。ワークロードにコーディングと相当量の検索や取得が混在している場合は、推奨ブロックを使い続けるか、すでに算出しているワークロードタイプのシグナルに基づいて切り替えを制御してください。

Opusエグゼキューターでのアドバイザー呼び出しの増加

Opusエグゼキューターは通常、追加のプロンプトなしで適切な頻度でアドバイザーを呼び出します。ワークロードでOpusエグゼキューターの呼び出しが少ない場合は、次のチェックポイントをシステムプロンプトに追加してください。

Call advisor for design, architecture, and risk questions where you won't touch a file. If your response would be analysis or a recommendation with no other tool calls, call advisor first. That judgment call is exactly where a second opinion is highest-value. (This does not apply to simple factual lookups or arithmetic; those you answer directly.)

Hard rule: your first write_file, edit_file, or state-changing bash call on a task must be preceded by an advisor call in the same or an earlier turn. Read-only orientation commands (ls, cat, grep, find) are not state-changing. This is a checkpoint, not a difficulty judgment. It applies to one-line edits too.

注意点： Anthropicのテストでは、このブロックに近いバリアント（Hard ruleの読み取り専用の例外は測定後に追加されたもの）により、呼び出しが少ないタスクでの合格率が約7〜10パーセントポイント向上しましたが、最初のアクションに計画が不要なタスクではOpusが過剰に呼び出すようになりました。混合ワークロードでの正味の効果はほぼ横ばいでした。相談が役立ったはずのタスクでOpusがアドバイザーを省略しているのを確認した場合にのみ追加してください。デフォルトとして追加しないでください。

アドバイザー出力の長さの削減

アドバイザーの出力はアドバイザーの最大のコスト要因であり、トップレベルの max_tokens ではこれを制限できません。アドバイザーは、あなたのシステムプロンプトとユーザーメッセージの両方を、エグゼキューターのタスクに関する引用されたコンテキストとして参照します。そのため、アドバイザーに直接呼びかける指示は、三人称の記述よりもはるかに確実に守られます。Anthropicがテストした中で最も効果的な配置は、ユーザーメッセージ内の次の一行です。

(Advisor: please keep your guidance under 80 words — I need a focused starting point, not a comprehensive plan.)

この行は、リクエストを送信する前にエージェントフレームワークでプログラム的に先頭に付加できます。この制限はソフトな制約です。アドバイザーはときどきこれを超えるため、実際の上限の約80パーセントを指定してください。

最も優れたコストと品質のトレードオフを得るには、このアプローチをコーディングタスク向けの推奨システムプロンプトのタイミングガイダンス（または、置き換えた場合はHaiku向けの代替ブロック）と組み合わせてください。ソフトな要求ではなく厳格な上限を設けるには、アドバイザー出力の制限を参照してください。

アドバイザー出力の制限

ツール定義で max_tokens を設定すると、呼び出しごとのアドバイザーの総出力（思考とテキストの合計）を制限できます。

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-5",
        "max_tokens": 2048,
    }
]

最小値は1024です。max_tokens をアドバイザーモデル自体の出力上限より大きく設定すると、400エラーが返されます。上限は各アドバイザー呼び出しに個別に適用され、同じリクエスト内の呼び出し間で共有されることはありません。

これは単なる強制的な切り捨てではありません。サーバーはアドバイザーに残りのトークン予算も渡すため、アドバイザーはそれに収まるように応答を調整します。

推奨される出発点： max_tokens: 2048。難しい推論ベンチマーク（構成ごとにn = 40）でのAnthropicのテストでは、上限を設定しない場合と比べてアドバイザーの平均出力が約7分の1に減少し、切り捨てはほぼゼロで、検出可能な品質の低下もありませんでした。最小値の1024では出力が約10分の1に減少しましたが、呼び出しの約10パーセントが切り捨てられました。すべての構成間の精度の差は、このサンプルサイズではノイズの範囲内でした。ご自身のワークロードで検証してください。

難しい推論タスクでは、より軽いワークロードについて前述した一般的な1,400〜1,800トークンよりも大幅に長いアドバイザー出力が生じます。この表は、アドバイザー出力の普遍的なベースラインとしてではなく、削減率の見積もりに使用してください。

アドバイザーが上限に達した場合、どのアドバイザーモデルを使用していても、結果バリアントのどちらでも結果ブロックに stop_reason: "max_tokens" が含まれます。stop_reason を使用して切り捨てられたアドバイスを検出し、上限を引き上げるか、エグゼキューターに部分的なガイダンスで続行させるかを判断してください。APIはアドバイスのテキストに [Advisor output truncated at max_tokens=2048.]（設定した上限値を含む）も付加するため、エグゼキューターは自身のコンテキスト内で切り捨てを認識できます。プレーンテキストの advisor_result を返すアドバイザーの場合、このマーカーはクライアントからも確認できます。どちらのシグナルも、ツール定義で max_tokens を設定した場合にのみ表示されます。

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_redacted_result",
    "encrypted_content": "EqQBCkYIBRgCIiQ3YTAwMjY1Mi1mZjM5LTQ1NGUtODgxNC1kNjNjNTk1ZWI3Y...",
    "stop_reason": "max_tokens"
  }
}

各呼び出しが上限にどれだけ近づいたかを確認するには、usage.iterations 内の対応する advisor_message エントリの output_tokens を確認してください。

プロンプトベースのアプローチと比べて、max_tokens はソフトな要求ではなく厳格な上限です。コストやレイテンシに対して保証された上限が必要な場合は max_tokens を使用してください。思考の途中で切断されるリスクを負わずに簡潔さへ誘導したい場合は、プロンプトベースのアプローチ（または両方の併用）を使用してください。

effort設定との組み合わせ

コーディングタスクでは、medium の「effort」（エフォート）に設定したSonnetの「executor」（エグゼキューター）と、Opusの「advisor」（アドバイザー）を組み合わせると、デフォルトのeffortのSonnetと同等の知能をより低いコストで実現できます。知能を最大限に高めたい場合は、エグゼキューターをデフォルトのeffortのままにしてください。

コスト管理

• 会話単位で予算を管理する場合は、アドバイザーの呼び出し回数をクライアント側でカウントしてください。上限に達したら、toolsからアドバイザーツールを削除します。メッセージ履歴からadvisor_tool_resultブロックを取り除く必要はありません（マルチターン会話の注記を参照してください）。
• cachingは、アドバイザーの呼び出しが3回以上見込まれる会話でのみ有効にしてください。

モデルの互換性

エグゼキューターモデル（トップレベルの model フィールド）とアドバイザーモデル（ツール定義内の model フィールド）は、有効な組み合わせである必要があります。アドバイザーはClaude Sonnet 4.6以上の性能を持つモデルである必要があり、かつエグゼキューターと同等以上の性能を持つ必要があります。同等の性能を持つモデル（例：Claude Opus 4.7とClaude Opus 4.8）は、互いにアドバイスできます。

無効な組み合わせをリクエストすると、APIはサポートされていない組み合わせを示す 400 invalid_request_error を返します。

プラットフォームでの利用可能性

アドバイザーツールは、Claude APIおよびClaude Platform on AWSでベータ版として利用できます。現在、Amazon Bedrock、Google Cloud、Microsoft Foundryでは利用できません。

Claude Managed Agentsでのアドバイザー

Claude Managed Agentsのセッションもアドバイザーをサポートしており、ツール定義としてではなくエージェントの一部として設定します。エージェントの multiagent ブロックで "advisor": {"type": "enabled", "model": ...} を設定すると、セッションのプライマリスレッドはターンの途中でそのモデルに相談できます。この設定は max_uses、max_tokens、caching のオプションを受け付けず、アドバイスはレスポンス内の advisor_tool_result ブロックとしてではなく、セッションのイベントストリーム上のスレッドイベントとして配信されます。セッションにアドバイザーを与えるを参照してください。

次のステップ