アドバイザーツール

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

このパターンは、長期的なエージェント型ワークロード（コーディングエージェント、コンピューター操作、マルチステップの調査パイプライン）に適しています。これらのワークロードでは、ほとんどのターンが機械的な処理である一方、優れた計画を持つことが極めて重要です。トークン生成の大部分をエグゼキューターモデルのレートで行いながら、アドバイザー単独に近い品質を得られます。



使用すべき場面

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

• 現在、複雑なタスクにSonnetを使用している場合： より上位のアドバイザーを追加します。Opusを使用すると総コストは同等かそれ以下に抑えられ、Claude Fable 5を使用すると品質向上が最大化されます。
• 現在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、Claude Fable 5、またはClaude Mythos 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 フィールドは判別共用体です。成功した呼び出しの場合、バリアントはアドバイザーモデルによって異なります。

Claude Opus 5、Claude Fable 5、およびClaude Mythos 5のアドバイザーは advisor_redacted_result を返します。互換性テーブルのその他のアドバイザーモデルは advisor_result を返します。

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

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

どちらの場合も、後続のターンでコンテンツをそのままラウンドトリップしてください。会話の途中でアドバイザーモデルを切り替える場合は、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に渡してください。この例では、response.content でプレーンテキストのアドバイスが確認できるように、アドバイザーとして claude-opus-4-8 を使用しています。仕組みはどのアドバイザーモデルでも同じです。

client = anthropic.Anthropic()

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

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



呼び出し不足のエグゼキューターへの会話途中のナッジ

Haikuエグゼキューターが最初のアシスタントターンでアドバイザーを呼び出していない場合、2回目のアシスタントターンの前に、追加のユーザーメッセージとして短いリマインダーを追加してください。Anthropicの内部動作評価では、これによりHaikuエグゼキューターのタスク合格率が約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ブロックごとに1つのtool_resultブロックを返します。
    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-4-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 == "end_turn":
        break
    if response.stop_reason == "pause_turn":
        continue  # server tool pending; re-send to let the API complete it

    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})

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

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

プレーンテキストのナッジは、HaikuおよびSonnetエグゼキューターで非常に顕著な効果があります。Anthropicのテストでは、ナッジされた試行の74パーセント（Sonnet）から98パーセント（Haiku）がターン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 を返します。アダプティブ思考は強制ツール使用をサポートしています。



ストリーミング

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

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がテストした中で最も効果的な配置は、ユーザーメッセージ内の1行です。

(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-4-8",
        "max_tokens": 2048,
    }
]

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

これは単なるハードな切り捨てではありません。サーバーはアドバイザーに残りのトークンバジェットも渡すため、アドバイザーはそれに収まるようにレスポンスを形成します。

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

難しい推論タスクは、軽いワークロードについて前述した典型的な1,400〜1,800トークンよりも大幅に長いアドバイザー出力を引き出します。この表は節約率のサイズを見積もるために使用し、アドバイザー出力の普遍的なベースラインとしては使用しないでください。

アドバイザーが上限に達した場合、結果ブロックには stop_reason: "max_tokens" が含まれます。APIはまた、アドバイステキストに [Advisor output truncated at max_tokens=2048.]（あなたの上限値を示す）を追加するため、エグゼキューターは自身のコンテキストで切り捨てを確認できます。stop_reason を使用して切り捨てられたアドバイスを検出し、上限を上げるか、部分的なガイダンスでエグゼキューターを続行させるかを決定してください。両方のシグナルは、ツール定義で max_tokens を設定した場合にのみ表示されます。

{
  "type": "advisor_tool_result",
  "tool_use_id": "srvtoolu_abc123",
  "content": {
    "type": "advisor_result",
    "text": "Use a channel-based coordination pattern. The tricky part is\n\n[Advisor output truncated at max_tokens=2048.]",
    "stop_reason": "max_tokens"
  }
}

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

プロンプトベースのアプローチと比較すると、max_tokens はソフトなリクエストではなくハードな上限です。コストやレイテンシのために保証された境界が必要な場合は max_tokens を使用してください。思考の途中で切れるリスクなしに簡潔さに偏らせたい場合は、プロンプトベースのアプローチ（または両方を併用）を使用してください。



エフォート設定との組み合わせ

コーディングタスクでは、中程度のエフォートのSonnetエグゼキューターとOpusアドバイザーを組み合わせることで、デフォルトエフォートのSonnetと同等の知能を、より低いコストで実現できます。最大の知能を得るには、エグゼキューターをデフォルトエフォートのままにしてください。



コスト管理

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



モデルの互換性

エグゼキューターモデル（トップレベルの 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 のセッションもアドバイザーをサポートしており、ツール定義としてではなくエージェントの一部として設定されます。エージェントのマルチエージェントロスターに {"type": "advisor", "model": ...} エントリを追加すると、セッションのプライマリスレッドがターンの途中でそのモデルに相談できるようになります。このロスターエントリは max_uses、max_tokens、caching オプションを受け付けず、アドバイスはレスポンス内の advisor_tool_result ブロックとしてではなく、セッションのイベントストリーム上のスレッドイベントとして配信されます。詳細については、セッションにアドバイザーを付与するを参照してください。



次のステップ