自動プロンプトキャッシュは多ターン会話でどう動くか

自動プロンプトキャッシュとは何か

自動プロンプトキャッシュは、個々のコンテンツブロックへ cache_control を置かずに済むキャッシュ設定です。リクエストのトップレベルに cache_control: {"type": "ephemeral"} を1つ加えるだけで、システムがキャッシュ可能な最後のブロックへ自動的にブレークポイントを割り当てます。明示的ブレークポイントとの違いは1点だけです。どこをキャッシュするかをシステムが選ぶか、開発者がブロック単位で選ぶか。

会話が伸びるチャットアプリでは、ターンが増えるたびに cache_control を打ち直す運用は現実的ではありません。自動プロンプトキャッシュはこの手間を消すために用意されています。仕組みの全体像はClaudeのプロンプトキャッシュの仕組みで扱いましたが、本稿は多ターン会話に絞って動きを追います。

curl https://api.anthropic.com/v1/messages \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "cache_control": {"type": "ephemeral"},
    "system": "You are a helpful assistant.",
    "messages": [
      {"role": "user", "content": "My name is Alex."},
      {"role": "assistant", "content": "Nice to meet you, Alex."},
      {"role": "user", "content": "What did I say my name was?"}
    ]
  }'

トップレベルの cache_control は tools / system / messages を通しで見て、最後にキャッシュ可能なブロックへ境界を置きます。個別のブロックを見て回る必要はありません。

会話が伸びるとキャッシュ境界はどう動くか

自動プロンプトキャッシュの核心は、リクエストのたびに境界が前へ進むことです。1ターン前までの内容はキャッシュから読み、新しく増えた分だけを書き込みます。

開発者側が毎ターン cache_control の位置を更新する必要はありません。ブレークポイントは、各リクエストの最後のキャッシュ可能なブロックに自動で付きます。

課金体系や最小トークン数の閾値、コンテキストの並び順の制約は、明示的ブレークポイントとまったく同じです。自動プロンプトキャッシュは既存のキャッシュ基盤をそのまま使うだけで、新しい課金ルールを持ち込みません。5分TTLのキャッシュ書き込みは基本入力価格の1.25倍で、キャッシュ読み込みは0.1倍です。Claude Opus 5.5とSonnet 5.5は0.05倍、Claude Fable 5.1とClaude Mythos 5.1は0.025倍になります。この単価も明示的ブレークポイントと共通です。こうした単価がタスク単位でどれだけの金額になるかは、Opus 5.5のタスクコストを試算する方法でターン数・出力トークンと合わせて試算しています。

20ブロックの遡及窓とTTLをどう使い分けるか

自動プロンプトキャッシュにも、明示的ブレークポイントと同じ20ブロックの遡及窓が適用されます。システムはブレークポイント位置から最大20ブロックだけ過去へ遡り、一致するキャッシュエントリを探します。見つからなければ新規に書き込むだけで、読み込みは発生しません。

窓の数え方は、ブレークポイント自身が1つ目です。公式ページには、ブロック数が10 → 15 → 35と伸びる会話の例があります。

1ターンで20ブロック前後以上増える構成では、書き込みだけが続いてもエラーは出ません。コスト増に気づきにくい点に注意が必要です。

Claude APIでは、連続する tool_use ブロックの並びが1か所、連続する tool_result ブロックの並びも1か所として数えられます。並列ツール呼び出しが多いターンでも、それだけで前回のエントリが窓の外へ出ることはありません。大きな出力を何度も挟むエージェントでは、並びが途切れるたびに数が増えます。

TTL(キャッシュの生存時間)も選べます。既定は5分ですが、1時間TTLを使う場合は次のように指定します。

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "cache_control": {"type": "ephemeral", "ttl": "1h"},
    "model": "claude-opus-5",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "..."}]
  }'

1時間TTLのキャッシュ書き込みは基本入力価格の2倍です。キャッシュはヒットするたびに追加料金なしで更新されるため、5分より短い間隔で続く会話では既定の5分TTLのまま生き続けます。会話の間隔が数分から十数分空くチャットボットでは、既定の5分TTLだとターンの合間にキャッシュが失効し、書き込みだけが繰り返されます。1時間TTLの具体的な損益分岐はClaude APIの1時間キャッシュはいつ使うべきかで扱っています。

明示的ブレークポイントと自動キャッシュの使い分け

自動プロンプトキャッシュは明示的ブレークポイントと併用できます。システム全体で最大4つのブレークポイント枠があり、自動キャッシュはそのうち1枠を使います。システムプロンプトだけを明示的に固定し、会話部分は自動キャッシュに任せる構成が典型です。

末尾に毎回変わるブロック(タイムスタンプや動的な補足情報)を置く構成では、自動プロンプトキャッシュはその変わるブロックへ境界を置いてしまい、キャッシュが常に外れます。この構成では、変化しない直前のブロックを狙って明示的ブレークポイントを置くほうが確実です。区画ごとに更新頻度を分けたいケースの具体的な置き方はClaude APIの明示的キャッシュブレークポイントの置き方にまとめています。

