キャッシュ読み込みトークンが急にゼロへ落ちても、Messages APIのusageフィールドは理由を教えてくれない。システムプロンプトが変わったのか、ツール定義が変わったのか、履歴の編集が原因なのか——従来は仮説を立てて1つずつ潰すしかなかった。2026年9月23日にGA化したCache Diagnosticsは、この当てずっぽうのデバッグを構造化されたレスポンスに置き換える。
Cache Diagnosticsとは何か
Cache Diagnosticsは直前のレスポンスIDを渡すだけで、2つのリクエストのプロンプト接頭辞がどこで分岐したかをAPIが特定する機能だ。
リクエストにdiagnosticsオブジェクトを含めると、APIはそのリクエストのフィンガープリントをidに紐づけて保存する。次のターンで直前のidをdiagnostics.previous_message_idとして渡すと、APIは保存済みフィンガープリントと新リクエストを比較し、レスポンスのdiagnosticsフィールドに分岐点を返す。初回ターンは比較対象が無いためprevious_message_id: nullを渡してオプトインするだけでよい。かつて必要だったcache-diagnosis-2026-04-07ベータヘッダーは不要になり、GA後は送っても無視される。
キャッシュミスの原因はどう分類されるか
cache_miss_reasonはtypeで判別する共用体で、model/system/tools/messagesの変更4種と、比較不能だった2種を返す。
具体的にはmodel_changed（モデル自体が変わった）、system_changed（システムプロンプトにタイムスタンプ等を埋め込んだ）、tools_changed（ツール定義の順序や内容が変わった）、messages_changed（過去の会話履歴を追記ではなく編集・削除した）の4種が分岐点を示す。加えてprevious_message_not_found（フィンガープリントの保持期限切れや別ワークスペース起因）、unavailable（thinkingやtool_choiceなど他パラメータの変更、または比較範囲を超えた長い会話）がある。各*_changed型はcache_missed_input_tokensという目安の推定値も持ち、どれだけのキャッシュ済み接頭辞を失ったかが分かる。
usageとdiagnosticsをどう組み合わせて読むか
diagnosticsは「リクエストが変わったか」、usage.cache_read_input_tokensは「キャッシュが実際に当たったか」を示し、両方を見て初めて原因が切り分かる。
diagnosticsがnullで読み込みトークンが高ければ正常動作だ。nullなのに読み込みトークンが低い場合は、リクエスト自体は一致しているがキャッシュエントリが期限切れになったケースで、5分TTLから1時間TTLへの切り替えが有効な対処になる。*_changed型が返り読み込みトークンも低ければ、それが本当のバグでありtypeが示す原因を直す対象になる。
実装と運用で何に注意すべきか
フィンガープリントはハッシュとトークン数推定のみで生テキストを保持せず、ZDR適格だが保持期間は短く、継続したターンでの利用が前提になる。
マルチターンのループでは、直前レスポンスのidを毎ターンprevious_message_idとして引き渡す実装にする。ストリーミングではdiagnosticsがmessage_startイベントに載るため、SDKのアキュムレータで最終メッセージまで保持すればよい。Claude API専用の機能でAmazon BedrockやGoogle Cloud経由では使えない点、フィンガープリントの保存先が同一ワークスペースに限られる点は事前に把握しておく必要がある。SMBではAPI呼び出し全体にdiagnosticsを常時組み込んでログにcache_miss_reasonを残すだけで十分だが、エンタープライズで複数チームがモデルルーティングを行う場合はLLMゲートウェイ側でモデル固定やsystemプロンプトの一意性を保証する設計が要る。コスト計測基盤全体との統合はAI FinOps設計も参照してほしい。
参考
- Cache diagnostics - Claude Platform Docs
- Prompt caching - Claude Platform Docs
- Pricing - Claude Platform Docs
まとめ
Cache Diagnosticsは、キャッシュミスという「見えない事故」をcache_miss_reasonという診断可能な情報に変える機能だ。usage.cache_read_input_tokensと組み合わせれば、リクエストのバグとキャッシュエントリの期限切れを切り分けられ、プロンプトキャッシュのコストメリットを継続的に確保できる。自社のエージェント基盤にキャッシュ監視を組み込みたい場合は、Kuuのエージェント運用支援で設計・実装を相談できる。