長時間のセッションで、使っていないツールを外そうとしたときのことでした。
ツールが12本ぶら下がったまま会話が進んでいて、明らかに後半では使わないものが混ざっておりました。ターン間でツールを追加・削除できるベータが来ていましたので、素直に4本ほど削りました。入力トークンが減るはずでした。
減りませんでした。むしろ増えました。
cache_read_input_tokens がゼロに落ちて、それまで積み上がっていた会話履歴が丸ごと再送されていたのです。ツールを削って節約したつもりが、キャッシュを壊して全部払い直していたのです。手が止まりました。
ツール定義はプレフィックスの最前列にいる
プロンプトキャッシュは接頭辞（プレフィックス）の一致で効きます。リクエストの先頭から一致している範囲までがキャッシュヒットの対象で、どこか一箇所でも変われば、そこから後ろは全部ミスになります。
問題は、ツール定義がその最前列に置かれることです。Claude API のリクエストは、おおよそ次の順序で直列化されます。
つまりツール配列は、リクエスト全体で最も影響半径の大きい場所にいます。会話が100ターン積み上がっていようと、ツールを1本入れ替えた瞬間に、その100ターン分のキャッシュが道連れになります。
ターン間のツール変更がベータで解禁されたことと、その変更がキャッシュにとって安全であることは、別の話でした。API が変更を受け付けてくれることと、プレフィックスが保たれることは、同じではありません。
ここを取り違えていました。私自身、ベータの告知文にある「プロンプトキャッシュを維持したまま」という一節を、どんな変更でも維持されるという意味に読んでいたのです。機能が解禁されたという知らせを、費用が下がるという知らせと重ねて読んでしまう癖があるのかもしれません。
12種類の変更を指紋で測る
感覚で語っても仕方がないので、測ることにしました。ツール配列を先頭から1本ずつ足していったときの累積ハッシュ列を作り、変更前後でどこまで一致するかを見ます。
# toolprefix.py — ツールブロックのプレフィックス指紋を測る import hashlib import json
def canon (obj): """決定論的シリアライズ: キーをソートし、区切りを固定する""" return json.dumps(obj, sort_keys = True , separators = ( "," , ":" ), ensure_ascii = False )
def prefix_chain (tools): """ツール配列を先頭から1本ずつ足したときの累積ハッシュ列を返す""" chain, h = [], hashlib.sha256() for t in tools: h = h.copy() # copy しないと以降の update が混ざる h.update(canon(t).encode()) chain.append(h.hexdigest()) return chain
def shared_prefix_len (a, b): """2つのハッシュ列が先頭から何要素一致しているか""" n = 0 for x, y in zip (a, b): if x != y: break n += 1 return n h.copy() を挟んでいるのは、各段の途中経過を別々に取り出すためです。ここを省くと同じオブジェクトを更新し続けてしまい、全段が最終値になります。最初これで丸一晩、意味のない100%一致を眺めていました。
ベースになるツール配列は、実際の構成に近い5本にしました。
def mk (name, props): return { "name" : name, "description" : f " { name } tool" , "input_schema" : { "type" : "object" , "properties" : props, "required" : sorted (props.keys()), }, }
BASE = [ mk( "search_docs" , { "query" : { "type" : "string" }, "top_k" : { "type" : "integer" }}), mk( "read_file" , { "path" : { "type" : "string" }}), mk( "write_file" , { "path" : { "type" : "string" }, "body" : { "type" : "string" }}), mk( "run_tests" , { "suite" : { "type" : "string" }}), mk( "post_report" , { "channel" : { "type" : "string" }, "text" : { "type" : "string" }}), ]
base_chain = prefix_chain( BASE ) for label, mutate in CASES : n = shared_prefix_len(base_chain, prefix_chain(mutate( BASE ))) print ( f " { label :<26 } { n } / { len ( BASE ) } { n / len ( BASE ) :.0% } " ) 手元で12パターンを流した結果です。
完全保全は12件中2件、平均保全率は48%でした。
そして、この表の「部分」という判定こそが落とし穴です。プレフィックスが4/5まで一致していても、cache_control のブレークポイントを置いていない位置での一致には何の価値もありません。キャッシュの単位はブレークポイントで区切られた区間であって、ツール1本ごとではないからです。
ブレークポイントをツール配列の最後尾にだけ置いている構成では、上の12パターンのうち実際に救われるのは「安全」の2件だけです。残り10件は、保全率が80%だろうと20%だろうと、等しくゼロとして扱われます。
自分が壊していたのは、まさにこれでした。使わないツールを削るとき、配列の中ほどにいた post_report を抜いていたのです。
同じ内容なのに指紋が変わる
もう一つ、測っていて背筋が寒くなった挙動があります。
ツールの中身が論理的にまったく同じでも、組み立てた順序が違うだけで指紋が変わります。Python の辞書は挿入順を保持しますので、properties に項目を足す順番が違えば、json.dumps の出力も違ってきます。
36通りすべてが別々の指紋になりました。偽の無効化率は35/35、つまり100%です。
これは机上の心配ではありません。ツール定義を条件分岐で組み立てているコード、たとえば「管理者ならこのプロパティを足す」「デバッグ時だけこの項目を入れる」といった書き方をしていると、分岐の順序次第で同じツールが別物として直列化されます。ログには「ツールは変えていない」と映るのに、キャッシュだけが黙って落ち続けます。
対策そのものは一行です。
json.dumps(tool, sort_keys = True , separators = ( "," , ":" ), ensure_ascii = False ) sort_keys=True でキー順を固定し、separators で空白の入り方を固定します。ensure_ascii=False は日本語の説明文を含むツールで出力を安定させるために付けています。これを通した辞書をリクエストに載せる、というところまでやって初めて意味を持ちます。指紋の計算だけ正規化して、実際に送るのは素の辞書、では何も変わりません。
安定コアと揮発テールに分ける
ここまでで方針が決まりました。ツール配列を一枚の板として扱うのをやめ、二つの区画に分けます。
安定コア : そのセッションの間、絶対に変えません。末尾に cache_control のブレークポイントを置きます揮発テール : コアの後ろに置きます。この区画の中でなら、追加も削除も並べ替えも自由です
コアが不変であるかぎり、テールで何をしてもコアまでのプレフィックスは一致します。ツールを「外す」のではなく「テールに移してから外す」に変えるだけで、影響半径が閉じ込められます。
import hashlib import json from dataclasses import dataclass
class ToolPrefixViolation ( Exception ): """コアが変化したまま送信されようとしたときに送出される"""
def canon (o): return json.dumps(o, sort_keys = True , separators = ( "," , ":" ), ensure_ascii = False )
@dataclass ( frozen = True ) class ToolSegments : core: tuple # 会話中は不変。末尾に cache_control を置く tail: tuple # 差し替え自由
@ property def core_fingerprint (self) -> str : h = hashlib.sha256() for t in self .core: h.update(canon(t).encode()) return h.hexdigest()[: 16 ]
def to_request_tools (self) -> list : # 正規化を通した辞書をそのまま送る（指紋だけ正規化しても意味がない） tools = [json.loads(canon(t)) for t in self .core] tools[ - 1 ][ "cache_control" ] = { "type" : "ephemeral" } # コア末尾に breakpoint tools += [json.loads(canon(t)) for t in self .tail] return tools to_request_tools が返す配列で cache_control が付くのは、コアの最後の1本だけです。ここが区間の切れ目になります。テールに何本ぶら下がっていても、この切れ目より前は動きません。
コア改変を弾くガードを挟む
規律は、破れるようになっていると破れます。コアを触れないようにコードで縛りました。
class ToolSetSession : """1セッション分のツール構成。コアの指紋をピン留めして監視する"""
def __init__ (self, segments: ToolSegments): self ._pinned = segments.core_fingerprint self .segments = segments
def mutate_tail (self, new_tail) -> ToolSegments: nxt = ToolSegments( core = self .segments.core, tail = tuple (new_tail)) if nxt.core_fingerprint != self ._pinned: raise ToolPrefixViolation( f "コアが変化しました pinned= { self ._pinned } got= { nxt.core_fingerprint } " ) self .segments = nxt return nxt 動かすとこうなります。
初期コア指紋: daf5a27a5273fe97
送信 tools の cache_control 位置: [2]
テール差し替え後のコア指紋: daf5a27a5273fe97 → 一致
コア改変を検出: コアが変化しました pinned=daf5a27a5273fe97 got=8ac9bd8f8b1072d2
ToolSegments を frozen=True にしているのは、うっかり segments.core.append(...) のような書き方が通らないようにするためです。タプルにしているのも同じ理由です。締めておかないと、半年後の自分が締め忘れます。
例外を投げる設計にしたのは、静かに劣化するより落ちてくれた方が安いからです。キャッシュミスは動作としては正常なので、テストでは検出できません。請求書で気づくことになります。
40ターンのセッションで比べる
分割の効き目を確かめるため、40ターンぶんのツール操作を乱数で作り、二つの運用方式に同じ操作列を流しました。
A : 単一セグメント。有効なツールを毎ターン集めて名前順にソートし、配列を組み直します（よく見る書き方です）B : 安定コア6本を固定し、揮発テールだけを操作します
操作の内訳は add が10回、drop が12回、swap が9回、変更なしが9回です。
安定コア6本の直列化サイズは990バイトでした。A ではそれが39回、まるごと再送され直しています。
ここで効いているのは分割そのものよりも、A が毎ターン「名前順にソートして組み直す」という一見きれいな処理をしている点です。ツールが1本増減するだけでソート後の並びがずれ、コアの位置が動きます。整列は決定論的なのだから安定するはず、という直感と真逆でした。決定論的であることと、変更に対して安定であることは別の性質です。
なお、ここで測っているのはツールブロックの直列化バイト数であって、課金トークンそのものではありません。実際の削減額は、コアの後ろにどれだけ会話履歴が積み上がっているかで大きく変わります。長い会話ほど、この990バイトの背後で失われるものが大きくなる、という読み方をしています。
テールを動かした瞬間、その後ろの履歴まで道連れになります
分割を入れて、しばらく安心しておりました。コアの指紋は40ターンずっと一致していますし、ガードも一度も火を噴きません。
それでも、請求は期待したほど下がりませんでした。
理由は、いま読み返せば初歩的なものでした。プレフィックスは直列です。tools の後ろには system が続き、その後ろに会話履歴が続きます。コア末尾にブレークポイントを置いて守れるのは、そのブレークポイントまで——つまりコアの981バイトだけです。テールを1本足した瞬間、その後ろにある system と、積み上がった履歴のすべてが一致しなくなります。
守っていたつもりの区画は、守る価値がいちばん小さい区画でした。
40ターンのセッションで、3ターンに1回テールを操作する運用を想定して測り直しました。1ターンあたり user と assistant の往復を1組ずつ積み、40ターン終了時点の履歴は46,262バイトです。
分割で救えていたのは、動いた総量の4%に届きませんでした。残りの96%は、テールを触るたびに払い直していたことになります。
では、どうするか。テールという区画を持たず、ツールブロックそのものを会話のあいだ一度も動かさない構成（C）と比べました。使わないツールも配列に残したままにして、tool_choice とツール側の応答で実効的に絞ります。
未使用ツール8本を最後まで載せ続ける運び賃は、B が捨てていた量の12.9%でした。使わないものを配列に残しておく方が安い、という結論は、削って節約するという発想と正面からぶつかります。私はしばらく受け入れられませんでした。
分かれ目は、テールをどれくらいの頻度で触るかです。同じ40ターンで、操作の間隔だけを変えて測りました。
15ターンに1回あたりで拮抗し、それより頻繁に触るなら動かさない方が安くつきます。逆に、セッションの折り返しで一度だけ道具立てを入れ替えるような使い方であれば、分割は素直に効きます。
動かしてよいのは、後ろに何も背負っていないものだけです。 ツールブロックは会話履歴を背負っています。だから分割は、壊れ方を小さくする手当てではあっても、壊さないための答えではなかったのだと受け止めています。
数字はいずれも直列化バイト数で、課金トークンそのものではありません。トークナイザを通せば比率は動きます。それでも「守れた区画と失った区画の桁が二つ違う」という関係は、履歴が長くなるほど開いていく方向にしか動きません。
運用で気をつけている点
個人開発でスケジュール実行を回していると、失敗が請求書まで見えてこないことがあります。私自身、壊れていた期間を後から特定できずに悔しい思いをしましたので、いくつか手を打ちました。
コアに入れる基準を決める : そのセッションで一度でも呼ばれる可能性があるものはコア。「たぶん使わない」は揮発テール。迷ったらテールに置きます。コアは小さいほど壊れにくくなりますツール定義をコードから直接組み立てない : 宣言をモジュール定数として持ち、条件分岐は「どれを選ぶか」だけに使います。中身を分岐で組み立てた瞬間、順序が揺れますcache_read_input_tokens をターンごとに記録するテールが育ったらセッションを切る : テールが膨らみすぎたら、新しいコアを組み直して会話を畳んだ方が安いことがあります。テールもトークンではあります削除より無効化を先に検討する : tool_choice で選ばせない、あるいはツール側で「この段階では使えません」と返す方が、配列から抜くより安全です。前節の測定では、これが最も効きました。テールを頻繁に触る予定があるなら、テールを作らない選択から考えます
3番目は、実際に助けられました。ミスが起きたターンの指紋と、その1つ前の指紋を並べれば、何が変わったかは一目で分かります。
構成別には、次のように振り分けています。
次の一歩
まずは、いま動いているエージェントのツール配列を1回だけ直列化して、sort_keys=True を通した場合と通さない場合でハッシュを比べてみてください。ここが割れているなら、ツールを何も変えていないターンでもキャッシュが落ちている可能性があります。
割れていなければ、次はブレークポイントの位置と、その後ろに何バイト背負っているかです。ツール配列のどこに cache_control が付いているかを出力し、同じターンの system と履歴の直列化サイズを並べて記録してみてください。守れている区画と、テールを触るたびに払い直している区画の大きさが、その1行で見えます。
ツールを削ってコンテキストを節約する、という最適化が逆に高くつくことがあります。そう腑に落ちたのは、守れた区画と失った区画のバイト数を並べて書き出したあとでした。数字にしないと直感の方を信じてしまうのだと思います。同じところで手を止めている方の役に立てば嬉しく思います。お読みいただきありがとうございました。