# プロンプトキャッシュ設計——ブレークポイントとTTL選択

> Anthropic APIのプロンプトキャッシュをエージェント設計に組み込む実践ガイド。ブレークポイントの配置戦略、5分／1時間TTLの使い分け、マルチターン会話の設計、キャッシュ無効化リスクの回避まで解説します。

- Canonical: https://kuucorp.com/blog/prompt-caching-agent-design-context-reuse/
- Date: 2026-06-26
- Last modified: 2026-06-26
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
AIエージェントが本番稼働を始めると、見落としがちなコスト構造の問題が浮上します。マルチターン会話エージェントは毎ターン、同じシステムプロンプト・ツール定義・参照ドキュメントをゼロから送信します。20,000トークンのシステムプロンプトを持つエージェントが1日1,000ターン実行すれば、その大半が純粋な「再送信コスト」です。Anthropic APIのプロンプトキャッシュはこの無駄を設計レベルで解消できます。

本記事は[エージェントハーネス設計](/blog/agent-harness-architecture/)と連動しています。コスト計測・部門配賦の全体像は[AI FinOps設計](/blog/ai-finops-token-cost-instrumentation/)を参照してください。

## プロンプトキャッシュの仕組みとエージェントへのインパクト

> Anthropic APIのプロンプトキャッシュはKVキャッシュをAPIレベルで提供し、キャッシュ読み込みトークンの単価を通常入力比90%削減で再利用できます。

プロンプトキャッシュは、Anthropic APIがAttention層のKV（Key-Value）テンソルをサーバーサイドで保持する仕組みです。同一プレフィックスを再送信した際、モデルはキャッシュされたKVを読み込むだけで再計算をスキップします。

**コスト構造の変化**

トークン単価はキャッシュ操作によって3段階に変わります（Claude Sonnet 4.6の場合）。

| 操作 | 単価 | 倍率 |
|------|------|------|
| 通常入力 | $3.00/百万トークン | 基準 |
| キャッシュ書き込み（5分） | $3.75/百万トークン | 1.25× |
| キャッシュ書き込み（1時間） | $6.00/百万トークン | 2.0× |
| キャッシュ読み込み | $0.30/百万トークン | 0.10× |

キャッシュ書き込みのプレミアムがあっても、同一プレフィックスを2〜3回再利用すればネットで安くなります。1,000回再利用するエージェントでは、該当トークンのコストを90%近く削減できます。

**キャッシュの評価順序**

Anthropic APIはキャッシュプレフィックスを `tools → system → messages` の階層順に評価します。tools定義がキャッシュに乗れば、その下のsystemもまとめてキャッシュから読まれます。この順序は設計上の重要な制約で、後述するブレークポイント配置の基礎になります。

最小キャッシュ可能長はモデルによって異なり、Claude Sonnet 4.6・Opus 4.8 では1,024トークンです。これ未満のブロックはキャッシュ書き込みの対象にならず、エラーなく通常入力として処理されます。

## キャッシュブレークポイントの配置設計

> ブレークポイントはtools→system→messagesの階層順に評価され、変化頻度の低いブロック末尾に1リクエスト最大4個配置するのが設計の基本です。

`cache_control` パラメータをブロックに付与することでキャッシュブレークポイントを明示します。

```json
{
  "type": "text",
  "text": "【静的なシステムプロンプト本文】",
  "cache_control": {
    "type": "ephemeral",
    "ttl": "5m"
  }
}
```

1リクエストに設定できる明示ブレークポイントは最大4個です。モデルは最後にキャッシュヒットしたブレークポイント以降のトークンを新規計算します。

**推奨配置パターン**

エージェント設計で有効な配置は次の3層です。

```
Layer 1: tools定義（ほぼ変わらない）→ cache_control: {ttl: "1h"}
Layer 2: systemプロンプト本文（変わらない）→ cache_control: {ttl: "1h"}
Layer 3: 参照ドキュメント（セッション単位で固定）→ cache_control: {ttl: "5m"}
---（ここから下はキャッシュしない）---
Layer 4: ユーザーメッセージ・ツール結果（ターンごとに変化）
```

**キャッシュすべきでないコンテンツ**

ユーザーメッセージ本文・ツール実行結果・タイムスタンプを含むテキスト・セッションIDは、ターンごとに変化するためキャッシュに乗せません。これらを `cache_control` 付きブロックより上流に置くと、意図せずキャッシュが分断されます。

## マルチターン会話の自動キャッシュと明示キャッシュの使い分け

> マルチターン会話では自動キャッシュが会話履歴を逐次キャッシュし、長時間セッションには1時間TTLとの組み合わせでコスト構造が大きく変わります。

Anthropic APIには **自動キャッシュ** と **明示キャッシュ** の2つのモードがあります。

**自動キャッシュ（推奨起点）**

明示的に `cache_control` を指定しなくても、APIが会話履歴を自動でキャッシュします。ターンNのキャッシュをターンN+1が読み込む形で、会話履歴が積み上がるコストを自動で最適化します。シンプルなチャット型エージェントの多くはこれだけで十分です。

