AI エージェント本番チェックリスト：ログ、監視、アラート、ロールバック、カナリアリリース

金曜の午後、客服エージェントを 5% のユーザーに開放しようとしています。カナリア設定はそろっています。流量比率、観測ウィンドウ、アラートしきい値。最後に確認したところ、3 つの問題が見つかりました。

1. feature flag がなく、止めるには再デプロイが必要。
2. 人間の承認キューに入っているタスクを、旧バージョンへ戻す方法がわからない。
3. 送信済みメールをツールの副作用と見なすべきか、ロールバック時に取り消すべきか判断できない。

この 3 つは、HTTP 500 やレスポンス時間では見えません。エージェントの本番投入では、通常の Web サービスより 8 つ多い観点を見る必要があります。trace、tool calls、guardrails、HITL、eval、cost、secrets、checkpoint です。以下では、この 8 つをリリース前ゲート、カナリア観測、リリース後監視、インシデント時ロールバックの 4 つに分けて確認します。

1. リリース前ゲート：必ず通す 10 個のチェック

1.1 Trace の完全性チェック

リリース前に、trace で 1 回の Agent run 全体を再現できることを確認します。ここが欠けると、事故時に復盤できません。OpenAI Agents SDK には tracing が組み込まれており、LLM generations、tool calls、handoffs、guardrails、custom events を記録します。ただし、その情報が本番環境で完全に残るかどうかは別途確認が必要です。

チェックリスト：

• run ID、trace ID、span ID が正しく関連付けられ、エラーログから具体的なリクエストまで追跡できる。
• model call、tool call、guardrail result が欠損フィールドなしで記録されている。
• 所要時間、token 使用量、エラーコードのフィールドが使え、コストと性能の基準値を計算できる。
• trace の保持方針とマスキングルールが明確で、ストレージコストやコンプライアンスリスクを理由に必要な記録が消えない。
• 開発環境と本番環境で trace export の挙動が一致している。

trace が LLM call だけを記録し、tool call や guardrail result を残していない場合、カナリアで HTTP 200 に見えても、実際にはツール引数が誤っていたり権限境界を越えていたりします。

1.2 機密データのマスキング方針

本番 trace には PII、secret、顧客データが含まれる可能性があります。リリース前に、何を取得し、どうマスキングするかを決めておきます。OpenAI Agents SDK には trace_include_sensitive_data 設定があり、LLM と tool call の完全な入出力を記録するかどうかを制御できます。

チェックリスト：

• trace_include_sensitive_data の設定場所とデフォルト値が明確である。
• PII 検出とマスキングルールが、氏名、メールアドレス、電話番号などの一般的な項目をカバーしている。
• secret の分離ができており、API key やデータベースパスワードが trace やログに出ない。
• 顧客データを公開、社内、機密に分類し、レベルごとに異なるマスキング方針がある。
• マスキング後の trace でもデバッグに使える。

本番環境では、自動 PII 検出と段階的なマスキングを組み合わせるのがおすすめです。コンプライアンスを満たしつつ、デバッグ能力も残せます。

1.3 Guardrails 監視ゲート

guardrails はユーザー入力と agent 出力を検証し、より速い、または安いモデルで不適切なリクエストをブロックできます。OpenAI Agents SDK の tool input guardrail は、関数ツールを呼び出す前に実行されます。ただし guardrails は絶対的な防御線ではありません。リリース前に、観測でき、アラートを出せ、ロールバックに組み込めることを確認します。

チェックリスト：

• input guardrail のブロック率の基準値を測定済みである。
• output guardrail の false positive と false negative の割合がわかっている。
• tool input guardrail がツール呼び出し前に実行されている。
• guardrail trip のアラートしきい値が設定されている。
• false positive を素早くフィードバックできる経路がある。

guardrails 監視ゲートの要件は明確です。ブロック率に基準値があり、誤検知にフィードバック経路があり、アラートにしきい値があること。

1.4 Tool Calls の可観測性

ツール呼び出しの失敗は、エージェントで最もよく起きる失敗パターンの 1 つです。HTTP API は 200 を返していても、ツール引数が誤っている、権限を越えている、外部サービスがタイムアウトしていることがあります。こうした失敗は通常のサービス監視では見えず、trace の中にだけ残ります。

