AIエージェントのバージョン管理、普通のソフトウェアと何が違う？
ミドリ： タツヤさん、AIエージェントのプロンプトをちょっと変えたら品質がガタ落ちして……。元に戻そうとしたけど、前のバージョンがどれだったかわからなくなったんです。
タツヤ： あるあるだね。「新しいプロンプトにしたら品質が大幅低下」「モデルをアップグレードしたら予期しない挙動が増えた」……バージョン管理が不十分な環境で頻繁に起きる事故だよ。
ミドリ： GitHubでコード管理してるのに、なんで防げないんですか？
タツヤ： そこがポイント。GitHubのState of Octoverse 2024レポートによるとAIアプリケーションのリポジトリ数は前年比59%増加してる。でもAIエージェントのバージョン管理は、普通のソフトウェアとは根本的に違うんだ。
AIエージェントのバージョン管理が難しい理由
ミドリ(surprised)： 何がそんなに違うんですか？
タツヤ： 従来のソフトウェアなら、バージョンを構成する要素はソースコードと設定ファイルが中心。差分を追跡して、ビルド→テスト→デプロイで管理できる。でもAIエージェントは構成要素が多岐にわたるんだ。
- プロンプト：システムプロンプト、Few-shot例、テンプレート
- モデル：使用するLLMの種類・バージョン（例：GPT-4o → GPT-4o-mini への切り替え）
- パラメータ：temperature（応答のランダム性）、max_tokens、top_p 等
- ツール定義：エージェントが利用可能なツールの一覧と設定
- ナレッジベース：RAGで参照するドキュメント群
- アプリケーションコード：オーケストレーション、前処理・後処理のロジック
- 依存ライブラリ：LangChain、LlamaIndex等のバージョン
ミドリ： めちゃくちゃ多いですね……。
タツヤ： しかもこれらのどれか一つが変わるだけで挙動が変化する可能性がある。だからすべての構成要素を一つの「バージョン」として紐付けて管理する仕組みが必要なんだ。
セマンティックバージョニングをAIに適用する
ミドリ(thinking)： じゃあ、どうやって管理すればいいんですか？
タツヤ(nodding)： まずバージョニング戦略。ソフトウェアで広く使われているセマンティックバージョニング（メジャー.マイナー.パッチ）をAIエージェントの文脈に合わせて再定義する。
| バージョンレベル | 変更内容の例 | リリース時の対応 |
|---|---|---|
| メジャー（X.0.0） | LLMモデルの変更、大幅なプロンプト書き換え、ツールの追加・削除 | 全環境でのフルテスト、段階的ロールアウト必須 |
| マイナー（0.X.0） | プロンプトの微調整、パラメータ変更、ナレッジベースの更新 | 統合テスト＋E2Eテスト、カナリアリリース推奨 |
| パッチ（0.0.X） | バグ修正、ログ追加、設定値の微修正 | ユニットテスト＋統合テスト、即時デプロイ可 |
ミドリ： LLMモデルの変更はメジャーバージョンアップなんですね。
タツヤ： 挙動が大きく変わる可能性があるからね。次に重要なのが構成のスナップショット管理。各バージョンに対して、すべての構成要素をスナップショットとして保存して、任意の時点の状態を完全に再現できるようにする。
ミドリ(thinking)： 具体的に何を保存するんですか？
タツヤ： プロンプトテンプレートの全文、LLMモデルのID（例：gpt-4o-2024-11-20）とパラメータ設定、ツール定義のJSON、ナレッジベースのスナップショットIDまたはハッシュ値、アプリケーションコードのGitコミットハッシュ、依存ライブラリのロックファイル。これらをまとめて「エージェント構成マニフェスト」としてGitで管理するんだ。
3つの環境を用意する
ミドリ(nodding)： 管理方法はわかりました。次はどう環境を作ればいいですか？
タツヤ： 安全なリリースのために最低3つの環境を用意する。
開発環境
タツヤ： 開発者がプロンプトの修正やコード変更を自由に試す環境。ポイントは、LLM APIは本番と同じモデルを使うこと。違うモデルだと挙動の差異が出るからね。テストデータは匿名化された本番データのサブセットを使って、コスト管理のためAPIの利用量に上限を設定。
ステージング環境
タツヤ： 本番と同一構成でリリース前の最終検証を行う環境。評価データセットでの自動品質テスト、パフォーマンステスト、少数のテストユーザーによるUAT（ユーザー受入テスト）を実施する。
本番環境
タツヤ： 実際のユーザーにサービスを提供する環境。段階的ロールアウトで新バージョンを展開して、リアルタイム監視とアラートが稼働してること。そしてロールバック手順が事前に準備されていること。
ミドリ： ロールバックは事前に用意しておくものなんですね。
デプロイメント戦略 ── 4つの方式
ミドリ： 本番への出し方にもいろいろあるんですか？
タツヤ： 4つの方式がある。
ブルーグリーンデプロイ
タツヤ： 2つの同一環境（ブルーとグリーン）を用意して、新バージョンをグリーン環境にデプロイしてからトラフィックを切り替える方式。問題があれば即座にブルーに切り戻し。ロールバックが数秒〜数分で完了する。
ミドリ： 超速いですね。デメリットは？
タツヤ： 2倍のインフラコストが一時的に必要になること。でもロールバックの安心感を考えたら安いもんだよ。
カナリアリリース
タツヤ： 新バージョンを一部のトラフィック（最初は5〜10%）にだけ適用して、段階的に拡大していく方式。
- 5%のトラフィックに新バージョンを適用（1〜2時間観察）
- 品質指標が正常なら25%に拡大（4〜8時間観察）
- 問題なければ50%に拡大（24時間観察）
- 最終的に100%に展開
ミドリ： 途中で問題が見つかったら？
タツヤ： 即座にロールバック。判断基準は明確に決めておく。エラー率が旧バージョンの2倍以上、P95レスポンスタイムが1.5倍以上、ネガティブフィードバック率が10%以上増加、のいずれかに該当したらアウト。
フィーチャーフラグ
タツヤ： コードレベルで機能の有効/無効を切り替える仕組み。デプロイとリリースを分離できるのが最大のメリット。新しいツールの段階的公開、プロンプトバリエーションの切り替え、特定ユーザーグループへの先行リリースに使える。
ミドリ： ツール例は？
タツヤ(thinking)： LaunchDarkly、Unleash、AWS AppConfigなど。注意点として、フィーチャーフラグが増えすぎると管理が複雑になるから、リリース完了後は速やかに削除する運用ルールを設けよう。
A/Bテスト
タツヤ： 2つ以上のバージョンを同時に稼働させて、統計的に有意な差があるか検証する手法。各バリエーションに最低1,000件以上のリクエストを振り分けて、曜日の変動を吸収するため最低1週間は実施する。
ロールバック ── 最も重要な保険
ミドリ： 問題が起きたとき、どれだけ早く戻せるかが勝負ですよね。
タツヤ(nodding)： その通り。ロールバック戦略はバージョン管理の最重要項目。
自動ロールバックの条件
タツヤ： 以下のいずれかに該当したら、人間の判断を待たずに自動でロールバックを実行する。
- エラー率がデプロイ前の3倍以上に急増
- 可用性が99%を下回った状態が5分以上継続
- P95レスポンスタイムがSLOの2倍を超過
ロールバックの3種類
タツヤ： 状況に応じて3種類を使い分ける。
- インスタントロールバック：ロードバランサーの切り替えで即座に実行（ブルーグリーンの場合）
- 段階的ロールバック：新バージョンへのトラフィック割合を段階的に減らす（カナリアの場合）
- 構成ロールバック：プロンプトやパラメータのみを前バージョンの値に戻す（コード変更がない場合）
ミドリ： ロールバック後はどうするんですか？
タツヤ： 3ステップ。ロールバックの理由と影響範囲をインシデントレポートとして記録 → 問題の根本原因を調査して修正パッチバージョンを作成 → ステージングで十分検証してから再デプロイ。
CI/CDパイプラインを組む
ミドリ： これ全部を手動でやるのは無理ですよね？
タツヤ： 当然、CI/CD（継続的インテグレーション/継続的デリバリー）パイプラインで自動化する。推奨フローはこう。
- コード/プロンプト変更をGitにプッシュ
- CI（自動テスト）が起動 — プロンプトの構文チェック、ユニットテスト、統合テスト。評価データセットでの品質スコア算出。品質ゲートの通過確認
- ステージング環境への自動デプロイ — E2Eテスト、パフォーマンステスト。人間によるレビュー・承認
- 本番環境への段階的デプロイ — カナリアリリースまたはブルーグリーンデプロイ。リアルタイム監視、自動ロールバック機構
ミドリ： プロンプトの変更もCIでテストされるんですね。
タツヤ： そこが重要。コードだけじゃなくてプロンプトの変更も同じパイプラインに乗せる。だからプロンプトもGit管理対象にしないといけないんだ。
まとめ：全構成要素を統合管理する
ミドリ： 今日の話をまとめると？
タツヤ： AIエージェントのバージョン管理は、コードだけじゃなくプロンプト・モデル・パラメータ・ナレッジベースを含むすべての構成要素を統合的に管理する必要がある。
- セマンティックバージョニングをAIの文脈に適用して変更の影響度を明確にする
- 構成スナップショットで任意の時点の状態を完全再現可能にする
- 3環境構成（開発→ステージング→本番）で段階的に品質を検証する
- デプロイメント戦略（ブルーグリーン、カナリア、フィーチャーフラグ、A/Bテスト）を組み合わせてリスクを最小化する
- 自動ロールバックを組み込んで問題発生時の影響を最小限に抑える
ミドリ： 「プロンプトを変えたら元に戻せなくなった」はもう卒業ですね。
タツヤ： そう。まずは今のエージェントの構成要素を全部リストアップして、Git管理外のものがないか確認するところから始めよう。
次のアクション
まずは現在のAIエージェントの構成要素（プロンプト、モデル、パラメータなど）をリストアップし、それぞれがどこで管理されているかを整理してみてください。「構成要素のどれかがGit管理外にある」という状態が見つかれば、それがバージョン管理の最初の改善ポイントです。
Shimanto AI Solutionsでは、AIエージェントのCI/CDパイプライン構築とバージョン管理戦略の策定を支援しています。安定した本番運用と迅速な改善サイクルの両立でお悩みの方は、お気軽にご相談ください。