AIエージェントの障害復旧では、失敗した手順を停止、再試行、照合、承認待ち、補償、checkpointからの再開のどれで処理するか決めます。この判断はerror classと、外部への効果がすでに完了した可能性に依存します。
自動再試行が安全なのは、操作契約によって反復が安全になる場合だけです。タイムアウトは失敗を証明しません。
対応する前に失敗を分類する
| 失敗 | デフォルトの対応 |
|---|---|
| 不正な入力またはschema | 停止し、リクエストを修正 |
| 認証または認可 | 停止し、有効なアクセスを要求 |
| ポリシー拒否 | 停止するか、指定された承認を要求 |
| 再試行時刻付きrate limit | 待機し、操作予算内で再試行 |
| 一時的な読み取り失敗 | 制限付きbackoffで再試行 |
| 結果不明の書き込みtimeout | 再試行前に照合 |
| 永続的なprovider障害 | 失敗にするか、文書化済みの代替経路を使用 |
| worker crash | 永続状態から再開 |
| 複数systemの部分完了 | policyに従い、続行、補償、escalate |
ツールから安定したerror codeを公開します。「問題が発生しました」のような文章から再試行の安全性をモデルへ推測させてはいけません。
一つの論理書き込みに一つのoperation IDを与える
重大な呼び出しの前に操作記録を作成します。action、tenant、resource、正規化済みinput hash、idempotency key、state、attempt、provider reference、resultを保存します。
論理的効果のすべての再試行で同じ冪等性キーを再利用します。異なるparameterでの再利用を拒否します。Stripeの冪等なリクエストのドキュメントは、同じキーに保存済み結果を返すserver-side契約を示しています。保持ルールはprovider固有なので、想定する最長の再開経路から保持期間を決めます。
providerが冪等性に対応していない場合、operation tableにより二つのlocal workerが同じactionを意図的に開始することを防げます。ただし、providerが処理した後に失われたresponseを確定することはできません。provider lookup、webhook、人間による照合手順を追加します。
検証済みの進捗をcheckpointする
モデルが実行したと言った後ではなく、システムが外部への効果を検証した後にcheckpointします。provider identifierまたはoperation referenceを保存します。再開時は、モデルを再度呼び出す前にcheckpointと正式なbackend stateを読み込みます。
永続実行ガイドでは、workflow history、deterministic replay、永続化した待機を説明しています。障害復旧では各状態に対する運用上の選択を加えます。
再試行の責任箇所を一つにする
HTTP client、queue、workflow engine、model SDK、tool、providerがすべて再試行する場合があります。各error classに一つの責任箇所を選び、すべての試行を同じoperationとして数えます。
最大試行回数、経過時間、backoff、最終結果を設定します。検証、認可、ポリシーの失敗では停止します。モデル呼び出しでは、再試行が同じpromptとtoolを使うか、新しいdecisionを作るか決めます。評価が変わるため、この違いを記録します。
結果不明を照合する
書き込みがtimeoutした場合：
- 操作を
unknownではなくfailedにする。 - idempotency key、provider reference、期待するbusiness stateでqueryする。
- 効果が存在すればcompletedにする。
- providerが発生していないと確認した場合だけ再試行する。
- どちらも確定できない場合は人間のレビューを求める。
結果不明状態を成功メッセージで隠さないでください。照合中にユーザーがリクエストを繰り返さないよう案内が必要な場合があります。
影響の大きい試行の前に承認を置く
承認をaction、resource、parameter、actor、expiryへ紐づけます。実行再開時に認可を再確認します。「続行」のような広い承認で、変更された支払いまたは削除parameterを対象にしてはいけません。
Railwayはエージェントによる削除インシデントを受け、APIの削除を48時間のsoft-delete期間に揃えました。復元可能な効果は復旧の負担を減らしますが、スコープ付きIDと監査記録は引き続き必要です。
キャンセルと補償を分ける
キャンセルは以後の作業を止めます。完了済みのメール、支払い、外部公開を元には戻せません。補償は請求書の無効化やsoft-delete済みリソースの復元など、別のアクションです。
補償にも個別の認可、冪等性、操作記録、失敗経路が必要です。複数の外部systemに共通transactionがない場合、automatic rollbackと表現しないでください。
人間が実行できるrunbookを書く
影響の大きいワークフローごとに次を文書化します。
- 新しい実行とactive workerを停止する方法
- 取り消す認証情報
- 対象のtaskとoperationを見つける方法
- 結果不明を分類する方法
- 安全な再試行
- 補償できる効果
- 復旧を誰が承認し、完了をどう検証するか
runbookをtraceとoperation queryへlinkします。オブザーバビリティガイドに、インシデントを最初から最後まで追跡するための識別子があります。
手順の間で障害を実践する
呼び出し前、provider受信後、成功後かつresponse到着前、checkpoint後、承認中、キャンセル中に障害を注入します。local stateのない新しいworkerで再開し、効果の件数と最終的なbusiness stateを検証します。
以下のプロンプトは本番環境に触れず、最も有用な訓練を設計します。runbookが「失敗」と「成功した可能性がある」を区別できなければ、自律性を高める前にその分岐を修正してください。