チェックリスト：

• 各ツールの成功率と失敗率の基準値を測定済みである。
• ツール呼び出しのレイテンシ分布（P50/P95/P99）がわかっている。
• 権限境界が明確で、どのツールがどのリソースを呼べるかに allowlist または denylist がある。
• 失敗モードの分類がそろっており、タイムアウト、権限、引数エラー、外部サービス障害で処理方針が分かれている。
• リトライ方針と circuit breaker のしきい値が設定されている。

ツール可観測性の要件は、各ツールに成功率の基準値があり、失敗が分類され、タイムアウトに circuit breaker があることです。

1.5 HITL キュー監視の準備

Human-in-the-Loop（HITL）の承認キュー滞留は、カナリア中に見落とされやすいリスクです。LangGraph checkpointers は各 super-step で graph state を保存し、HITL、time travel、fault tolerance を支えます。ただし、キュー長と承認タイムアウトは個別に監視する必要があります。

チェックリスト：

• HITL キュー長のアラートしきい値が設定されている。
• 承認タイムアウト時の自動処理方針が明確で、拒否、人手への移譲、 degrade のルールがある。
• 中断後の resume 経路を検証済みである。
• 新バージョンへ切り替えるとき、キュー内タスクをどう扱うかが決まっている。

HITL キュー監視の要件は、キュー長にしきい値があり、タイムアウトに方針があり、中断後に復旧できることです。

KiloClaw - 企業向けマネージド OpenClaw、AI エージェントのオーケストレーションとスマートルーティングを加速

今すぐ始める →広告

1.6 Eval Regression Suite

リリース前には、自前の regression suite を実行して能力低下を防ぎます。regression suite には synthetic examples だけでなく、実タスクを含めるべきです。回帰の通過率が基準値を下回るなら、新バージョンには問題がある可能性があり、出すべきではありません。

チェックリスト：

• regression suite に十分な数の実タスクが含まれている。
• 通過率の基準値が明確である（推奨：≥95%）。
• 失敗ケースの分類が明確である。
• suite の実行時間が制御されている（推奨：≤15 分）。
• カナリアの失敗サンプルを suite に戻す仕組みが準備されている。

regression suite は最後のゲートです。通過率が 95% 未満なら、リリース前に修正します。

1.7 Cost Budget と Rate Limit

プラットフォームレベルの費用境界とレート制限は、最後の防線です。OpenAI は usage tracking、billing limits、notification threshold、project-level spend/rate limits の設定を推奨しています。業務コード内の予算判定だけに頼るべきではありません。

チェックリスト：

• project-level spend limit が設定されている。
• usage notification threshold が設定されている（推奨：70%/90%）。
• rate limit がユーザーまたは tenant ごとに分かれている。
• コスト急増アラートが設定されている（時間単位の前期比など）。
• 予算超過時の degrade 方針が明確で、高コストツールを止める、モデルを切り替える、ユーザーを制限するなどの経路がある。

Cost Budget の要件は、予算に上限があり、アラートにしきい値があり、超過時に degrade できることです。

1.8 Secrets の分離と監査

secret 漏えいは、エージェントで最も深刻なセキュリティ事故の 1 つです。エージェントはツール呼び出しを通じて、データベース、サードパーティ API、社内サービスにアクセスします。すべての呼び出しに監査が必要で、actor/subject/tool/resource の 4 フィールドを完全に記録します。

チェックリスト：

• actor/subject/tool/resource の全フィールドが記録されている。
• secret storage が分離され、API key やデータベースパスワードが環境変数や設定ファイルに出ない。
• ツール呼び出し前に secret 検証が実行される。
• 監査ログの保持期間が明確である（推奨：1 年）。
• secret rotation の計画がある。

監査ログは、事故の復盤に欠かせない材料です。

1.9 Checkpoint 復旧の検証

長時間動くエージェントは、失敗後に正しい状態へ復旧できなければなりません。LangGraph checkpointers は各 super-step で graph state を保存し、time travel debugging と fault-tolerant execution を支えます。ただし復旧経路は個別にテストします。

チェックリスト：

