# 録画再生でLLMエージェントの回帰テストを固定する

> LLM API呼び出しはvcrpyの録画再生で固定でき、CIの回帰テストを課金ゼロ・決定的にできます。record_mode四種の使い分けと機密除去、body照合の落とし穴を整理します。

- Canonical: https://kuucorp.com/blog/llm-api-record-replay-cassette-regression-test/
- Date: 2026-11-21
- Last modified: 2026-11-21
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
プロンプトを一行直すたびに、CIが実APIを叩く。課金が膨らみ、結果も毎回揺れ、落ちた理由が「変更のせい」なのか「モデルの気まぐれ」なのか切り分けられない。品質評価（eval）とは別に、**コードの回帰だけを決定的に検査する層**が必要です。その最小構成が、HTTP通信の録画再生（cassette方式）です。関連する評価設計は[エージェント評価のフレーキー対策](/blog/agent-eval-flaky-nondeterminism-reproducibility-design/)も参照してください。

## 録画再生テストは何を検査し、何を検査しないのか

> 録画再生は、実APIの応答を保存して再生し、呼び出し側コードの回帰だけを決定的に検査する手法です。

録画再生とは、初回に実APIへ送ったリクエストと応答をファイル（cassette）に保存し、以降はその応答を返す仕組みです。Pythonでは vcrpy が代表的で、HTTPクライアントの層で通信を横取りします。

検査できるのは、リクエストの組み立て、ツール結果のパース、リトライや例外処理、会話履歴の積み方といった**自分のコード**の挙動です。検査できないのは、モデル自体の回答品質です。応答は固定されているため、モデルを入れ替えても点数は変わりません。品質は従来どおりevalで測り、録画再生は「配線が壊れていないか」を見る層と割り切ります。

- 録画再生: 速い・無料・決定的。コードの回帰を検出する
- eval: 遅い・有料・確率的。モデルとプロンプトの品質を測る

## record_modeはどう使い分けるのか

> vcrpyのrecord_modeは once・new_episodes・none・all の4種類で、CIでは none が基本です。

vcrpyには4つの記録モードがあります。

- `once`（既定）: 保存済みを再生し、cassetteが無いときだけ記録する。cassetteがあるのに未記録のリクエストが来ると例外になる
- `new_episodes`: 保存済みを再生しつつ、新しいやり取りも記録する。意図しないリクエストを黙って記録するため、回帰検知には向かない
- `none`: 再生のみ。新しいリクエストは例外になり、実APIには一切出ない
- `all`: 常に記録し、再生しない。応答を作り直したいときに使う

運用は次の分担が安定します。ローカルで意図的に `all` を使ってcassetteを更新し、差分をレビューしてコミットします。CIでは `none` に固定します。これで「プロンプト変更で送信内容が変わったのに、cassetteが古いまま」という状態は、例外として即座に見えます。

## リクエスト照合と機密除去はどう設計するのか

> 既定の照合はmethod・URL系のみで、bodyは比較されません。bodyの照合とAPIキー除去は明示設定が必要です。

既定の `match_on` は method・scheme・host・port・path・query で、**リクエスト本文は比較されません**。LLM APIは同じURLに全リクエストを送るため、既定のままだと別のプロンプトでも同じ応答が返り、プロンプトを壊しても緑のままになります。`match_on` に `body` を加え、JSON本文を意味単位で比較させます。

ただし本文には、タイムスタンプや生成IDなど毎回変わる値が混ざりがちです。その場合は `register_matcher` で独自の照合関数を登録し、揺れる項目を除いた上で比較します。

機密は記録の前に落とします。

- `filter_headers` で `authorization` 等のヘッダを除去または固定値へ置換する
- `filter_query_parameters` でクエリ中のキーを除去する
- `before_record_request` / `before_record_response` で本文中の個人情報を加工する。これらは読み込み時にも走るため、何度適用しても同じ結果になる（冪等な）関数にする
- `ignore_hosts` で、録画対象外のホストを素通しにする

cassetteはリポジトリに入るファイルです。キーや顧客データが入ったままコミットすれば、そのまま漏洩になります。

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

SMBでは、まずクリティカルな3〜5経路だけをcassette化し、CIの `none` 固定を最優先にします。導入の進め方は[AI導入の伴走支援](https://kuucorp.com/services/ai-ops/)でも扱っています。エンタープライズでは、cassetteを監査対象の成果物として扱い、機密除去フィルタを共通ライブラリに集約し、複数チームで更新レビューのルールを統一します。大規模な統制設計は[RDE](https://kuucorp.com/services/rde/)の対象です。

## 参考

- [VCR.py Usage（record modes）](https://vcrpy.readthedocs.io/en/latest/usage.html)
- [VCR.py Advanced Features（filter・hook・custom matcher）](https://vcrpy.readthedocs.io/en/latest/advanced.html)
- [VCR.py Configuration（match_on の既定値）](https://vcrpy.readthedocs.io/en/latest/configuration.html)

## まとめ

> 録画再生は品質評価の代替ではなく、コード回帰を安く確実に止めるための補完層として運用します。

CIは `none` で固定し、更新はローカルの `all` で意図的に行い、`body` 照合と機密除去を設定する。この三点で、LLMを呼ぶコードの回帰は決定的に検査できます。評価基盤の設計や運用体制づくりは、[Kuu株式会社への無料相談](https://kuucorp.com/contact/)からご相談ください。