併用時にはまり込みやすい境界条件が4つあります。自動キャッシュが割り当てる末尾ブロックに、同じTTLの明示的 cache_control がすでに付いている場合、自動キャッシュはno-opになり何も起きません。逆にTTLが食い違っていると400エラーになります。明示的ブレークポイントが4枠を使い切っていて自動キャッシュに割り当てる枠が残っていない場合も400エラーです。自動キャッシュの対象ブロックがキャッシュ不適格(サイズが最小トークン数の閾値未満など)なときは、システムは手前のブロックへ黙って遡り、適格なブロックが見つからなければキャッシュ自体をスキップします。エラーにならず静かにキャッシュが効かなくなるため、ヒット率が想定より低いときはこの遡り・スキップも疑ってください。

自動キャッシュが効かない・壊れる条件

自動プロンプトキャッシュも、明示的ブレークポイントと同じキャッシュ基盤の上で動くため、同じ条件で無効化されます。ツール定義(名前・説明・パラメータ)を変更すると、tools / system / messages のキャッシュが全体で無効になります。画像の追加・削除や tool_choice の変更はメッセージ部分のキャッシュだけを壊し、ツールとシステムのキャッシュは残ります。thinkingの設定(モードや budget_tokens)を変えると常にメッセージのキャッシュが無効になり、モデルによってはツールとシステムのキャッシュも道連れになります。output_config.effort の値を変えた場合も同様で、メッセージ部分のキャッシュが必ず無効になります。thinking設定の変更でキャッシュヒット率が落ちる具体的な挙動はClaude Thinkingでキャッシュヒット率が落ちる原因で詳しく扱っています。

多ターン会話でとくに見落としやすいのが、途中でシステム指示を追加するケースです。トップレベルの system フィールドを直接書き換えると、そこから下のキャッシュがすべて無効になります。これを避ける手段が、messages 配列への {"role": "system"} メッセージの追記です。既存のキャッシュを壊さずに指示を追加でき、対応しているのはClaude Fable 5.1・Mythos 5.1・Mythos 5・Fable 5・Opus 5.5・Opus 4.8・Opus 5・Sonnet 5.5です。Claude Sonnet 5では使えないため、通常どおりトップレベルの system を書き換える形になります。

thinkingブロックを含む会話でどう動くか

thinkingを有効にしたモデルとの多ターン会話では、もう1つ知っておくべき挙動があります。thinkingブロックは cache_control を直接付けてキャッシュすることはできませんが、ツール結果を含む後続のリクエストを送るときに、他のコンテンツと一緒に自動でキャッシュされます。ツール呼び出しのあとにthinkingブロックを会話へ渡し戻す構成では、この自動キャッシュが日常的に発生します。キャッシュから読み込まれたthinkingブロックは、通常のコンテンツと同じく入力トークンとして計上されます。

ここでモデル世代による差が出ます。Claude Opus 4.5以降・Claude Sonnet 4.6以降では、ツール結果以外のユーザーコンテンツを追加してもthinkingブロックは既定で保持され、キャッシュは有効なままです。それより前のOpus・Sonnetモデルと全てのHaikuモデルでは違います。ツール結果以外のユーザーコンテンツが挟まった時点で過去のthinkingブロックがすべて取り除かれ、そこから先のキャッシュが無効になります。エージェント用途で複数ターンにわたりthinkingを引き継ぐ構成を組むときは、使っているモデル世代でこの挙動が変わる点を前提に設計します。

キャッシュが実際に効いているかを確認する

自動プロンプトキャッシュは条件を満たさなくてもエラーを返さず、静かにキャッシュなしで処理を続けます。まず確認したい条件がプロンプトの長さです。キャッシュ可能な最小長はモデルで違い、これを下回るプロンプトはキャッシュされません。

会話の序盤はメッセージ数が少なく、この最小長に届かないことがあります。モデルを世代の古いものへ切り替えると、同じ会話でも最小長が8倍になる場合がある点は見落としがちです。

キャッシュが効いたかどうかは、レスポンスの usage フィールドで確認します。cache_creation_input_tokens と cache_read_input_tokens の両方が0であれば、そのリクエストはキャッシュされていません。会話の序盤でこの値がゼロのままなら、エラーではなく、まだ最小トークン数に届いていないだけの可能性を先に疑います。

同時に複数のリクエストを送る場合も注意が必要です。キャッシュエントリは最初のレスポンスが返り始めてから初めて使えるようになります。並列リクエストでキャッシュヒットを狙うなら、最初のレスポンスの開始を待ってから後続のリクエストを送る設計にします。

ヒットしないとき、usageの数字からどこを疑うか

ここまでの条件は、usage の2つの値の組み合わせで疑う場所を絞れます。

ワークスペースを複数使う構成では、キャッシュはワークスペースごとに分離されます(Claude API・Claude Platform on AWS・Microsoft Foundryが対象。BedrockとGoogle Cloudは組織単位の分離です)。キャッシュヒットには対象範囲の完全一致も必要で、テキストや画像が1文字でも違えば別扱いです。

どこでプレフィックスが分岐したかを自動で報告するCache diagnosticsという仕組みもあります。使い方はCache diagnosticsでキャッシュミスの原因を特定するにまとめました。

まとめ

自動プロンプトキャッシュは、リクエスト末尾が会話とともに伸びる構成に向きます。選ぶ基準は、末尾のブロックが固定かどうかと、1ターンの増分が20ブロックを超えるかどうかです。どちらかに当てはまる構成では、明示的ブレークポイントとの併用という選択肢があります。