アドバイザーツール

アドバイザーツールは、より高速で低コストの実行モデルが、生成中に高い知能を持つアドバイザーモデルに戦略的なガイダンスを求めることができます。アドバイザーは完全な会話を読み、計画またはコース修正を生成し（通常400～700テキストトークン、思考を含めて1,400～1,800トークン合計）、実行モデルがタスクを続行します。

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

使用する場合

初期ベンチマークでは、これらの構成で意味のある改善が見られます：

• 複雑なタスクで現在Sonnetを使用している場合： アドバイザーとしてOpusを追加して、同等またはより低い総コストで品質を向上させます。
• 現在Haikuを使用していて、知能を向上させたい場合： アドバイザーとしてOpusを追加します。Haiku単独よりも高いコストが予想されますが、実行モデルをより大きなモデルに切り替えるよりも低くなります。

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

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

モデル互換性

実行モデル（トップレベルの model フィールド）とアドバイザーモデル（ツール定義内の model フィールド）は、有効なペアを形成する必要があります。アドバイザーは少なくとも実行モデルと同じくらい有能である必要があります。

無効なペアをリクエストした場合、APIは 400 invalid_request_error を返し、サポートされていない組み合わせを指定します。

プラットフォーム可用性

アドバイザーツールは、Claude API（Anthropic）でベータ版として利用可能です。

クイックスタート

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-7",
        }
    ],
    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はサーバー側でアドバイザーモデルに対して別の推論パスを実行し、実行モデルの完全なトランスクリプトを渡します。アドバイザーはシステムプロンプト、すべてのツール定義、すべての以前のターン、およびすべての以前のツール結果を見ます。
3. アドバイザーの応答は advisor_tool_result ブロックとして実行モデルに返されます。
4. 実行モデルはアドバイスに基づいて生成を続行します。

これはすべて単一の /v1/messages リクエスト内で発生します。あなた側の追加のラウンドトリップはありません。

アドバイザー自体はツールなしで、コンテキスト管理なしで実行されます。その思考ブロックは結果が返される前にドロップされます。アドバイザーに到達するのはアドバイステキストのみです。

ツールパラメータ

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

レスポンス構造

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

アドバイザーが呼び出されると、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 フィールドは判別された共用体です。受け取るバリアントはアドバイザーモデルに依存します：

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でリクエスト全体を失敗させます。

マルチターン会話

後続のターンでAPIに完全なアシスタントコンテンツ（advisor_tool_result ブロックを含む）を渡します：

import anthropic

client = anthropic.Anthropic()

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

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

# Append the full response content, including any advisor_tool_result blocks
messages.append({"role": "assistant", "content": response.content})

# Continue the conversation
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,
)

後続のターンで tools からアドバイザーツールを省略しながら、メッセージ履歴に advisor_tool_result ブロックが含まれている場合、APIは 400 invalid_request_error を返します。

ストリーミング

アドバイザーサブ推論はストリーミングしません。実行モデルのストリームはアドバイザーが実行している間一時停止し、その後、完全な結果が単一のイベントで到着します。

name: "advisor" を持つ server_tool_use ブロックは、アドバイザー呼び出しが開始されていることを示します。一時停止はそのブロックが閉じるとき（content_block_stop）に始まります。一時停止中、ストリームは標準SSE ping キープアライブを除いて静かです。これは約30秒ごとに出力されます。短いアドバイザー呼び出しは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-7",
        "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 は実行モデルの出力にのみ適用されます。アドバイザーサブ推論トークンを制限しません。アドバイザーのトークンも実行モデルに適用されるタスク予算から引き出されません。

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

2つの独立したキャッシングレイヤーがあります。

実行モデル側キャッシング

advisor_tool_result ブロックは他のコンテンツブロックと同じようにキャッシング可能です。後続のターンでそれの後に配置された cache_control ブレークポイントはヒットします。実行モデルのプロンプトは、クライアントが text または encrypted_content を受け取ったかどうかに関わらず、常にプレーンテキストアドバイスを含むため、キャッシング動作は両方の結果バリアントで同じです。

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

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

tools = [
    {
        "type": "advisor_20260301",
        "name": "advisor",
        "model": "claude-opus-4-7",
        "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-7",
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {"command": {"type": "string"}},
        },
    },
]

実行モデルは、同じターンでウェブを検索し、アドバイザーを呼び出し、カスタムツールを使用できます。アドバイザーの計画は、実行モデルが次に何のツールに到達するかに影響を与える可能性があります。

ベストプラクティス

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

アドバイザーツールは、実行モデルに複雑なタスクの開始近くで呼び出すよう促し、困難に直面したときに呼び出すよう促す組み込みの説明が付属しています。研究タスクの場合、通常、追加のプロンプティングは必要ありません。

コーディングおよびエージェントタスクでは、アドバイザーは総ツール呼び出しと会話長を削減するときに同様のコストで高い知能を生成します。2つのタイミングがこの改善を駆動します：

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

エージェントが他のプランナーのようなツール（例：todoリストツール）を公開する場合、モデルにアドバイザーをそれらのツールの前に呼び出すよう促して、アドバイザーの計画がそれらに流れ込むようにしてください。以下の提案されたシステムプロンプトは早期呼び出しパターンを強化します。エージェントが公開するプランナーツールを指す独自のファネルイン文を追加してください。

コーディングタスク用の提案されたシステムプロンプト

アドバイザーのタイミングを一貫させたい、タスクごとに2～3回の呼び出しを行いたいコーディングタスクの場合、実行モデルシステムプロンプトの他のアドバイザーに言及する文の前に、以下のブロックを先頭に追加してください。内部コーディング評価では、このパターンは最高の知能をSonnetに近いコストで生成しました。

タイミングガイダンス：

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.

アドバイザー出力長のトリミング

アドバイザー出力はアドバイザーの最大のコストドライバーです。そのコストを削減するには、アドバイザーに言及する他の文の前に、システムプロンプトに単一の簡潔性指示を先頭に追加してください。内部テストでは、以下の行は呼び出し頻度を変更することなく、総アドバイザー出力トークンを約35～45パーセント削減しました：

The advisor should respond in under 100 words and use enumerated steps, not explanations.

上記のタイミングブロックと組み合わせて、最強のコスト対品質トレードオフを実現してください。

努力設定とのペアリング

コーディングタスクの場合、中程度の努力でSonnet実行モデルをOpusアドバイザーとペアリングすると、デフォルト努力でのSonnetに匹敵する知能が達成され、コストが低くなります。最大の知能のために、実行モデルをデフォルト努力で保つ。

コスト制御

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

制限事項

• アドバイザー出力はストリーミングしません。 サブ推論が実行されている間、ストリームの一時停止が予想されます。
• アドバイザー呼び出しに組み込みの会話レベルのキャップがありません。 クライアント側でそれらを追跡してキャップしてください。
• max_tokens は実行モデルの出力にのみ適用されます。 アドバイザートークンを制限しません。
• Anthropic Priority Tier はモデルごとに尊重されます。実行モデルのPriority Tierはアドバイザーに拡張されません。アドバイザーモデルで具体的にPriority Tierが必要です。