プロンプトキャッシング

プロンプトキャッシングとは、モデルプロバイダーが変更されていないプロンプトプレフィックス（通常はシステム/開発者指示や他の安定したコンテキスト）をターンごとに再処理する代わりに再利用できる仕組み。最初のマッチするリクエストがキャッシュトークンを書き込み（cacheWrite）、以降のマッチするリクエストで読み戻す（cacheRead）。

利点: トークンコストの削減、高速なレスポンス、長時間セッションでの予測可能なパフォーマンス。

主要な設定ノブ

`cacheRetention`（モデルおよびエージェントごと）

agents:
  defaults:
    models:
      "anthropic/claude-opus-4-6":
        params:
          cacheRetention: "short" # none | short | long

レガシー `cacheControlTtl`

レガシー値は引き続き受け入れられマッピングされる: 5m -> short、1h -> long。新しい設定ではcacheRetentionを推奨。

`contextPruning.mode: "cache-ttl"`

キャッシュTTLウィンドウ後に古いツール結果コンテキストを刈り込み、アイドル後のリクエストが過大な履歴を再キャッシュしないようにする。

ハートビートキープウォーム

ハートビートでキャッシュウィンドウをウォームに保ち、アイドルギャップ後の繰り返しキャッシュ書き込みを削減。

プロバイダー動作

Anthropic（直接API）: cacheRetentionサポート。
Amazon Bedrock: Anthropic ClaudeモデルrefでcacheRetentionパススルーをサポート。
OpenRouter Anthropicモデル: Anthropic cache_controlをシステム/開発者プロンプトブロックに注入。
その他: キャッシュモードをサポートしない場合、cacheRetentionは効果なし。

キャッシュ診断

diagnostics.cacheTrace設定でエンベデッドエージェント実行の専用キャッシュトレース診断を公開。