# エージェントリリース管理——ブルーグリーン・カナリア展開の設計

> エージェントのコード・プロンプト・モデル・ツールスキーマをバージョン管理し、ブルーグリーンとカナリアリリースで本番展開する設計を解説する。品質ゲートの自動化とロールバックトリガーの実装まで踏み込む。

- Canonical: https://kuucorp.com/blog/agent-blue-green-canary-deployment/
- Date: 2026-06-22
- Last modified: 2026-06-22
- Publisher: Kuu株式会社 (https://kuucorp.com)

---
本番エージェントのプロンプトを改善して再デプロイしたとたん、出力品質が低下した——このパターンは従来のコード変更と異なり、テスト環境では発見しづらい。エージェントは**コード・プロンプト・モデルバージョン・ツールスキーマ**という4コンポーネントが絡み合っており、従来のブルーグリーンデプロイをそのまま適用できない。プロンプト1行の変更が振る舞いを静かに変え、ツールスキーマの更新が連鎖障害を起こす。エンタープライズのエージェント基盤では、この複雑性に対応したリリース管理アーキテクチャが必要だ。

## なぜエージェントのリリース管理は難しいのか

> エージェントはコード・プロンプト・モデル・ツールスキーマの4コンポーネントが絡み、ツールスキーマ変更だけで本番障害の60%が起きるという現実が従来のデプロイパイプラインを無効にします。

従来のソフトウェアはコードSHAひとつで状態を再現できる。エージェントはそうではない。同じコードでも、プロンプトテンプレートのバージョン・使用モデルのバージョン（例: `claude-sonnet-4-6` から `claude-opus-4-8` への切り替え）・ツールスキーマのバージョンが異なれば、エージェントの振る舞いは別物になる。

このうちツールスキーマ変更が最もサイレントに致命的だ。ある調査では本番エージェント障害の60%がツールスキーマの変更に起因するという結果が出ている。`resetPassword` ツールのパラメータ名が変わるだけでエージェントの推論が崩れ、下流タスク全体がエラーになる。コードのユニットテストではこの変化を検出できない。

さらにエージェントは**非決定論的**だ。同じプロンプトで100回実行しても出力は毎回異なりうる。A/Bテストで「新バージョンが優れている」と判断するには統計的有意差を持つサンプル数が必要であり、マイクロサービスのレスポンスタイム比較より判定が難しい。

## エージェントマニフェストをどう設計するか

> エージェントマニフェストはcode SHA・promptバージョン・モデルID・ツールスキーマバージョンを1つの追跡可能な単位として管理し、バージョン間の完全な再現性を保証する設計基盤です。

バージョン管理の出発点は**エージェントマニフェスト**の定義だ。1つのエージェントを特定するには以下を揃える必要がある。

```json
{
  "agent_id": "support-agent",
  "version": "2.4.1",
  "code_sha": "a1b2c3d",
  "prompt_version": "v12",
  "model_id": "claude-sonnet-4-6",
  "tool_schemas": {
    "resetPassword": "v3",
    "openTicket": "v5"
  }
}
```

このマニフェストをGitで管理し、CI/CDパイプラインのデプロイアーティファクトとして扱う。プロンプト変更も「プロンプトテンプレートのPRレビュー → マニフェストのバージョン更新 → ステージング評価」というコードと同等のワークフローを通す。AWSはこのパターンを「プロンプトはコードと同様に重要」として推奨しており、[Amazon Bedrock Prompt Management](https://aws.amazon.com/bedrock/prompt-management/)や類似のツールで実装できる。

Gitへのプロンプトバージョン管理は `prompts/agent-id/v12/system.txt` のような階層構造が運用しやすい。変更差分がPRで可視化されるため、承認ワークフローと自動評価チェックを統合できる。

## ブルーグリーンとカナリアをどう使い分けるか

> ブルーグリーンは大規模変更を即時切り替えで安全に展開し、カナリアは5%→25%→100%の段階的展開で本番検証する。変更の規模と許容ダウンタイムで使い分けます。

**ブルーグリーン（Blue/Green）**

2つの完全な本番環境（Blue=現行、Green=新バージョン）を並走させ、LLMゲートウェイのルーター設定変更だけでトラフィックを即時切り替える。モデルバージョンのメジャーアップグレードや、ツールスキーマの破壊的変更など「一括移行が必要な変更」に適する。ロールバックはルーター設定を元に戻すだけで完了する——再デプロイは不要だ。インフラコストは2倍になるが、カットオーバー時の停止時間はゼロだ。

**カナリアリリース**

新バージョンに5%のトラフィックをルーティングし、品質ゲートを通過したら25%、さらに通過したら100%へ段階的に拡大する。プロンプト改善・モデルのマイナーアップデート・新機能追加など「段階的に検証しながら展開したい変更」に向く。ブルーグリーンより安価だが、2バージョンが本番で同時稼働するため、ステートフルな会話を持つエージェントではセッション管理に注意が必要だ。

使い分けの判断基準:

| 変更種別 | 推奨戦略 |
|---|---|
| モデルバージョンのメジャー変更 | ブルーグリーン |
| ツールスキーマの破壊的変更 | ブルーグリーン |
| プロンプト改善・チューニング | カナリア |
| 新機能（新ツール追加） | カナリア |

## カナリア品質ゲートと自動ロールバックをどう実装するか

> カナリアのエラー率・レイテンシ・ツール呼び出しパターン・LLM-as-a-judge品質スコアの4ゲートが自動化の核心で、いずれか失敗時に即時100%ロールバックを起動します。

カナリアの5%フェーズで監視する4つの品質ゲートを定義する。

1. **エラー率**: カナリアのエラー率が安定版の1.5倍を超えたら即時ロールバック
2. **レイテンシ**: P95レイテンシが安定版の120%超でロールバック
3. **ツール呼び出しパターン**: ツール選択分布の統計的乖離が閾値を超えたらロールバック（これはエージェント固有の指標）
4. **LLM-as-a-judge品質スコア**: カナリアの出力を別モデルで自動採点し、安定版との差が閾値以下ならロールバック

ロールバックは「設定変更による再ルーティング」として実装する。再デプロイは不要だ。LLMゲートウェイのルーティングタグを `canary → stable` に切り戻すだけで、午前3時に障害が発生しても人間の介入なしに自動復旧できる。LLMゲートウェイとの統合設計は[LLMゲートウェイ設計——モデルルーティング・レート制限・コスト配賦](/blog/llm-gateway-routing-rate-limiting/)を参照されたい。

## シャドーモードと本番ドリフト検知はどう設計するか

> シャドーモードは新バージョンを本番トラフィックで動かしながらユーザーに影響を与えない安全な事前検証手段で、ゴールデンテストケースによる定期ドリフト検知と組み合わせます。

**シャドーモード（Shadow Mode）**

新バージョンを本番トラフィックと並走させながら、出力をユーザーには届けない手法だ。安定版の出力とシャドー版の出力を比較することで、カナリアより低リスクで実挙動を観察できる。プロンプトのマイナー変更・新モデルのバージョン評価に特に有効だ。AWSのガイドラインでもシャドーモードを「新しいプロンプトやモデルの安全なロールアウトのために不可欠」と位置づけている。

**ゴールデンテストケースによるドリフト検知**

ベースラインを記録したゴールデンデータセットを本番デプロイごとに実行し、出力の変化を検知する。モデルプロバイダー側のサイレント変更（例: Anthropicによるモデルアップデート）を検出するためにも定期実行が必要だ。ゴールデンデータセットの設計については[エージェント回帰テストとゴールデンデータセット](/blog/agent-regression-test-golden-dataset/)を参照されたい。

マルチチーム環境でエージェントリリース管理・LLMゲートウェイ統合・品質ゲート自動化を包括的に設計・実装するには、[Kuu の RDE サービス](/services/rde/)でご相談いただきたい。

## 参考

- [Prompt, agent, and model lifecycle management — AWS Prescriptive Guidance](https://docs.aws.amazon.com/prescriptive-guidance/latest/agentic-ai-serverless/prompt-agent-and-model.html)
- [Blue-green deployment vs canary release — Unleash](https://www.getunleash.io/blog/blue-green-deployment-vs-canary-release)

## まとめ

エージェントのリリース管理が従来のソフトウェアデプロイより難しい本質は、コードではなく**コード・プロンプト・モデル・ツールスキーマ**の4コンポーネントが個別にバージョンを持ち、相互作用するためだ。エージェントマニフェストでこの4軸を一元管理し、変更規模に応じてブルーグリーンとカナリアを使い分け、エラー率・レイテンシ・ツール呼び出しパターン・LLM品質スコアの4ゲートで自動ロールバックを実装する——この体制がエンタープライズ規模の安全な継続的デリバリーの土台となる。

エージェント基盤の設計・展開管理の高度化について相談は[Kuu の RDE サービス](/services/rde/)から。