• checkpoint の保存頻度が明確で、各 super-step または重要ノードごとに保存される。
• 失敗後の復旧テストを実施済みである。
• 復旧後の状態の正しさを検証済みである。
• 途中まで進んだタスクのクリーンアップ方針が明確である。

Checkpoint 復旧は、長時間動くエージェントの基礎能力です。

1.10 Feature Flag と Kill Switch

再デプロイせずにエージェントを止められる必要があります。OpenFeature は標準的な feature flag 実装を提供し、tenant、ユーザー、タスク種別ごとの制御と、割合ベースの振り分けをサポートします。

チェックリスト：

• feature flag が tenant、ユーザー、タスク種別ごとに分けられている。
• kill switch が 1 分以内に反映される。
• 割合ベースの振り分けをサポートし、カナリアリリースに使える。
• flag 状態の監視と監査が設定されている。

Feature Flag の要件は、段階的に制御でき、素早く反映され、状態を監査できることです。

2. カナリア観測：最初の 10〜30 分で見るもの

リリース前ゲートを通っても、カナリア中に問題が起きないとは限りません。エージェントのカナリアでは、通常サービスの指標（HTTP エラー率、レスポンス時間）とエージェント固有の指標（tool failure rate、guardrail trip rate、cost per run、HITL queue）の 2 層を見ます。

2.1 流量比率と観測ウィンドウ

カナリアを勘で進めてはいけません。Kubernetes と AWS はどちらも、小さな流量から始め、十分な評価期間を置き、指標を監視してから段階的に拡大することを推奨しています。流量比率と時間パラメータは明確に定義します。

チェックリスト：

• 初期流量比率が明確である（推奨：5〜10%）。
• 最小観測ウィンドウが設定されている（推奨：10〜30 分）。
• 観測ウィンドウ内の最小リクエスト数が設定されている。
• 段階的に流量を増やす条件が定義されている。

流量比率と観測ウィンドウは、カナリアの基本パラメータです。5% の流量が 10 分以内にアラートを発火させるなら、新バージョンには深刻な問題があり、すぐにロールバックすべきです。

2.2 サービス指標の監視

HTTP エラー率、レスポンス時間、スループットはカナリアの第一層の指標で、通常のサービスリリースでも見ます。ただし、この層だけを見ると、エージェント固有の失敗モードを見逃します。

チェックリスト：

• HTTP 5xx エラー率のしきい値が設定されている（推奨：≤1%）。
• レスポンス時間 P95 のしきい値が明確である。
• スループットの前期比変化を監視している。
• CPU/メモリ使用率を監視している。
• ネットワークエラー率を監視している。

サービス指標は第一の防線ですが、それがすべてではありません。エージェントは HTTP 200 を返していても、ツール呼び出しに失敗し、guardrail をすり抜け、コストが急増することがあります。

2.3 エージェント指標の監視

エージェント固有の指標は、カナリアの第二層です。通常のサービス監視ではほぼカバーされません。これらの指標は trace の中にあり、HTTP log には出ません。

チェックリスト：

Vultr - 高性能NVMeクラウドサーバー、世界32拠点、Dockerワンクリック展開対応

価格を見る →広告

• tool failure rate をツール別に監視している。
• guardrail trip rate を種類別に監視している。
• cost per run を前期比で監視している。
• HITL キュー長をリアルタイムで監視している。
• eval drift を必要に応じて監視している。

エージェント指標監視の要件は、平均値だけを見ず、ツール別、種類別に分けて見ることです。

2.4 アラート条件と自動ロールバック

カナリアは自動でロールバックできる必要があります。人が画面を見続ける運用だけに頼ってはいけません。AWS のドキュメントでは、CloudWatch alarms で自動ロールバックを起動し、明確なトリガー条件とロールバック経路を定義することを推奨しています。

チェックリスト：

• 自動ロールバックのトリガー条件が定義されている。
• ロールバック後の流量切り替え経路が明確である。
• ロールバック後の観測ウィンドウが設定されている。
• 人間の確認とエスカレーションフローが定義されている。

自動ロールバックの要件は、トリガー条件が明確で、ロールバック経路が明確で、必要な人間確認があることです。

