advisor toolのHaikuナッジで通過率を7ポイント上げる実装

このTipsでできること

advisor toolでexecutorにHaikuを使うと、序盤でadvisorを一度も呼ばずにタスクを進めてしまうことがあります。この取りこぼしに対して、Anthropicは会話へ短いリマインダーを1つ差し込むだけの仕組みを検証しました。内部の行動評価では、Haiku executorのタスク通過率がおよそ7ポイント上がっています。ただし同じ仕掛けはSonnetでは効果が測定されず、Opusでは逆効果です。実装パターンと、モデルごとに割れる結果、タイミングを誤ったときの副作用までをまとめます。

Haikuナッジとは何か — 追加のユーザーメッセージ1つだけの仕組み

ナッジは、Haiku executorが最初のassistantターンでadvisorをまだ呼んでいないとき、2ターン目のassistant応答が生成される前に短いリマインダーを差し込む仕組みです。新しいツールを足すわけではありません。会話履歴に、ユーザー役のテキストメッセージを1つ追加するだけです。

公式が示す既定のリマインダー文言は次のとおりです。

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.

このメッセージを、advisorをまだ呼んでいない状態のまま2ターン目に差し込みます。既定のNUDGE_TURNは2です。モデルがタスクの全体像を把握したものの、まだ具体的な実装方針にコミットしていない、そのわずかな隙間を狙ったタイミングになっています。

効果はモデルで真逆に割れる

Anthropicの内部行動評価では、このナッジはHaiku executorのタスク通過率をおよそ7ポイント引き上げました。一方でSonnet executorに対して、平文のナッジには測定可能な効果がありませんでした。Opus executorへの適用は避けます。公式ドキュメントは「Opus executorにはナッジを適用しない」と明記しており、通過率がわずかに下がると説明しています。

3つのモデル階層で結果がここまで割れる以上、Haiku向けの調整結果をSonnetやOpusにそのまま横展開しない設計になります。Opusにはナッジを適用しません。Sonnetでは、ナッジを足すかどうかより、advisorをどのタイミングで呼ばせるかの設計が先に来ます。次の節のタイミングの実測データは、特にSonnet executorに関わりが深い内容です。

実装 — NUDGE_TURNとナッジ文言

実装は、advisorが呼ばれたかどうかをターンごとに追跡し、指定したターン数に達してもまだ呼ばれていなければユーザーメッセージを1つ足すだけです。エージェントループの骨格に、フラグと条件分岐を1つ足す程度の変更で組み込めます。

import anthropic
 
client = anthropic.Anthropic()
 
NUDGE_TURN = 2  # このターンの前に、advisor未呼び出しならナッジを挿入
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  # エージェントループの上限
 
tools = [
    {"type": "advisor_20260301", "name": "advisor", "model": "claude-opus-5"},
    # ... 他のツール
]
messages = [{"role": "user", "content": "Goでgracefulシャットダウンつきのワーカープールを実装して"}]
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  # advisor呼び出しが保留中。そのまま送り直して完了させる
 
    # 自前のツール実行。tool_resultはナッジより先にmessagesへ追加する
    results = run_your_tools(response.content)
    if results:
        messages.append({"role": "user", "content": results})
 
    if turn == NUDGE_TURN - 1 and not advisor_called:
        messages.append({"role": "user", "content": NUDGE_TEXT})

ナッジは、tool_resultを含むユーザーメッセージとは別の、独立したユーザーメッセージとして追加します。ユーザーメッセージが連続しても、APIの仕様上は問題ありません。Anthropicの検証では、tool_resultと同じメッセージ内の別ブロックとして混ぜても、Haiku・Sonnetでは同等の挙動でした。それでも独立メッセージにしておくほうが、ツールの実行結果とリマインダーの境界がログ上でも明確になります。

システムプロンプトに、すでに「本当に不確実なときだけadvisorを呼ぶ」のような抑制的な指示が入っているなら、turn == NUDGE_TURN - 1の分岐自体を丸ごと省略します。2つの指示が矛盾したまま両方生きている状態は避けます。

タイミングを間違えると逆効果になる

この平文ナッジはHaikuとSonnetの両方でadvisorの呼び出しを強く促します。その結果、問題を読み切る前の早すぎるタイミングで呼ばせてしまうことがあります。そうなると相談の文脈が薄くなり、本来もっと良いタイミングで呼ばれるはずだった相談を、低品質な早期呼び出しが押しのけます。

NUDGE_TURNを決める前に、対象のexecutorが自発的にadvisorを呼ぶベースラインのターン数を測っておきます。すでに信頼できるタイミングで呼んでいるなら、そのターン数より後ろにNUDGE_TURNを設定します。

