[JA] Opusの頭脳をHaikuの価格で使う方法：Advisor Tool 実践ガイド

1週間前にAnthropicのAdvisor Toolについて少し触れました。今日はその完全なガイドを共有します：APIを介して構成する方法、Claude Codeで単一のコマンドでアクティブ化する方法、有効なモデルのペア、そして本番環境で実行し続ける前に確認すべき請求の詳細についてです。

秘訣は、すべてに最も高価なモデルを使用するのではなく、重要なことに最も賢いモデルを使用することです。

一言で言うと

作業の90％を行うために、高速で安価なモデル（HaikuまたはSonnet）を配置します。行き詰まったり、本当に考える必要がある場合、そのモデルがOpusに相談します。あなたがオーケストレーション（調整）を行う必要はありません。決定は実行者（executor）によって行われ、すべては単一の /v1/messages 呼び出し内で発生します。

🏃 実行者（Executor / Haiku または Sonnet） — プレイヤーです。コードを生成し、ファイルを読み、コマンドを実行します。高速で安価です。

🧠 アドバイザー（Advisor / Opus） — コーチです。計画、修正、または停止信号が必要な場合にのみ介入します。ツールを呼び出すことはなく、ユーザーのための出力を生成することもありません。実行者にアドバイスするだけです。

これは、典型的なサブエージェントパターン（大規模なオーケストレーターが小さなワーカーに委任する）の逆転です。ここでは、小さなモデルが運転し、必要な場合にのみスケールアップします。

ベータ版を正当化する数字

🔹 Haiku 4.5 + Opus アドバイザー (BrowseCompで検証): 19.7%から41.2%への飛躍。2倍以上。

🔹 Sonnet 4.6 + Opus アドバイザー (SWE-bench Multilingualで検証): Sonnet単独の場合よりタスクあたりのコストが約11%低く、スコアは向上。

🔹 中程度の努力（medium effort）のSonnet + アドバイザーは、より少ないコストで、デフォルトの努力（default effort）のSonnetの知能に到達します。

この節約はアドバイザーからもたらされるのではありません。実行者がすでに適切な計画を持っているため、より少ないターンでタスクを完了することからもたらされます。

有効なモデル（これは重要です）

アドバイザーは、実行者と少なくとも同じ能力を持っていなければなりません。APIが受け入れる組み合わせは以下の通りです：

実行者 claude-haiku-4-5-20251001 → アドバイザー claude-opus-4-7
実行者 claude-sonnet-4-6 → アドバイザー claude-opus-4-7
実行者 claude-opus-4-6 → アドバイザー claude-opus-4-7
実行者 claude-opus-4-7 → アドバイザー claude-opus-4-7

これ以外の組み合わせは 400 invalid_request_error を返します。いいえ、「安く済ませるために」SonnetのアドバイザーとしてHaikuを設定することはできません。ベータ版では許可されていませんし、そもそも役に立ちません。

オプションA: Claude Code（最も簡単）

すでにClaude Codeを使用している場合、これは文字通り1つのコマンドで済みます。

要件: Claude Code v2.1.101以降。claude --version で確認し、必要に応じて更新してください：

npm install -g @anthropic-ai/claude-code

アクティベーション:

プロジェクトでClaude Codeを開きます：claude
セッション内で次のように入力します：/advisor
モデルの短いリストが表示されます。Opusを選択してください。

“Advisor configured. Opus will be consulted for complex decisions and task completion checks.”（アドバイザーが構成されました。複雑な決定とタスク完了のチェックのためにOpusに相談します。）のようなメッセージが表示されます。これで完了です。サンプリングパラメータも、カスタムシステムプロンプトも何もありません。

理解しておくべきことは、あなたがアドバイザーを呼び出すわけではないということです。 「アドバイザーに相談する」コマンドはありません。Sonnetはセカンドオピニオンが必要な時期を自ら決定し、応答の途中で静かに呼び出しを挿入し、アドバイスは最初からそこにあったかのようにコンテキストに組み込まれます。初めて見る時は、存在しない確認ダイアログを探してしまうかもしれません。

