やす研究所 AI Lab
戻る

Claude API 動的ツール切替2026:mid-conversation-tool-changesでキャッシュを壊さず武器を持ち替える

Claude API 動的ツール切替2026:mid-conversation-tool-changesでキャッシュを壊さず武器を持ち替える

長時間動くエージェントを組んでいると、「途中でツールを1つだけ差し替えたいのに、tools を書き換えた瞬間プロンプトキャッシュが全滅して課金が跳ねる」という壁にぶつかります。

2026年7月1日に beta 提供が始まった mid-conversation-tool-changes-2026-07-01 ヘッダを使うと、その壁が消えます。実際に自分の運用中エージェントに入れてみたら、想像以上に効きました。この記事では最小コード、キャッシュが壊れない条件、そして本番で踏んだ落とし穴3つを紹介します。

結論:途中で tools を足し引きしてもキャッシュは生き残る

先に結論だけ言います。
ベータヘッダを付けて Messages API を叩けば、会話の途中で tools 配列に要素を追加・削除しても、それより前のプロンプトキャッシュブレークポイントは無効化されません。

Anthropic の 2026年7月のリリースノートによると、この機能は Claude Fable 5、Mythos 5、Opus 4.8、Opus 5 の4モデルで beta 提供中で、リクエストに mid-conversation-tool-changes-2026-07-01 ヘッダを含めることで有効になります。

つまりこれまで「エージェントが Phase A で調査ツールを使い、Phase B に入ったら本番書き込みツールを解禁する」といったフェーズ切替のたびに、システムプロンプト+ツール定義の全キャッシュを捨てていたのが、そのまま持ち越せる。地味ですが、5分TTL時代のプロンプトキャッシュにとってはかなり大きい変化です。

なぜ tools を書き換えるとキャッシュが壊れるのか

プロンプトキャッシュの仕組みを乱暴に言えば、「system → tools → messages の順にハッシュを取り、一致する接頭辞まで再利用する」というものです。

つまり tools の中身が1文字でも変わると、その位置以降のキャッシュが全部無効になる。長時間エージェントでは system と tools の合計だけで5,000〜20,000トークンあることも珍しくないので、ここが壊れるとキャッシュヒット率がゼロに落ちます。

私が5月頃に組んでいた調査エージェントは、この問題のせいで「調査フェーズ」と「実行フェーズ」を別セッションに分割して回していました。会話履歴は Memory Tool 経由で受け渡す、という迂回策です。動きはしますが、コードは複雑になるし、フェーズ間で暗黙の文脈が飛びやすい。

新ベータはこの迂回そのものを不要にします。

最小コード:ツールを Phase 2 で1つ追加する

実際に動く Python コード(anthropic SDK)を貼ります。Phase 1 は読み取り専用ツールだけ、Phase 2 で書き込みツールを解禁するパターンです。

import anthropic

client = anthropic.Anthropic()

READ_TOOLS = [
    {
        "name": "search_docs",
        "description": "社内ドキュメントを全文検索する",
        "input_schema": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    }
]

WRITE_TOOL = {
    "name": "create_ticket",
    "description": "Jira にチケットを作成する",
    "input_schema": {
        "type": "object",
        "properties": {
            "title": {"type": "string"},
            "body": {"type": "string"},
        },
        "required": ["title", "body"],
    },
}

SYSTEM = [
    {
        "type": "text",
        "text": "あなたは社内オペレーションを支援するエージェントです。...(長文)...",
        "cache_control": {"type": "ephemeral"},
    }
]

messages = [{"role": "user", "content": "障害チケットの候補を洗い出して"}]

# Phase 1: 読み取りだけ
resp1 = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    system=SYSTEM,
    tools=READ_TOOLS,
    messages=messages,
    extra_headers={
        "anthropic-beta": "mid-conversation-tool-changes-2026-07-01"
    },
)

# ... tool_use / tool_result のやりとりを messages に積む ...

# Phase 2: 書き込みツールを追加
resp2 = client.messages.create(
    model="claude-opus-5",
    max_tokens=2048,
    system=SYSTEM,
    tools=READ_TOOLS + [WRITE_TOOL],  # ← tools が変わるが cache は壊れない
    messages=messages,
    extra_headers={
        "anthropic-beta": "mid-conversation-tool-changes-2026-07-01"
    },
)

ポイントは3つ。

実際に走らせて usage.cache_read_input_tokens を見ると、Phase 2 でも system 分がしっかりキャッシュヒットしているのが確認できます。

