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にそのまま横展開しないのが安全です。SonnetとOpusでは、ナッジ自体を足すかどうかより、advisorをどのタイミングで呼ばせるかの設計が先に来ます。次の節のタイミングの実測データは、特にSonnet executorに関わりが深い内容です。

Haikuで取りこぼしが起きやすいのは、モデルの階層が上がるほど計画段階での不確実性を自発的に検知しやすくなる一方、Haikuは実装に着手する判断が早く、advisorへ相談すべき局面をそのまま素通りしやすいためだと考えられます。ナッジという明示的な一言が効くのは、この「相談すべきかどうかの自己判断」を補う形で働くからです。Opusのように自己判断の精度がもともと高いモデルに同じ一言を足すと、必要のない相談まで誘発し、むしろノイズになります。

実装 — 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の追加を行う
 
    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の両方でかなり強く効きます。ナッジを受けた試行のうち、Sonnetで74%、Haikuでは98%が、ターン2で即座にadvisorを呼びました。狙ったタイミングより早く問題を読み切る前に呼ばせてしまうと、文脈の薄い相談になります。本来もっと良いタイミングで呼ばれるはずだった相談を、低品質な早期呼び出しが押しのける形です。

したがってNUDGE_TURNを決める前に、対象のexecutorが自発的にadvisorを呼ぶベースラインのターン数を測っておきます。すでに信頼できるタイミングで呼んでいるなら、そのターン数より後ろにNUDGE_TURNを設定します。実測では、ベースラインの初回呼び出しがターン7以降のワークロードにターン2のナッジをかけると、タスクの成功率が3〜4ポイント下がりました。逆に、ベースラインの呼び出し率が86%というブラウズ系ワークロードでは、同じナッジを足しても呼び出し率が上がるだけで、性能面のコストは出ませんでした。

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

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

ナッジが効いて呼び出し率が上がるということは、advisorのサブ推論回数自体も増えるということです。advisor呼び出しはexecutorとは別料金で、出力はthinking込みで典型的に1,400〜1,800トークン程度です。ナッジで単純なタスクにまで呼び出しを誘発すると、通過率の改善と引き換えにコストが積み上がります。混合ワークロードでナッジを検討するときは、通過率の変化だけでなく、usage.iterations配列に記録されるadvisor呼び出し回数の変化もあわせて見ておくと、想定外のコスト増に早く気づけます。

たとえば1日1万リクエストのHaiku executorのうち、ナッジ導入前は3割だけがadvisorを呼んでいたとします。ナッジを足してHaikuの呼び出し率がSonnet同様98%まで上がると、advisor呼び出し回数はおよそ3倍に増えます。通過率+7ポイントの価値が、この3倍のadvisorコストに見合うかどうかは、タスクの重要度と失敗時のコストによって変わります。すべてのリクエストに一律でナッジをかけるのではなく、失敗の許容度が低いタスク種別に絞って導入するところから試すと、コストの伸びを制御しながら効果を確認できます。max_tokensをツール定義に設定してadvisorの出力上限を切ることも、呼び出し回数が増えたぶんのコストを抑える補助策になります。

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

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

Claude Fable 5.1とClaude Mythos 5.1をexecutorにする場合は、tool_choiceのtool型・any型そのものが拒否されます。tool_choiceの強制が使えないため、公式はプロンプトによるこのナッジを代替として挙げています。この2モデルはadvisor側に選べる相手も自分自身とお互いだけに絞られており、他のexecutorとは組み合わせのルールがかなり違います。executorごとに選べるadvisorの範囲はadvisor toolのモデル互換性にまとめてあります。

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

ナッジを挟んでもなお、executorがadvisorを呼ばずにend_turnで終わることがあります。ナッジはあくまで指示文であり、呼び出しを保証する仕組みではありません。CVE級の重大なタスクなど、確実にadvisorの助言を挟みたい場面では、ナッジを1回試したあとでtool_choiceによる強制へ切り替えるフォールバックを重ねる設計が有効です。実装上は、ループの中で「ナッジ済みだがadvisor_calledがFalseのままend_turnに達した」ケースを検知し、そのターンだけtool_choiceを強制へ切り替えて再送します。ナッジと強制を同時に使う必要はなく、ナッジで十分な大多数のケースは低コストのまま処理し、ナッジが効かなかった少数のケースだけ強制のコストを払う二段構えです。

使い分け早見表

まとめ

Haiku executorへの平文ナッジは、advisor呼び出しの取りこぼしを補う安価な仕掛けで、Anthropicの内部評価では通過率を7ポイント押し上げました。Sonnetには測定可能な効果がなく、Opusには逆効果です。効くモデルであっても、NUDGE_TURNを早すぎる位置に置くと文脈の薄い呼び出しを誘発し、成功率を落とします。適用前に、対象のexecutorが自発的にadvisorを呼ぶベースラインのターン数を測り、そのタイミングより後ろにNUDGE_TURNを置くところから始めます。advisor toolの最小構成と結果の読み方はClaude APIのadvisor toolを実装する最小構成にまとめています。