3. リリース後の継続監視：本番準備は投入時点で終わらない

カナリアが通っても、本番準備が完了したわけではありません。リリース後も trace 品質、コスト使用、guardrails の効果、eval 回帰を継続監視し、能力低下やコスト急増を防ぎます。

3.1 Trace 品質の監視

リリース後、trace が欠落したり、遅延したり、フィールドが抜けたりすることがあります。これは事故復盤とデバッグ能力に影響します。trace 品質監視は、サービス指標監視とは別に設計します。

チェックリスト：

• trace の完全性を監視し、run ID の関連付け率が基準値を下回ったらアラートを出す。
• trace 遅延を監視し、書き込みから検索可能になるまでの時間がしきい値を超えたらアラートを出す。
• trace sampling rate が設定され、高流量時には downsampling でストレージコストを抑える。
• trace storage cost を監視している。

Trace 品質監視の要件は、完全性に基準値があり、遅延にしきい値があり、コストに予算があることです。

3.2 Cost と Usage の継続監視

コスト急増は、エージェントで最もよく起きる本番事故の 1 つです。token 使用の異常、モデルの誤用、ツール呼び出し頻度の急増は、どれもコスト爆発につながります。OpenAI は usage tracking と notification threshold の設定を推奨しています。

チェックリスト：

• 日次 cost のトレンドを監視し、前日比と前年比で異常を見つけられる。
• token 使用量をモデル別、ユーザー別に監視している。
• 高コストのツールを特定している。
• cost 予算の消費速度を監視している。
• 予算超過時の自動 circuit breaker が設定されている。

Cost 監視の要件は、トレンドに比較軸があり、モデル別に分類され、予算に circuit breaker があることです。

3.3 Guardrails の継続監視

guardrail のブロック率の変化は、攻撃または誤検知を示すことがあります。input guardrail のブロック率上昇は悪意ある prompt の増加かもしれません。output guardrail の誤検知率上昇は、ルールが厳しすぎる可能性があります。

チェックリスト：

• input guardrail のブロック率トレンドを監視している。
• output guardrail の false positive rate を監視している。
• guardrail false positive/negative のフィードバック収集が整っている。
• guardrails ルールを定期的に評価している。

Guardrails 監視の要件は、ブロック率にトレンドがあり、誤検知にフィードバックがあり、ルール更新の仕組みがあることです。

3.4 Eval の継続回帰

リリース後も、能力が低下していないことを継続的に検証します。毎日または毎週 regression suite を実行し、失敗ケースで自動アラートを出し、新しい失敗ケースを suite に追加します。

チェックリスト：

• 毎日または毎週の regression suite 実行が自動化されている。
• 失敗ケースが自動でアラートされる。
• 新しい失敗ケースを suite に追加している。
• regression suite のバージョン管理が整っている。

Eval 回帰の要件は、定期実行、失敗アラート、ケースの回灌です。

4. インシデント時のロールバック：難しいのはツールの副作用

エージェントのロールバックは、通常のサービスより複雑です。通常のサービスならコードバージョンを戻せば足りることが多いですが、エージェントではすでに実行されたツール副作用、途中まで進んだ workflow、人間の承認キュー内のタスクも扱う必要があります。

4.1 コードロールバック

コードロールバックは最も単純なロールバック方法です。Kubernetes Deployment は rolling update と rollback をサポートしますが、ロールバックウィンドウは 5 分以内に抑えます。

チェックリスト：

• コードバージョンのロールバック経路が明確である。
• ロールバック後の流量切り替えを検証済みである。
• ロールバック後の検証（smoke test）を実行する。
• ロールバックウィンドウが設定されている（推奨：≤5 分）。

コードロールバックの要件は、経路が明確で、切り替えを検証し、時間枠を制限することです。

4.2 ツール副作用のロールバック

エージェントのロールバックで最も難しいのは、すでに実行されたツール副作用です。メール送信、注文作成、外部 API 呼び出しは、コードを戻しても取り消されません。冪等な操作と非冪等な操作を分け、補償アクションを設計します。

Railway - モダンなデプロイプラットフォーム、煩わしい運用から解放、数分で公開

今すぐ始める →広告