相性がいいユースケース3つ

1. フェーズ制エージェントの権限昇格

先ほどの例のように「調査フェーズは read-only、承認後に write ツール解禁」というパターン。以前は権限を Hooks や Advisor で縛る運用でしたが、そもそもモデルに見せなければ最強の deny です。

2. 40ツール上限を回避する動的ロード

MCP を積むと簡単に40ツールに達します。ベータを使えば、「今から DB を触るぞ」というタイミングで DB 系ツールだけを active に差し込み、終わったら外す、という動的ロードが現実的になります。Tool Search と組み合わせると、常時見せるツールを10個以下に抑えられました。

3. コスト削減のための Sonnet→Opus 切替

同じ会話の中で、単純なファイル検索は Sonnet、最終判断は Opus に渡す、という運用でも、tools がフェーズごとに違うことが多い。ここのキャッシュを維持できるだけで、体感で数十%は入力コストが減ります(私の30分エージェントで、cache_read が全体の68%まで伸びました)。

本番で踏んだ落とし穴3つ

落とし穴1:途中でツールの description を書き換えた

「同じ名前のツールなら大丈夫だろう」と思って search_docs の description を Phase 2 で少し詳しくしたら、キャッシュがそこから全部剥がれました。ツール定義は 完全一致で持ち続ける のが大原則。差し替えたいなら別名にする方が安全です。

落とし穴2:beta ヘッダを付け忘れたリクエストが1回混じった

リトライロジックの中で extra_headers を渡し忘れた分岐が1本あり、そこを通った瞬間キャッシュがリセットされて、翌朝の請求で気づきました。ラッパー関数側で強制的にヘッダを差し込む設計に変えるのが結局いちばん安いです。

落とし穴3:古いモデルに投げていた

対応モデルは Fable 5 / Mythos 5 / Opus 4.8 / Opus 5 の4つ。Opus 4.7 以前に投げるとベータヘッダは無視され、tools 変更の瞬間にキャッシュが飛びます。ちなみに Opus 4.7 は7月24日で fast mode が削除されたので、そもそも Opus 4.8 か Opus 5 に寄せておくのが2026年後半の標準構成だと思います。

Extended Thinking / Memory Tool との組み合わせ方

動的 tool 切替は単体でも効きますが、既存の長時間エージェント用機能と重ねると効果が倍増します。

Extended Thinking の思考ブロックはツール呼び出しをまたぐと保持されないので、フェーズ切替のたびに thinking をやり直しがちでした。tool 差し替えでキャッシュを維持できるようになると、interleaved thinking のブロックも会話履歴として素直に積み上がるので、モデルが「Phase 1 でこう考えた、だから Phase 2 はこうする」と自然に接続します。

Memory Tool は逆に、「セッションをまたいで残したいもの」に限定するのが正解です。ベータ導入後は、同一セッション内で持ち回るべき情報を無理に memory に書き出さなくてよくなったので、memory の中身がスリムになりました。

fallbacks の “default” モードも同日に来ている

余談ですが、同じ2026年7月1日付で fallbacks パラメータに "default" モードが追加され、server-side-fallback-2026-07-01 beta ヘッダでサーバー側フォールバックが有効になりました。Refusal のカテゴリごとに Anthropic 推奨のフォールバック先モデルが自動選択される仕組みです。

動的 tool 切替と組み合わせると、「本番書き込みだけ Opus 5、拒否時は自動で Opus 4.8 にフォールバック」といった構成をクライアント側の分岐なしで組める。長時間エージェントの信頼性設計としては、この2つのベータをセットで入れておく価値があります。

まとめ:今日からやる3つのアクション

  1. 手持ちのエージェントに beta ヘッダを追加する。mid-conversation-tool-changes-2026-07-01 を extra_headers に固定で埋め込む
  2. モデルを Opus 4.8 か Opus 5 に統一する。Opus 4.7 以下ではベータが効かない
  3. フェーズごとの tool リストを設計し直す。Phase 1 は read-only、Phase 2 で write を追加、のような段階解禁を設計に落とす

5分TTL時代のプロンプトキャッシュは、壊さない工夫の連続です。tool の差し替えでキャッシュを守れるようになった今、次に潰すべきボトルネックは「system プロンプトの微調整による無自覚な失効」あたりだと思います。そちらはまた別の記事で。

参考リンク

この記事をシェア:
X で共有 Facebook で共有 Telegram で共有
次の記事
Claude Agent SDK副業の始め方2026|月次クレジットで作る自動化納品ルート