⚠️ 重要な制限: これはAnthropicの直接APIに対してのみ機能します。Bedrock、Vertex、LiteLLM、OpenRouter などのプロキシ経由でClaude Codeを使用している場合、アドバイザーはトリガーされません。これはネイティブエンドポイント上に存在するサーバー側の機能です。

オプションB: 直接API（完全な制御）

独自のエージェントを構築する場合、アドバイザーを tools 配列内の別のツールとして宣言します：

import anthropic

client = anthropic.Anthropic()

response = client.beta.messages.create(
    model="claude-sonnet-4-6",                  # 実行者 (executor)
    max_tokens=4096,
    betas=["advisor-tool-2026-03-01"],          # ベータヘッダー
    tools=[
        {
            "type": "advisor_20260301",
            "name": "advisor",
            "model": "claude-opus-4-7",         # アドバイザー
            "max_uses": 5,                       # オプション、リクエストごとの制限
        }
    ],
    messages=[
        {"role": "user", "content": "Goで優雅なシャットダウン（graceful shutdown）を備えた同時実行ワーカープールを構築してください。"}
    ],
)

必要な3つの最低限の項目：

ベータヘッダー advisor-tool-2026-03-01。
model（トップレベル）での実行者の指定。
独自の model（アドバイザー）を持つ advisor_20260301 ツール。

マルチターン：ここに注意してください

後続の呼び出しでは、advisor_tool_result ブロックを含む完全な履歴を返す必要があります。アドバイザーがまだ tools にある間にこれらを省略すると、APIは400を返します。また、アドバイザーを tools から削除した場合は、履歴からもこれらのブロックをクリアする必要があります。両方を同時に保持するか、両方を削除するかのどちらかです。

messages.append({"role": "assistant", "content": response.content})
messages.append({"role": "user", "content": "インフライト（実行中）の制限を10に追加してください。"})

💡 設定 `keep: "all"`（見落としがちなキャッシュの詳細）

ドキュメントを文字通り引用します：keepの値が”all”以外でclear_thinkingを行うと、各ターンでアドバイザーの引用されたトランスクリプトがシフトし、アドバイザー側のキャッシュミスを引き起こします。

なぜそれが重要なのでしょうか？アドバイザーは戦略的推論ブロックを生成します。デフォルトでは、拡張思考（extended thinking）を有効にしている場合、APIは keep: {type: "thinking_turns", value: 1} で clear_thinking を適用します。つまり、各ターンで古いブロックをトリミングします。これにより、アドバイザーが見るトランスクリプトがシフトし、アドバイザー側のプロンプトキャッシュが壊れます。

結果：すべての呼び出しでキャッシュの書き込みに支払いを行い、読み取りは決して行われません。永久的なキャッシュミスです。

解決策: コンテキスト編集設定で keep: "all" を設定してください。履歴をそのまま保持することで、アドバイザーへの繰り返しの呼び出しはキャッシュから読み取られ、アドバイザーの入力トークンの節約は**最大90%**に達する可能性があります。

そして、アドバイザー自体のキャッシュを有効にするには：

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

⚠️ アドバイザーキャッシュの黄金律: 会話あたりのアドバイザーの呼び出しが2回以下の場合は、キャッシュの書き込みによるコストが節約額を上回ります。3回目の呼び出しから利益が出始めます。短いタスクの場合は無効にしておきましょう。

請求：`usage` が隠しているもの

アドバイザーは、実行者とは別に、独自のOpusのレートで請求されます。そして usage のトップレベルのフィールドは実行者の使用量のみを反映しています。input_tokens と output_tokens だけを見てコストを追跡していると、計算が合いません。

実際の明細は usage.iterations[] にあります：

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

イテレーション type: "message" → 実行者のレート。
イテレーション type: "advisor_message" → アドバイザーのレート (Opus)。
アドバイザーは通常、呼び出しごとに400〜700のテキストトークン、または思考を含めて1,400〜1,800のトークンを生成します。
リクエストの max_tokens はアドバイザーのトークンを制限しません。

コストを真剣に追跡したい場合は、イテレーションを自分で合計してください。

実際に効果のあるシステムプロンプト