**明示キャッシュの適用場面**

長い参照ドキュメントを毎ターン添付するエージェント、ツール定義が多いエージェント、複数セッションで同一システムプロンプトを使い回すバッチ処理エージェントでは、明示キャッシュが有効です。

**キャッシュのプリウォーム**

本番トラフィックが来る前にキャッシュを温めるには、`max_tokens: 0` のリクエストを送ります。

```json
{
  "model": "claude-sonnet-4-6",
  "max_tokens": 0,
  "system": [
    {
      "type": "text",
      "text": "【大規模システムプロンプト】",
      "cache_control": {"type": "ephemeral", "ttl": "1h"}
    }
  ],
  "messages": [{"role": "user", "content": "warmup"}]
}
```

`stop_reason: "max_tokens"` で即終了し、内容は返りませんが、キャッシュ書き込みは実行されます。初回リクエストのレイテンシスパイクを避けたい本番環境で有効な手法です。

**使用量のモニタリング**

レスポンスの `usage` フィールドに、キャッシュ書き込み・読み込みのトークン数が別々に記録されます。

```json
{
  "usage": {
    "input_tokens": 100,
    "cache_creation_input_tokens": 18000,
    "cache_read_input_tokens": 52000,
    "output_tokens": 300
  }
}
```

`cache_read_input_tokens` がターンを経るごとに増えているかを監視することで、キャッシュが正常に効いているかを確認できます。

## キャッシュ無効化リスクと設計の落とし穴

> ツール定義の変更やweb_search機能の切り替えはキャッシュ全体を即時無効化するため、安定ブロックより上流に変動設定を置かない構造設計が必須です。

プロンプトキャッシュを本番に導入した際、最も多いトラブルが「想定通りキャッシュが効かない」という問題です。主な原因は次の無効化トリガーです。

| 変更操作 | 無効化範囲 |
|----------|-----------|
| ツール定義の変更 | キャッシュ全体 |
| web_searchの有効化／無効化 | system + messages |
| citationsの有効化／無効化 | system + messages |
| speed設定の変更（fast/standard） | system + messages |
| tool_choice パラメータ変更 | messagesのみ |

**設計上の対策**

変動頻度の高い設定を「安定ブロックの下流」に配置することが根本的な解決策です。たとえば、セッションごとにツールを動的に追加するアーキテクチャでは、ベースとなる静的ツール群と動的ツール群を別リクエストに分けるか、動的部分をツールとして扱わず `user` ターンの構造化テキストとして渡す設計を検討します。

**ワークスペース単位のキャッシュ分離**

2026年2月以降、プロンプトキャッシュはワークスペース単位で分離されています。異なるプロジェクト・チームが同じAPIキーを共有している場合でも、ワークスペースが異なればキャッシュは共有されません。エンタープライズ環境でのキャッシュヒット率の設計には、このワークスペース境界を意識する必要があります。

## 規模別の留意点（SMB / エンタープライズ）

**SMB**

まず自動キャッシュだけで始めるのが現実的です。システムプロンプトが1,024トークンを超えるエージェントが1本あれば、自動キャッシュだけで月次コストの20〜40%が削減されるケースが多くあります。明示キャッシュや1時間TTLは、月次の請求書を確認した後に効果の高いエージェントから順次適用します。[Kuu株式会社のAI運用管理サービス](/services/ai-ops/)では、キャッシュ効率のモニタリング設計を含む導入支援を行っています。

**エンタープライズ**

複数チームが同一LLMプラットフォームを使う環境では、ワークスペース設計とキャッシュ効率の関係を設計時に考慮します。大規模なRAGシステムでは、取得ドキュメントをキャッシュ内に配置するか、毎ターン動的に挿入するかのトレードオフが発生します。キャッシュ書き込みコスト（1h TTLは2.0×）と読み込みコスト（0.10×）の損益分岐点は、ワークスペースごとのリクエスト頻度から算出します。大規模統制が必要な場合は[Kuuのエンタープライズ向けRDEサービス](/services/rde/)も参照してください。

## 参考

- [プロンプトキャッシング（Anthropic公式ドキュメント・英語）](https://platform.claude.com/docs/en/build-with-claude/prompt-caching)
- [プロンプトキャッシング（Anthropic公式ドキュメント・日本語）](https://platform.claude.com/docs/ja/build-with-claude/prompt-caching)
- [AIエージェントは毎ターン、同じ20,000トークンを読み直している——Prompt Cachingという設計規律](https://zenn.dev/analysis/articles/thought-analyzer-prompt-caching)

## まとめ

プロンプトキャッシュは「設定するだけ」ではなく、設計思想として取り込む必要があります。変化頻度ごとにコンテンツを層に分け、適切なTTLとブレークポイントを割り当てることで、エージェントのAPIコストは構造的に下がります。無効化トリガーを把握した上でキャッシュ境界を設計することが、本番環境で期待通りの効果を得るための前提です。

エージェントのコスト設計・可観測性・権限管理を含むトータルな運用設計に課題を感じている場合は、[Kuuへお問い合わせ](/services/ai-ops/)ください。