アドバイザーツール

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

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



使用すべき場面

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

• 現在、複雑なタスクに 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 をアドバイザーとして使用する場合、ブロックの 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 フィールドは判別共用体です。成功した呼び出しの場合、バリアントはアドバイザーモデルによって異なります。

以下は、ツール定義内のアドバイザーの 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 フィールドには読み取ることのできない不透明なブロブが含まれます。次のターンで、サーバーがそれを復号し、プレーンテキストをエグゼキューターのプロンプトにレンダリングします。

どちらの場合も、後続のターンではコンテンツをそのままラウンドトリップしてください。会話の途中でアドバイザーモデルを切り替える場合は、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 が返されます。呼び出しが保留中の場合は常にツールを含めてください。代わりにエグゼキューターが同じターンであなたのツールの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-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 エグゼキューターでのテストでは、兄弟ブロックと同等に動作しました。別メッセージの形状にすることで、リマインダーがツール出力と明確に区別されます。

トレードオフ: ナッジは呼び出し率を上げるため、ごく単純なタスクを不要な相談に押し込む可能性があります。ワークロードに単純なタスクと複雑なタスクが混在している場合は、2ターンのタスクがナッジの発動前に完了するように NUDGE_TURN を3に上げるか、すでに計算しているタスク複雑度のシグナルでナッジをゲートすることを検討してください。システムプロンプトにすでに抑制的な文言（「アドバイザーは本当に不確実な場合のために取っておく」）が含まれている場合は、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-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 設定との組み合わせ

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



次のステップ