Microsoft developer platform documentation update の「Python: Add prompt caching support to Anthropic connector」は、Microsoft の Semantic Kernel Python 向け Anthropic connector に、Anthropic API のプロンプトキャッシュを扱うための設定を追加する変更です。結論から言うと、Claude系モデルへ長い system prompt や大量の tool definitions を繰り返し送っている開発者は確認すべき更新です。一方で、PRはオプトイン設計で、既存コードに自動でキャッシュが有効になる変更ではありません。2026年5月5日時点の差分では、AnthropicCacheSettings、環境変数による制御、cache_control の自動注入、サンプルコード、単体テストが追加されています。(GitHub)
Microsoft developer platform documentation updateで何が変わったのか
今回の更新は、Semantic Kernel の Python 版 Anthropic connector で、Anthropic API の prompt caching を使いやすくするためのものです。PRでは、AnthropicCacheSettings という新しい設定モデルを追加し、AnthropicChatPromptExecutionSettings に cache フィールドを持たせ、リクエスト送信前の prepare_settings_dict() で cache_control を system message や tool definitions に注入する構成になっています。(GitHub)
ポイントは、Anthropic のクライアント呼び出し部分を大きく変えるのではなく、実行設定レイヤーでキャッシュ指定を組み立てることです。PR本文でも、AnthropicChatCompletion 自体には変更せず、キャッシュ処理は settings layer に閉じ込める方針が示されています。(GitHub)
| 変更点 | 内容 | 実務上の意味 |
|---|---|---|
AnthropicCacheSettings の追加 | キャッシュ有効化、対象、TTLをまとめて管理 | コードまたは環境変数でキャッシュ戦略を切り替えやすい |
cache フィールドの追加 | AnthropicChatPromptExecutionSettings にキャッシュ設定を追加 | 既存のチャット設定と同じ流れで利用できる |
prepare_settings_dict() の上書き | 送信前ペイロードに cache_control を注入 | 開発者が毎回手動でJSONを組み立てる負担を減らせる |
| system message / tools 対応 | system message と最後の tool definition にキャッシュ指定 | 長い指示文や多数のツール定義を再利用しやすい |
| 環境変数対応 | ANTHROPIC_CACHE_ プレフィックスで設定可能 | 本番・検証環境でコード変更なしにON/OFFしやすい |
| サンプルと単体テスト追加 | caching サンプルと各種テストを追加 | 導入時の検証観点が分かりやすい |
prompt cachingとは何か
prompt caching は、毎回同じ内容を含む長いプロンプトの一部をキャッシュし、次回以降のリクエストで再利用する仕組みです。Anthropic の公式ドキュメントでは、同じ prompt prefix が見つかるとキャッシュ済みの内容を使い、処理時間とコストを抑えられると説明されています。特に、多数の例、長い背景情報、繰り返し使う指示、長いマルチターン会話で有効です。(Claude Platform)
Anthropic APIでは、cache_control を使ってキャッシュ対象を指定できます。キャッシュできる対象には、tools 配列内の tool definitions、system 配列内の system messages、messages.content 内のテキスト、画像、ドキュメント、tool use、tool results などが含まれます。(Claude Platform)
ただし、キャッシュは「長いプロンプトなら何でも自動で安くなる」機能ではありません。キャッシュ対象の内容が毎回同一であること、モデルごとの最小トークン数を満たすこと、TTL内に再利用されることが重要です。Anthropic のドキュメントでも、最小長に満たない場合はエラーにならず、cache_creation_input_tokens と cache_read_input_tokens が 0 になり得ると説明されています。(Claude Platform)
今回の更新で追加される主なAPI
PR差分では、semantic_kernel.connectors.ai.anthropic から AnthropicCacheSettings を公開APIとしてエクスポートする変更が入っています。これにより、Anthropic connector を使うコードからキャッシュ設定を直接インポートできるようになります。(GitHub)
想定される使い方は、次のような形です。
from semantic_kernel.connectors.ai.anthropic import (
AnthropicCacheSettings,
AnthropicChatPromptExecutionSettings,
)
settings = AnthropicChatPromptExecutionSettings(
service_id="anthropic",
max_tokens=512,
cache=AnthropicCacheSettings.system(ttl="5m"),
)system prompt と tool definitions の両方をキャッシュ対象にする場合は、次のような設定が想定されます。
settings = AnthropicChatPromptExecutionSettings(
service_id="anthropic",
max_tokens=512,
cache=AnthropicCacheSettings.on(ttl="1h"),
)PR差分では、AnthropicCacheSettings.on()、off()、system()、tools()、short()、long() といったクラスメソッドが用意されています。on() は system と tools の両方、system() は system message のみ、tools() は tool definitions のみを対象にする設計です。(GitHub)
環境変数で確認すべき設定
今回の更新では、AnthropicCacheSettings が KernelBaseSettings を継承し、ANTHROPIC_CACHE_ プレフィックスの環境変数から設定を読み込めるようになっています。PRのコメントでは、ANTHROPIC_CACHE_ENABLED、ANTHROPIC_CACHE_INCLUDE_SYSTEM、ANTHROPIC_CACHE_INCLUDE_TOOLS、ANTHROPIC_CACHE_TTL による制御が説明されています。(GitHub)
| 環境変数 | 役割 | 設定例 | 確認ポイント |
|---|---|---|---|
ANTHROPIC_CACHE_ENABLED | キャッシュのマスタースイッチ | true | 本番で意図せず有効化していないか |
ANTHROPIC_CACHE_INCLUDE_SYSTEM | system message をキャッシュ対象にする | true | system prompt が毎回変わらないか |
ANTHROPIC_CACHE_INCLUDE_TOOLS | tool definitions をキャッシュ対象にする | true | ツール定義の順序や内容が安定しているか |
ANTHROPIC_CACHE_TTL | キャッシュ保持時間 | 5m または 1h | 呼び出し間隔に合っているか |
本番運用では、まず ANTHROPIC_CACHE_ENABLED=false の状態でリリースし、検証環境で usage 情報を見ながら有効化するのが安全です。特に、プロンプト内に現在時刻、ユーザー名、セッションID、リクエストごとの検索結果などを system prompt に混ぜている場合、キャッシュヒットしにくくなります。
TTLは5分と1時間のどちらを選ぶべきか
今回の実装では、TTLとして "5m" と "1h" が扱われます。最終差分では、1時間TTLの cache_control は {"type": "ephemeral", "ttl": "1h"} として生成される形です。PR上では一時的に 3600 を使う問題が指摘されましたが、後続コミットで修正されています。(GitHub)
Anthropic の公式ドキュメントでは、5分キャッシュの書き込みはベース入力トークン価格の1.25倍、1時間キャッシュの書き込みは2倍、キャッシュ読み取りは0.1倍と説明されています。つまり、1時間TTLは便利ですが、初回書き込みコストが高いため、呼び出し間隔と再利用回数を見て選ぶ必要があります。(Claude Platform)
| TTL | 向いているケース | 避けたいケース |
|---|---|---|
5m | エージェントの連続実行、チャットの短時間の往復、開発者支援ツールの連続質問 | ユーザーの次回操作が5分以上空きやすい |
1h | バッチ処理、長時間の調査エージェント、ユーザー応答が数十分空くチャット | 1回しか再利用しない長大プロンプト、低頻度の単発処理 |
判断基準はシンプルです。5分以内に同じ静的プロンプトを何度も使うなら 5m、5分を超えても再利用される見込みが高いなら 1h を検討します。逆に、毎回内容が変わるプロンプトや、短いプロンプトではキャッシュの効果が出にくくなります。
影響を受ける開発者
今回の Microsoft developer platform documentation update で特に確認すべきなのは、Semantic Kernel の Python 版で Anthropic connector を使っている開発者です。PRは microsoft/semantic-kernel に対する変更で、Pythonラベルが付いたPRとして扱われています。(GitHub)
| 対象 | 対応優先度 | 理由 |
|---|---|---|
| Semantic Kernel PythonでClaude系モデルを呼び出している | 高 | 直接影響する可能性がある |
| 長い system prompt を毎回送っている | 高 | キャッシュ効果が出やすい |
| ツール定義を多数持つエージェントを運用している | 高 | tool definitions の再送コストを抑えられる可能性がある |
| 短い単発プロンプトだけを使っている | 低 | キャッシュの恩恵が小さい |
| .NET版やJava版のみを使っている | 低 | 今回のPRはPython向けの差分 |
| Anthropic connectorを使っていない | 低 | 直接の移行作業は不要 |
注意したいのは、PRがオープン状態である点です。GitHub上では、2026年5月時点で microsoft:main へのマージを目指すPRとして表示されています。実際に利用する前に、使っている Semantic Kernel のバージョンにこの変更が含まれているかを確認してください。(GitHub)
既存コードへの影響と移行方針
今回の変更は、既存コードを壊すよりも、新しいオプションを追加する性格が強い更新です。PR本文では、キャッシュはデフォルトでオフであり、AnthropicCacheSettings.on() などで明示的に有効化する設計が示されています。(GitHub)
移行時は、次の順序で確認すると失敗しにくくなります。
| 手順 | 作業 | 確認すること |
|---|---|---|
| 1 | 利用中の Semantic Kernel バージョンを確認 | AnthropicCacheSettings が含まれているか |
| 2 | Anthropic connector の利用箇所を洗い出す | AnthropicChatPromptExecutionSettings を使っているか |
| 3 | system prompt と tools の安定性を確認 | 毎回変わる値が混ざっていないか |
| 4 | 検証環境で 5m を有効化 | usage のキャッシュ関連トークンを見る |
| 5 | 呼び出し間隔が長い処理だけ 1h を検討 | 書き込みコストに見合う再利用があるか |
| 6 | 本番では環境変数で段階的に有効化 | 障害時にすぐOFFへ戻せるか |
特に重要なのは、system prompt に動的な値を入れないことです。たとえば、次のような system prompt はキャッシュに向いていません。
あなたはサポート担当です。
現在時刻は 2026-05-06 09:00 です。
ユーザーIDは 12345 です。この場合、現在時刻やユーザーIDがリクエストごとに変わるため、同じ prefix として扱われにくくなります。静的な役割定義や出力ルールは system prompt に置き、ユーザー固有情報や時刻は user message 側に分けると、キャッシュ効率を高めやすくなります。
cache_controlの注入位置で注意すべきこと
PRの実装では、system message が文字列の場合は {"type": "text", "text": system, "cache_control": ...} のような配列形式に変換し、system がリストの場合は最後のブロックに cache_control を付与します。また、tools については最後の tool definition に cache_control を付ける設計です。(GitHub)
この「最後のブロックに付ける」という考え方は、Anthropic のキャッシュ仕様と相性があります。Anthropic のドキュメントでは、キャッシュの階層は tools → system → messages の順で構成され、tool definitions の変更は system や messages 側のキャッシュにも影響すると説明されています。(Claude Platform)
実務では、次の点を確認してください。
- tool definitions の順序を毎回変えない
- ツール名、説明、パラメータ定義を頻繁に変更しない
- 動的な説明文を tool definition に埋め込まない
- system prompt の末尾に現在時刻やリクエスト固有情報を追加しない
- 既に
cache_controlを手動指定している場合、二重指定にならないか確認する
PRでは、既存の cache_control がある場合は上書きしないガードも追加されています。これは、開発者がすでに明示的なキャッシュポイントを設定しているケースで、意図しない上書きを避けるために重要です。(GitHub)
動作確認ではusageフィールドを見る
キャッシュが効いているかは、体感だけでは判断しない方が安全です。Anthropic のドキュメントでは、レスポンスの usage に含まれる cache_creation_input_tokens、cache_read_input_tokens、input_tokens を使ってキャッシュ性能を確認できると説明されています。(Claude Platform)
確認時の目安は次の通りです。
| 状態 | 見るべき値 | 解釈 |
|---|---|---|
| 初回リクエスト | cache_creation_input_tokens が増える | キャッシュ書き込みが発生している |
| 2回目以降 | cache_read_input_tokens が増える | キャッシュヒットしている |
| 常に0 | creation/read がどちらも0 | 最小トークン数不足、内容変更、TTL切れの可能性 |
| readが増えない | creationだけ増える | 毎回別のprefixとして扱われている可能性 |
CIや単体テストでは、private helper を直接テストするより、prepare_settings_dict() の出力に cache_control が入るかを見るのが実装変更に強い確認方法です。PRでも、TTL確認を private helper ではなく公開面である prepare_settings_dict() 経由に移す対応が示されています。(GitHub)
導入前に決めるべき運用ルール
prompt caching はコスト削減に役立つ可能性がありますが、導入すると「どこまでを静的プロンプトとして扱うか」という設計が重要になります。特にエージェント開発では、system prompt、tool definitions、RAGのコンテキスト、会話履歴が混ざりやすいため、最初にルールを決めておくべきです。
おすすめは、次のように分けることです。
| プロンプト要素 | 配置 | キャッシュ適性 |
|---|---|---|
| 役割、出力形式、禁止事項 | system prompt | 高い |
| 大量の固定ガイドライン | system prompt または固定コンテキスト | 高い |
| ツール名、説明、JSON schema | tools | 高い |
| ユーザー名、現在時刻、リクエストID | user message または別パラメータ | 低い |
| 検索結果、最新データ、個別ドキュメント | messages / context | 内容次第 |
| 会話履歴 | messages | マルチターンでは有効な場合がある |
キャッシュを効かせたいなら、「毎回変わるものを前に置かない」ことが大切です。Anthropic のドキュメントでも、静的なコンテンツをプロンプトの先頭に置き、リクエストごとに変わる suffix ではなく、同一性が保たれる prefix の終端に breakpoint を置くことが推奨されています。(Claude Platform)
今すぐ対応すべきチェックリスト
Semantic Kernel PythonでAnthropic connectorを使っている場合は、次の順で確認してください。
- 利用中の Semantic Kernel に
AnthropicCacheSettingsが含まれているか確認する - PRがマージ済みか、リリース済みパッケージに反映済みか確認する
- 長い system prompt や大量の tool definitions を送っている箇所を洗い出す
- system prompt に時刻、ユーザーID、セッション固有情報が混ざっていないか確認する
- まずは
ttl="5m"で検証する - レスポンスの
cache_creation_input_tokensとcache_read_input_tokensを記録する - 効果がある処理だけ本番で環境変数から有効化する
- 1時間TTLは、呼び出し間隔が5分を超える処理に限定して検討する
今回の Microsoft developer platform documentation update は、単なる小さなPython設定追加ではなく、Semantic KernelでClaude系モデルを使うエージェント開発のコスト設計に関わる更新です。まずは「長くて変わらない system prompt」「安定した tool definitions」「短時間に繰り返す呼び出し」があるかを確認し、該当する処理から段階的に prompt caching を試すのが現実的な対応です。
コメント