結論 — 5/13 リリースは「キャッシュ可観測性」と「Agents の RAG 化」の 2 軸
結論を先に書きます。v0.96.0 の追加 2 点は、それぞれ違うベクトルの実務改善です。changelog 上は 2 行ですが、SDK の型定義を読むと API 設計の意図がはっきり見えます。
cache diagnostics beta— プロンプトキャッシュ（送信プロンプトの前方一致再利用）が外れた時に、外した原因の enum をサーバが返す機能BetaManagedAgentsSearchResultBlock— Managed Agents（Anthropic のホスト型エージェント）が tool 実行結果として返せるブロック型に、検索結果用の構造体が追加された
前者は「キャッシュは効いているはずなのに料金が下がらない」問題に直接効きます。後者は Managed Agents 側を RAG として運用する時のデータ表現が、Web 検索結果と同じ citation 付きの形に揃ったということです。今日 (2026-05-19) 時点でどちらも beta ヘッダ越しの呼び出しになります。
cache diagnostics beta は何を返すか
要点を先に書きます。Messages API のリクエストに diagnostics.previous_message_id を入れると、レスポンス側に diagnostics.cache_miss_reason が返ってきます。SDK の型定義 (src/resources/beta/messages/messages.ts) から該当箇所を引きます。
export interface BetaDiagnosticsParam {
// 前回 /v1/messages レスポンスの id (msg_...)
// 初回ターンは null を渡すと「比較対象なし」で opt-in できる
previous_message_id?: string | null;
}
export interface BetaDiagnostics {
cache_miss_reason:
| BetaCacheMissModelChanged
| BetaCacheMissSystemChanged
| BetaCacheMissToolsChanged
| BetaCacheMissMessagesChanged
| BetaCacheMissPreviousMessageNotFound
| BetaCacheMissUnavailable
| null;
}
つまりサーバ側は、前回リクエストのプロンプト指紋（fingerprint）と今回のそれを バックグラウンドで比較 し、外れた理由を 6 種の enum から 1 つ返します。null が来た場合は「比較がまだ終わってない（レスポンスを serialize した時点で間に合わなかった）」というメッセージで、これも型コメントに書いてあります。
私が型定義を読んで「うまい」と思ったのは、「キャッシュが効いた」を返すのではなく「外れた時だけ理由を返す」設計 にしている点です。ヒットしている時はデフォルトの請求情報（usage.cache_read_input_tokens）を見れば分かるので、診断は外した時に限定して帯域を節約しています。
SDK から叩く時の実装ノート
結論から書くと、Redis に直近の msg_id を 1 つ持っておいて、次のリクエストの diagnostics.previous_message_id に詰めるだけ です。私は素のフィールド名で素直に渡しています。
import Anthropic from '@anthropic-ai/sdk';
const client = new Anthropic();
const previous = await redis.get(`anthropic:lastMsgId:${userId}`);
const resp = await client.beta.messages.create({
model: 'claude-opus-4-7',
max_tokens: 1024,
messages: [{ role: 'user', content: prompt }],
diagnostics: { previous_message_id: previous ?? null },
betas: ['cache-diagnostics-2026-05-13'],
});
await redis.set(`anthropic:lastMsgId:${userId}`, resp.id, 'EX', 600);
if (resp.diagnostics?.cache_miss_reason) {
metrics.increment('anthropic.cache_miss', {
reason: resp.diagnostics.cache_miss_reason,
});
}
最初に試した時、previous_message_id を undefined で渡してしまって cache_miss_reason が返らず 5 分悩みました。opt-in 用に null 明示が要る のがちょっと意外で、これは型コメントを読まないと引っかかります（余談ですが、cache_miss_reason の enum 名がどれも長くて、Datadog の tag に流すとログ 1 行で折り返します）。
どの reason をどう見るかは現場ごとに違いますが、私の今の方針は次のとおりです。
| reason | 意味 | 対応 |
|---|---|---|
model_changed | モデル ID が前回と違う | 仕様。料金変動を確認 |
system_changed | system prompt が変わった | system は固定したい場合は警告 |
tools_changed | tools 配列が違う | tools 順序のソート漏れを疑う |
messages_changed | messages 前半が違う | キャッシュ境界の breakpoint を疑う |
previous_message_not_found | TTL 切れ or 別 workspace | 5 分 TTL を意識する |
unavailable | サーバ側で比較不能 | 一時的なら無視 |
BetaManagedAgentsSearchResultBlock は何が変わったか
要点を先に書きます。Managed Agents の tool 結果ブロックの選択肢に、Web 検索結果用の構造体が加わりました。src/resources/beta/sessions/events.ts の該当部分はこうです。
export interface BetaManagedAgentsSearchResultBlock {
citations: BetaManagedAgentsSearchResultCitations; // { enabled: boolean }
content: Array<BetaManagedAgentsSearchResultContent>; // text block 配列
source: string; // 検索結果の URL
title: string; // 結果タイトル
tool_use_id: string; // どの tool 呼び出しの結果か
type: 'search_result';
}
注目したいのは、type: 'search_result' という識別子で、BetaManagedAgentsDocumentBlock と並ぶ位置に来ている ところです。これまで Managed Agents の tool 結果に詰められるのはテキスト / 画像 / ドキュメントが中心でしたが、ここに来て「検索結果」が一級市民として入ったわけです。
つまり Managed Agents を RAG（Retrieval-Augmented Generation、検索拡張生成）として運用する側のコードが書きやすくなります。自前の検索（社内ナレッジベース / Elasticsearch / pgvector）の結果を、Anthropic の Web Search 結果と同じ形に揃えて agent に返せます。citation の取り回しも、citations.enabled フラグで agent 側のレスポンスに参照リンクが入るかどうかを 1 bit で制御できます。
実運用に乗せる時の私の判断
結論から書くと、cache diagnostics は本番でも入れる、Managed Agents 検索ブロックは観測だけ先に入れる です。理由は両者の成熟度が違うからです。
cache diagnostics は副作用がほぼゼロです。リクエスト 1 フィールド追加で、レスポンスに 1 オブジェクト増えるだけ。私は Vercel AI SDK ではなく素の @anthropic-ai/sdk を使っているので、betas: ['cache-diagnostics-2026-05-13'] を渡せばすぐ動きます。ハンドリングコストより、料金が想定外に伸びた時の調査時間が圧倒的に重いので、入れない理由がありません。
Managed Agents の検索ブロックの方は、自社の RAG パイプラインを Managed Agents に寄せる判断 が前提です。私の今の構成は @anthropic-ai/sdk を直接叩いて RAG を自前で組んでいるので、当面は型定義を読んで観測だけ入れ、移行は急ぎません。Managed Agents が GA に近付いてから、検索結果型の互換を意識して自前 RAG の返却形式を寄せていく予定です。
まとめ
3 行で締めます。
- v0.96.0 は短い changelog の裏で 「キャッシュ可観測性」と「Agents の RAG 化」 の 2 軸を進めた
cache_miss_reasonenum 6 種は本番でメトリクスに流す価値が大きい（私は Datadog の tag に流しました）BetaManagedAgentsSearchResultBlockは Managed Agents 経由の RAG 運用を見据えた一手で、自前 RAG を組んでいる側は 返却形式の互換 だけ意識しておくと将来の移行が楽です
Claude Skills と CONTENT_GUIDELINES の時にも書きましたが、SDK の changelog は「行数」では情報量が測れません。型定義まで読みに行くと、API の設計意図が地続きで見えます。