チェックリスト：

• 実行済みのツール操作を特定し、trace からすべての実行済み tool call を見つけられる。
• 冪等な操作は安全に再実行できる。
• 非冪等な操作には補償アクションがある。訂正メールの送信、注文キャンセル、取り消し API の呼び出しなど。
• 途中まで進んだタスクのクリーンアップ方針が明確である。
• 人間によるフォールバック手順が定義されている。

ツール副作用ロールバックの要件は、実行済み操作を特定し、冪等性を判断し、補償アクションを設計することです。

4.3 HITL キューのクリーンアップ

ロールバック時、人間の承認キューには途中まで進んだタスクが残ることがあります。新バージョンのエージェントがタスクを HITL に昇格させ、旧バージョンでは人間承認が不要な場合もあります。キュー内のタスクは再割り当てまたは巻き戻しが必要です。

チェックリスト：

• キュー内タスクをバージョンラベルで識別できる。
• タスクの再割り当て方針が明確である。
• 承認タイムアウト時の処理が定義されている。
• 人間の確認フローが整っている。

HITL キューのクリーンアップ要件は、バージョンで識別でき、再割り当て方針があり、タイムアウト処理があることです。

4.4 Trace と Audit ログの保持

事故後の復盤には、完全な trace と監査ログが必要です。OpenTelemetry は logs を telemetry signals の 1 つとして扱い、既存の logging frameworks と統合できます。

チェックリスト：

• trace の保持期間が明確である（推奨：30〜90 日）。
• 監査ログの保持期間が明確である（推奨：1 年）。
• 機密データのマスキングルールが整っている。
• 業界ごとのコンプライアンス要件を満たしている。

Trace と Audit の保持要件は、保持期間が用途に合い、マスキングルールが整い、コンプライアンスを満たすことです。

4.5 失敗サンプルを Eval Suite に戻す

事故後は、失敗サンプルを regression suite に追加し、同じ種類の事故を繰り返さないようにします。サンプル抽出では trace から失敗 case を見つけ、人間が失敗理由と期待動作をラベル付けします。

チェックリスト：

• 失敗サンプルを抽出するツールまたはスクリプトがある。
• サンプルラベル付けに人間の確認がある。
• regression suite に追加するプロセスがある。
• 同じ種類の事故を再発させない仕組みがある。

失敗サンプルの回灌要件は、抽出ツール、人間のラベル付け、suite 追加プロセス、修正の検証です。

結論

エージェントの本番投入では、通常の Web サービスより 8 つ多い観点を見ます。trace、tool calls、guardrails、HITL、eval、cost、secrets、checkpoint です。この 8 つは 4 つのチェックリストに整理できます。

リリース前ゲート（10 個のチェック）：Trace 完全性、機密データのマスキング、Guardrails 監視、Tool Calls 可観測性、HITL キュー準備、Eval Regression Suite、Cost Budget と Rate Limit、Secrets 分離と監査、Checkpoint 復旧検証、Feature Flag と Kill Switch。リリース前に 1 つずつ確認し、通らないものは本番投入を止めます。

カナリア観測（4 個のチェック）：流量比率と観測ウィンドウ、サービス指標監視、エージェント指標監視、アラート条件と自動ロールバック。カナリアでは HTTP エラー率だけでなく、tool failure rate、guardrail trip rate、cost per run、HITL queue length も見ます。

リリース後監視（4 個のチェック）：Trace 品質監視、Cost と Usage の継続監視、Guardrails 継続監視、Eval 継続回帰。カナリアが通っても終わりではありません。能力低下やコスト急増を防ぐため、継続監視が必要です。

インシデント時ロールバック（5 個のチェック）：コードロールバック、ツール副作用ロールバック、HITL キュークリーンアップ、Trace と Audit ログ保持、失敗サンプルの Eval Suite 回灌。ロールバックはコードバージョンを戻すだけではありません。実行済みツール副作用、途中 workflow、人間の承認キューも処理します。

この 4 つのチェックリストをテンプレートとして保存し、各リリース前に順番に確認してください。どこかが通らないなら、既知の問題を抱えたままカナリアへ進むのではなく、先に直してから本番へ出しましょう。