ワークロードの性質で結果の向きが変わるため、Haiku全般の結果を鵜呑みにせず、自分の負荷で試す価値があります。単純なタスクと複雑なタスクが混ざるなら、調整の余地が2つあります。NUDGE_TURNを3に上げて2ターンで終わるタスクをナッジより先に完了させるか、複雑度を判定するシグナルをすでに計算しているならそれでナッジの発火自体をゲートします。

ナッジとシステムプロンプトのどちらで呼び出し率を上げるか

Haiku 4.5には、ナッジのほかにシステムプロンプト側で呼び出しを増やす手があります。公式ドキュメントには「コーディング中心のHaiku向け」の代替ブロックが載っており、write_fileやedit_file、状態を変えるbashを最初に使う前に、advisor呼び出しを済ませておくことを義務づける内容です。lsやcatのような読み取り専用の確認コマンドは対象外とされています。

2つの数値は別々の評価から出ており、並べて優劣はつけられません。書き込みの多いタスクが中心ならシステムプロンプト側、タスクの種類が混ざるなら必要なときだけ差し込めるナッジ側、という分け方が成り立ちます。公式ドキュメントも、コーディングと参照が混ざる負荷では代替ブロックを使わず、負荷の種類を示すシグナルで切り替えることを挙げています。

ナッジが増やすのはコストでもある

ナッジが効いて呼び出し率が上がれば、advisorのサブ推論回数も増えます。advisor呼び出しはexecutorとは別料金で、出力はthinking込みで典型的に1,400〜1,800トークン程度です。通過率の変化だけでなく、usage.iterations配列にadvisor_messageとして記録される呼び出し回数の変化も一緒に見ておくと、想定外のコスト増に早く気づけます。

出力上限の絞り方は2つあります。ひとつはツール定義のmax_tokensで、thinkingとテキストを合わせた1回あたりの出力に硬い上限をかけます。最小値は1024です。

これは難しい推論ベンチマーク(各構成n=40)での値で、軽い負荷の1,400〜1,800トークンとは水準が違います。打ち切られた呼び出しにはstop_reason: "max_tokens"が付きます。もうひとつはユーザーメッセージの先頭に「80語以内で」と頼む書き方で、こちらは守られないこともあるので、上限の8割程度を指定します。この書き方は呼び出し回数を増やしましたが、1回が短くなるぶん総コストは下がったと公式ドキュメントは述べています。

ナッジを使わない代替 — tool_choiceで強制する

特定のリクエストだけ確実にadvisorを呼ばせたいなら、ナッジではなくtool_choiceを{"type": "tool", "name": "advisor"}に設定して強制する方法もあります。ただし強制的なtool_choiceは、手動で有効化した拡張思考(thinking: {type: "enabled"})と併用できません。両方を同時に指定すると400 invalid_request_errorが返ります。Adaptiveな思考設定とは併用できます。

Claude Opus 5.5、Sonnet 5.5、Fable 5.1、Mythos 5.1をexecutorにする場合は、tool_choiceのtool型・any型そのものが拒否されます。強制が使えないため、公式はこの4モデルではプロンプトによるナッジを代替に挙げています。ただしOpusへのナッジは通過率を下げるとも書かれているので、Opus 5.5では2つの記述が食い違います。Opusの呼び出し不足にはシステムプロンプトの確認項目が別に用意されていますが、混合ワークロードでは効果がほぼ横ばいだったと注記されています。

Fable 5.1とMythos 5.1はadvisorに選べる相手も自分自身とお互いだけで、他のexecutorとは組み合わせのルールが大きく違います。executorごとに選べるadvisorの範囲はadvisor toolのモデル互換性にまとめてあります。

ナッジ後もadvisorを呼ばなかったときのフォールバック

前述の即呼び出し率(Haiku 98%、Sonnet 74%)の裏を返せば、残りではadvisorを呼ばないまま進む余地があります。ナッジは指示文であり、呼び出しを保証する仕組みではありません。以下はこの記事の設計例で、Anthropicのドキュメントが示す手順ではありません。失敗コストの高いタスクで、ナッジで足りなかった少数のケースだけtool_choiceの強制へ切り替える構成です。

ナッジと強制を同時に使う必要はなく、強制のコストを払うのはナッジが効かなかった分だけで済みます。前節のとおり、強制が使えない4モデルではこのフォールバックを組めません。

使い分け早見表

まとめ

手段の選び分けは、既存のプロンプトを変えずに足せるのがナッジ、コーディング中心のHaikuならシステムプロンプトの代替ブロック、特定のリクエストだけ確実に呼ばせたいならtool_choiceの強制です。ナッジはHaiku向けの手段なので、SonnetとOpusには持ち込みません。advisor toolの最小構成と結果の読み方はClaude APIのadvisor toolを実装する最小構成にあります。