APIを介して独自のエージェントを構築し、Anthropicがベンチマークで測定している品質を再現したい場合は、これらのブロックを実行者のシステムプロンプトの最初の部分（アドバイザーへの言及の前）に置いてください：

タイミングブロック（いつ呼び出すか）:

本質的な作業の前（コードを書く前、解釈を確定させる前、仮定に基づいて構築する前）にアドバイザーを呼び出してください。タスクが最初に方向付け（ファイルの検索、ソースの読み取り）を必要とする場合は、それを行ってからアドバイザーを呼び出してください。方向付けは本質的な作業ではありません。コードの記述、編集、および回答の宣言が本質的な作業です。

また、タスクが完了したと考える場合（最初に成果物を耐久性のあるものにしてください：ファイルを書き込み、出力を保存する）、行き詰まった場合、そしてアプローチの変更を検討する場合にもアドバイザーを呼び出してください。

アドバイスの扱い方ブロック（その直後に）:

アドバイスを重く受け止めてください。あるステップに従って経験的に失敗した場合、または特定の主張に矛盾する一次ソースの証拠がある場合は、適応してください。自分自身のテストがパスしたことは、アドバイスが間違っているという証拠には「なりません」。それは、アドバイスがチェックしているものをあなたのテストがチェックしていないという証拠です。

簡潔性ブロック（頻度に触れることなく、アドバイザーのトークンの約35〜45％を削減します）:

アドバイザーは100語未満で応答し、説明ではなく列挙された手順を使用する必要があります。

Claude Codeでは、これらのプロンプトはすでに標準で適用されています。APIを介して行う場合は、自分で追加する必要があります。

使ってはいけない場合

これは魔法ではなく、常に利益をもたらすわけではありません：

単一ターンのQ&A（一問一答）。 計画するものが何もなく、実行者はそれを呼び出さないため、オーバーヘッドを追加するだけです。
純粋に機械的なタスク（フォーマットの変更、検索、正規表現など）。決定のポイントがなく、アドバイザーの出番もありません。
レイテンシーが重要なパス。 アドバイザーのサブ推論が実行されている間、実行者のストリームは一時停止されます。ストリーミングされません。
すべてのターンでOpusが必要なワークロード。 常にそれが必要な場合は、すでに無駄に2倍支払っていることになります。直接Opusを使用してください。
現時点でのBedrockまたはVertex経由。 サポートは進行中ですが、まだすべての場所でネイティブではありません。

予算に関する他のマスターキー

アドバイザーは単独で動作するわけではありません。以下と組み合わせてください：

✨ プロンプトキャッシング（Prompt Caching） — 繰り返される入力トークンを最大90%節約します。長い会話には不可欠です。

📦 バッチAPI（Batch API） — 即時応答を必要としないタスクで50%の節約。

⚙️ 努力設定（Effort settings） — 中程度の努力のSonnet + Opusアドバイザーはデフォルトの努力のSonnetとほぼ同じで、より安価です。

推論が高価な贅沢になりつつある市場において、オーケストレーションはあなたの最大の競争優位性です。

要約 (TL;DR)

Claude Codeにて：/advisor → Opusを選択 → 完了。Anthropicの直接APIのみ。
API経由：ヘッダー advisor-tool-2026-03-01 + その model を持つツール advisor_20260301。
有効なペア: 実行者としてHaiku/Sonnet/Opus 4.6/Opus 4.7 → 常にアドバイザーとしてOpus 4.7。
拡張思考を使用する場合は keep: "all" を指定しないと、アドバイザーのキャッシュが失われます。
会話あたり3回以上の呼び出しが予想される場合のみ caching: ephemeral。
請求: トップレベルではなく usage.iterations[] を見てください。各 advisor_message はOpusのレートです。
単一ターン、機械的なタスク、または現時点でBedrock/Vertexなどのプロキシ経由では使用しないでください。

🚀 コード記述にAIを使用していて、トークンを測定せずにプロンプトを投げ続けている場合は、次の記事でプロンプトキャッシング、バッチAPI、および本番環境のエージェントの実際の経済性について詳しく説明します。見逃さないようにフォローしてください。

Cookie Consent