アドバイザーツール

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

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



使用すべき場面

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

• 現在、複雑なタスクにSonnetを使用している場合: Opusをアドバイザーとして追加すると、同等またはより低い総コストで品質が向上します。
• 現在Haikuを使用していて、知能を一段階上げたい場合: Opusをアドバイザーとして追加します。Haiku単独よりもコストは高くなりますが、エグゼキューターをより大きなモデルに切り替えるよりは低くなります。

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

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



モデルの互換性

エグゼキューターモデル（トップレベルの 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では利用できません。



クイックスタート

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    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.",
        }
    ],
)

print(response)



仕組み

アドバイザーツールを 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 ブロックが続きます。

{
  "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 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に渡してください。

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-4-6",
    max_tokens=4096,
    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-4-6",
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],
    tools=tools,
    messages=messages,
)

メッセージ履歴にまだ advisor_tool_result ブロックが含まれている状態で、フォローアップターンの tools からアドバイザーツールを省略すると、APIは 400 invalid_request_error を返します。



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

アドバイザー呼び出しがまだ保留中の状態で、レスポンスが stop_reason: "pause_turn" で終了することがあります。その場合、レスポンスにはアドバイザーの server_tool_use ブロックが含まれますが、それに対応する advisor_tool_result はありません。再開するには、そのアシスタントメッセージをコンテンツを変更せずに messages に追加し、server_tool_use ブロックを保持したまま、同じアドバイザーツールとベータヘッダーでリクエストを再送信します。ユーザーメッセージや tool_result ブロックを追加する必要はありません。APIは保留中のアドバイザー呼び出しを実行し、新しいレスポンスでエグゼキューターのターンを続行します。再開されたターンが再び一時停止することもあります。その場合は、同じ手順を繰り返してください。再開リクエストからアドバイザーツールを省略すると 400 invalid_request_error が返されます。代わりに、エグゼキューターが同じターンであなたのツールの1つを呼び出した場合、アドバイザー呼び出しが保留中のままレスポンスは 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-4-8"},
    # ... その他のツール
]
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(
        b.type == "server_tool_use" and b.name == "advisor" for b 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})

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

トレードオフ: ナッジは呼び出し率を上げるため、ごく単純なタスクでも不要な相談が発生する可能性があります。ワークロードに単純なタスクと複雑なタスクが混在している場合は、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"} に設定します。ツール使用の強制は拡張思考と組み合わせることはできません。両方を有効にすると、APIは 400 invalid_request_error を返します。



ストリーミング

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

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

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

続いて message_delta イベントが、アドバイザーのトークン数を反映した更新済みの usage.iterations 配列とともに到着します。



使用量と課金

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

{
  "usage": {
    "input_tokens": 412,
    "cache_read_input_tokens": 0,
    "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-4-8",
        "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" のイテレーションはエグゼキューターモデルのレートで課金されます。

集計ルールはフィールドによって異なります。トップレベルの output_tokens はすべてのエグゼキューターイテレーションの合計です。トップレベルの input_tokens と cache_read_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-4-8",
        "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-4-8",
    },
    {
        "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ルールの読み取り専用の除外は測定後に追加されました）により、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ルールの読み取り専用の除外は測定後に追加されました）は、呼び出し不足のタスクでの合格率を約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。難しい推論ベンチマーク（構成ごとにn = 40）でのAnthropicのテストでは、これにより上限を設定しない場合と比較して平均アドバイザー出力が約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 を使用してください。思考の途中での切断のリスクなしに簡潔さに偏らせたい場合は、プロンプトベースのアプローチ（または両方を併用）を使用してください。



effort設定との組み合わせ

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



コスト管理

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



次のステップ