エージェントの副作用に対する自動ロールバック

エージェントのロールバックで復元できるのは、コード、設定、選択したアプリケーションデータです。他組織に依頼を忘れさせること、受信トレイから配信済みメールを引き戻すこと、カード請求が決済代行会社に届かなかったことにすることはできません。これらすべてを「ロールバック」と呼ぶチームは、結果が重要になるまさにその場面で機能しない、安心感だけを与える仕組みを作ってしまいます。

安全な設計では、アプリケーションのスナップショット、Git revert、データベース復旧、補償アクションという4つの仕組みを分けます。それぞれの対象範囲は異なります。アプリケーションの境界を越える操作には、エージェントが実行する前に、個別の承認、証跡、再試行ルール、復旧経路が必要です。誰もその経路を一文で説明できないなら、その操作を無人実行に任せる準備はできていません。

ロールバックには4つの異なる意味がある

ロールバックが役立つのは、チームが復元する状態と手を触れられない状態を明確にしたときだけです。この言葉には、保証内容が大きく異なる4つの仕組みが隠れていることが多いのです。

スナップショットは、取得時点のアプリケーションまたはワークスペースのバージョンを復元します。製品によっては、生成されたコード、設定、選択された管理対象の状態が含まれます。スナップショットの契約に明記されていない限り、外部サービスについては何も保証しません。

Git revertは、以前のコミットによる変更を逆転させる新しいコミットを記録します。履歴を削除せずにソース履歴を修復します。古いコードが実行中に呼び出したサービスへ連絡することはありません。

データベース復旧は、データベースが保持するレコードを変更します。トランザクションのロールバックでは、1つのトランザクション内で未コミットの書き込みを破棄します。バックアップの復元やポイントインタイムリカバリは、データベースクラスタを過去の状態に近づける、はるかに大きな操作です。どちらも、そのデータベースの外部にあるシステムと自動的に整合するわけではありません。

補償アクションは、以前の影響を相殺する意図で新たな影響を作ります。返金は、確定した支払いを補償します。キャンセル依頼は、注文を補償します。訂正メールは誤ったメールの影響を和らげられるかもしれませんが、最初のメッセージを消すことはできません。補償は、元の操作が起きたという不都合な事実を残します。

設計レビューでは、正確な答えを引き出せるため、影響の責任分担表を使っています。

最終列が最も重要です。逆操作があることは、元の影響が消えた証拠にはなりません。監査記録、受信者のコピー、決済記録、Webhook、物理的な作業は残る場合があります。

コードのrevertはプログラムを変えるだけで、過去は変えない

コードのrevertは今後の動作を止めたり変えたりしますが、古いバージョンがすでに引き起こした動作を元に戻すことはありません。チームがGit、プラットフォームのスナップショット、デプロイのロールバックのどれを使っても同じです。

Gitのドキュメントでは、git revertは以前のコミットで導入された変更を逆転させるコミットを記録するものと説明されています。この表現は正確です。Gitはリポジトリの内容に逆パッチを適用します。revertしたコミットが実行されたときに作られたメール、支払い、クラウドリソース、サポートチケット、パートナーAPIについて、Gitは何も知りません。

たとえば、エージェントが請求関数を変更してデプロイし、監視で不具合を検知する前に2回呼び出したとします。コミットをrevertすれば、不正な関数が再び動くことは止められます。しかし、決済代行会社には2回の支払い試行が残ります。ローカルデータベースに1回分しか記録されていなければ、revertによって2回目の応答を処理していたコード経路まで失われ、調査がさらに難しくなることさえあります。

デプロイのロールバックにも同じ境界があります。トラフィックを以前のビルドに戻すと、実行可能な動作は復元されます。置き換えられたビルドがすでに受け付けたリクエストの結果は残ります。キュー内のジョブもデプロイ後に残り、復元したバージョンに対して古い前提のまま実行される場合があります。

revertする前に、古いビルドが生んだ運用上の証跡を保全してください。

• デプロイ識別子とソースコミット
• エージェント実行IDと意図ID
• キューメッセージIDとリース状態
• 外部リクエストID
• プロバイダーの応答とタイムスタンプ

その後、新しい実行を止め、不完全な操作を照合してから、コードを復元します。先にrevertして後から調べると、どの影響が外に出たのかを理解する最も簡単な手がかりを失いがちです。

スナップショットはGitコミットより広い範囲を含むことがありますが、同じ原則が当てはまります。スナップショットの契約には、含まれるリソースを正確に記載しなければなりません。コードと設定が対象なら、コードと設定の復旧機構と呼んでください。画面上の希望的な表現で、万能の取り消し機能に見せかけてはいけません。

データベース復旧の役割は、多くの人が思うより狭い

データベース復旧が戻すのはデータベースの状態であり、トランザクションの参加者すべてにまたがる業務上の現実ではありません。1つのデータベース内ではトランザクションを原子的に扱えても、周囲の処理は複数システムに分かれたままです。

次の流れを考えてみましょう。

1. エージェントが請求書行を追加する。
2. 決済APIを呼び出す。
3. 決済代行会社が請求を受理する。
4. データベースのコミットが失敗する。

ローカルのロールバックでは請求書行が消えますが、請求自体は残ります。照合せずに処理全体を再試行すると、顧客に再度請求する可能性があります。これは典型的な二重書き込み障害です。アプリケーションが、トランザクションコーディネーターを共有しないシステム間で、1つの業務操作を原子的に実行しようとしたのです。

順序を逆にしても解決しません。先に請求書をコミットし、その後に決済呼び出しが失敗すれば、データベースには未払いの請求書が残ります。この状態のほうが調査はしやすいものの、アプリケーションにはpayment_pending、payment_confirmed、payment_failed、payment_unknownを区別する状態機械が依然として必要です。

PostgreSQLのドキュメントでは、ポイントインタイムリカバリを、ベースバックアップを復元し、選択した復旧時点までWALレコードを再生するものと説明しています。これはデータベースクラスタを復旧するための運用手順です。あるエージェント実行だけを選んで取り消す仕組みではなく、決済代行会社やメールサービスに同じ時刻へ戻るよう依頼することもできません。

データベースを過去へ戻すと、別の不整合が生まれる場合があります。障害後に10:00へ復元するとします。プロバイダーは10:07までリクエストを受理していましたが、復元されたデータベースにはその記録が残っていません。「存在しない」行を見たエージェントは、7分間分の作業をすべて作り直すかもしれません。そのため、ワーカーを再開する前に外部照合の段階が必要です。

アウトボックスパターンは、危険な空白を1つ減らします。アプリケーションは業務上の変更と、影響を与える意図を同じローカルトランザクションでコミットします。

BEGIN;

INSERT INTO invoices (invoice_id, customer_id, status)
VALUES ('inv_2048', 'cust_91', 'payment_pending');

INSERT INTO effect_intents
  (intent_id, operation, subject_id, status)
VALUES
  ('eff_7f31', 'capture_payment', 'inv_2048', 'pending');

COMMIT;

後からワーカーがeff_7f31を取得し、安定した冪等性値を付けてプロバイダーを呼び出し、結果を記録します。アウトボックスは外部呼び出しを原子的にはしません。作業が意図されていたという永続的な証跡をシステムに残すため、再試行と照合が可能になります。

外部アクションには補償が必要で、補償できないものもある

外部への副作用には、プロバイダー固有の補償か、意味のある補償がないという明示的な記述が必要です。すべての操作を元に戻せるものとして扱うより、承認が必要な操作があると認めるほうが安全です。

メールは最もわかりやすい例です。プロバイダーがメッセージを受理する前なら、アプリケーションはキュー済みジョブをキャンセルできます。受理後、プロバイダーが短い内部処理段階でキャンセルを認めることはあるかもしれませんが、受信者やメールシステムをまたぐ一般的な取り消し保証はありません。配信後に2通目のメッセージで記録を訂正することはできても、最初のメッセージは消えません。機密データ、法的通知、評判への損害は、すでに露出したままです。

支払いには、チームが「請求済み」とひとまとめにしがちな複数の状態があります。オーソリは利用可能な支払い枠を確保します。キャプチャは、そのオーソリに対して資金移動を要求します。無効化は、まだ決済されていないオーソリを解除する場合があります。返金は、キャプチャ後にお金を戻す後続の金融記録を作ります。これらの操作は、タイミング、手数料、権限、顧客への影響が異なります。汎用的なundo_paymentツールでは、エージェントが安全に動くために必要な情報が隠れてしまいます。

他のAPIはさらに協力的ではありません。リクエストは在庫の発注、インフラのプロビジョニング、コンテンツ公開、アクセス付与、荷物発送、人による作業開始を引き起こすことがあります。DELETEエンドポイントがあるからといって、元に戻せるとは限りません。リソースを削除しても、監査ログ、複製されたデータ、通知、依存リソース、物理的な結果が残ることがあります。

補償は、正直に達成できることに基づいて分類します。

• 完全なローカル逆操作は、管理下の状態を以前の値に戻す。
• プロバイダーによるキャンセルは、完了していない作業を止める。
• 金銭的な補償は、返金またはクレジットを作る。
• 訂正の連絡は、最初のメッセージが見え続けることを認める。
• 手作業による是正は、安全な自動ルールに収まらない文脈を伴う影響に対応する。

補償自体も失敗する可能性があります。返金エンドポイントがタイムアウトするかもしれません。キャンセル可能な時間が過ぎるかもしれません。受信者アドレスが訂正を拒否するかもしれません。エージェントが使うアカウントに権限がないかもしれません。そのため、システムは補償も、意図ID、状態、試行回数、証跡、承認ポリシーを持つ別の操作として追跡しなければなりません。

「ロールバックをロールバックする」機能を再帰的に作らないでください。履歴はアクションの台帳として扱います。補償が新たなエラーを引き起こしたら、現在の状態を確認してから、別の明示的なアクションを実行します。履歴は長くなりますが、インシデント時にも理解し続けられます。

冪等性は重複を防ぐが、成功を取り消さない

冪等性は、再試行によって意図した影響が重複するのを防ぎます。最初に成功した影響を元に戻すものではありません。チームはこの2つを日常的に混同し、タイムアウトの後に違いを知ることになります。

RFC 9110では、同一リクエストを複数回行っても意図した効果が1回のリクエストと同じであるメソッドを冪等と定義しています。プロトコル上の意味論では、PUT、DELETE、安全なメソッドを冪等として挙げています。POSTは一般に冪等ではありませんが、APIが独自の契約で冪等性を追加することはできます。

この限定は重要です。冪等なDELETEでも、実行ごとに新しいログ、メトリクス、応答が生成されることがあります。プロバイダーの冪等性実装では、記録が期限切れになる、識別子の範囲が1つのアカウントに限られる、変更されたパラメーターを拒否する、選択した結果だけをキャッシュするといったこともあります。HTTP動詞から保証を推測せず、プロバイダーの契約を読んでください。

すべての影響の意図には、最初の試行前に1つの安定した冪等性値を与えるべきです。同じ意図の再試行ではその値を再利用します。新しい業務上の意図には新しい値を使います。顧客、金額、日付のような変更可能なパラメーターだけから導出してはいけません。同じ値を持つ正当な購入が2件あり得るためです。

タイムアウトは失敗ではなく、結果不明です。次の手順を使います。

1. 試行をoutcome_unknownとして記録し、代替の意図を作らない。
2. 冪等性値または操作参照を使ってプロバイダーに照会する。
3. プロバイダーが成功を確認したら、その成功をローカルに記録する。
4. 操作がなかったと確認したら、同じ値で再試行する。
5. 回答できない場合は、照合または人によるレビューのために操作を保留する。

次の応答形式なら、エージェントは受理と通信上の不確実性を区別できます。

{
  "intent_id": "eff_7f31",
  "attempt": 2,
  "idempotency_key": "eff_7f31",
  "transport_status": "timeout",
  "provider_status": "unknown",
  "provider_reference": null,
  "next_action": "reconcile"
}

冪等性値は、対応している場合、ログ、キューメッセージ、APIヘッダー、プロバイダーのメタデータまで渡すべきです。運用者が境界の両側でその値を検索できなければ、復旧時に推測することになります。

承認は影響の境界で行う

承認は、エージェントが正確な外部アクションを組み立てた後、最初の取り返しのつかないリクエストがシステムを出る前に行わなければなりません。広範なタスクの開始時点で承認すると、その後エージェントが受信者、金額、対象範囲、ツールを変える余地が大きすぎます。

「この顧客のアカウントを処理する」は、カードへの請求や全ユーザーへのメール送信を承認するには不十分です。有効な承認には、受信者、金額と通貨、メッセージまたはペイロードのダイジェスト、対象アカウント、ツール、有効期限、許可される試行回数といった具体的な操作を記載します。承認済みの項目が1つでも変われば、承認は一致しません。

有用なポリシーは、どのエージェントやモデルが要求したかではなく、結果に応じて影響を分類します。読み取りアクセスでも私的データが露出することはありますが、外向きの操作と同じ復旧問題を生むわけではありません。メールの下書きはローカルで、元に戻せます。送信は境界を越えます。支払い提案の作成はローカルです。資金のキャプチャは境界を越えます。

次のような操作には明示的な承認を求めます。

• 資金を動かす、または金銭的な義務を生む
• 個人または外部組織へ情報を送る
• 管理下のストレージ外でデータを公開、削除、開示する
• アイデンティティ、アクセス、所有権、セキュリティ設定を変更する
• 物理的な作業や、確実に取り消せない別のプロセスを開始する

影響が小さく繰り返される操作には、範囲を限定した継続承認を使えます。上限額、受信者集合、許可ツール、有効期限、レート、操作総数をその範囲に明記してください。「請求を承認済み」では、強制可能な境界がありません。

承認にはリプレイへの保護も必要です。不変の操作ダイジェストに結び付け、ポリシーで1回だけの実行を許可する場合は、使用済みと記録します。実行の結果が不明になったとき、新しい承認を求めて2つ目の意図を作ってはいけません。まず承認済みの意図を照合します。

承認画面では、復旧の事実をわかりやすい言葉で示すべきです。「このメッセージは配信後に取り消せません」は有用です。実際の復旧が、時間がかかり金融明細にも残る返金であるのに、「この操作は元に戻せます」と表示するのは誤解を招きます。

ツール契約では影響のライフサイクル全体を表す

エージェントのツール契約では、意図、実行、観測、補償を別々の操作として記述すべきです。影響を与える1つの関数がsuccess: trueを返すだけでは、再試行、承認、インシデント対応に必要な証跡が足りません。

次のポリシー断片は、強制できるほど小さく、レビューできるほど具体的です。

tools:
  send_email:
    effect: irreversible
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_message_id
    compensation: null

  capture_payment:
    effect: compensatable
    approval: required
    idempotency_field: intent_id
    evidence_field: provider_payment_id
    compensation: refund_payment

  update_draft:
    effect: local_reversible
    approval: none
    compensation: restore_version

effectは、どの復旧クラスが適用されるかをプランナーに伝えます。approvalは、正確な引数が認可されるまで実行を止めます。冪等性フィールドは、再試行で1つの識別子を再利用させます。証跡フィールドは、運用者が何を残す必要があるかを示します。補償フィールドは、元の呼び出しを逆再生できるかのように装うのではなく、別のツールを指します。

実行は不変のエンベロープを受け取るべきです。

{
  "intent_id": "eff_7f31",
  "operation": "capture_payment",
  "arguments": {
    "invoice_id": "inv_2048",
    "amount_minor": 12900,
    "currency": "USD"
  },
  "approval": {
    "approval_id": "apr_662",
    "scope_hash": "sha256:8b4f...",
    "expires_at": "2026-07-27T18:00:00Z"
  }
}

実行担当は操作ダイジェストを計算し、scope_hashと比較し、有効期限を確認し、意図を確保してから初めてプロバイダーに連絡します。呼び出し前にリクエストのメタデータを保存し、後で応答を保存します。この2回の書き込みの間にクラッシュしても、永続化された意図は照合に使えます。

実行担当は、引数の変更、期限切れの承認、別の操作への意図の再利用、成功が確認されていない影響を補償しようとする試みという4つの条件を、即興で処理せず拒否すべきです。エージェントはもっともらしい続きの手順を見つけるのが得意です。金銭と通信の制御では、もっともらしい推測より明確な停止を優先しなければなりません。

get_payment_status(intent_id)のように、観測にも専用ツールを用意します。観測は影響を作るべきではありません。分けておけば、エージェントは元の操作を再試行する権限を得ずに、曖昧な結果を解消できます。

1回の失敗した実行が、すべての復旧境界をまたぐことがある

1回のエージェント実行でも、コード、データベースレコード、外部システムがそれぞれ異なる時点に残されることがあります。リリース前にこの障害を追ってみると、汎用的なロールバック機能では隠れる穴が見えてきます。

エージェントが会員制アプリケーションを構築し、変更をデプロイし、顧客リストをインポートし、年会費を請求し、ウェルカムメールを送るとします。タスクは一体に見えますが、少なくとも4つの復旧境界をまたぎます。

14:00、エージェントは誤った列から年会費を計算するコードをデプロイします。14:02、データベースに40件の支払い意図とメール下書きを書き込みます。14:03、ワーカーがいくつかの支払いをキャプチャします。14:04、メールプロバイダーが誤った料金を含むウェルカムメッセージを受理します。14:05、監視がワーカーを停止します。一部の決済呼び出しは決済代行会社に届いた後にタイムアウトしているため、ローカル状態では成功したかどうかわかりません。

13:59のコードスナップショットを復元すると、今後の実行で誤った計算は止まります。Gitコミットのrevertもソース修正を記録しますが、同じ限界があります。

データベースを13:59に復元すると、プロバイダー参照と冪等性値を持つローカルの意図レコードが消えてしまいます。外部との不整合はさらに悪化します。より良いデータベース操作は論理的な訂正です。意図を残し、結果不明の操作に照合が必要であると印を付け、プロバイダーの状態と照合してから行だけを訂正します。

対応チームは次に、影響のクラスごとに進めます。安定した操作識別子を使って、結果不明の支払いをすべて照会します。確認済みのキャプチャは返金レビューへ進め、失敗した試行は再試行せずに終了し、未解決の試行はブロックしたままにします。配信済みメールには慎重に承認した訂正を送ります。プロバイダーに届いていないキュー済みメッセージはキャンセルします。各補償には、元の意図に紐付く新しい意図を与えます。

この例は、自動補償が危険になり得る理由も示しています。システムがローカルのpayment_unknownレコードすべてを即座に返金すると、存在しない請求に返金したり、誤った参照で返金エンドポイントを呼び出したりするかもしれません。データベース復旧後に存在しないメールをすべて再送すれば、受信者に重複メールが届く可能性があります。ローカルとプロバイダーの状態が食い違うときは、補償より先に照合しなければなりません。

すべての意図がsucceeded、confirmed_failed、compensated、manual_exceptionなどの終端状態に達したとき、実行は完了します。「アプリケーションをロールバックした」は、インシデントの最初の部分しか説明していません。

証跡が残って初めて復旧できる

ロールバックによって何が起きたかを判断するためのレコードまで削除されると、復旧制御は失敗します。通常のスナップショットや復元で置き換わらないアプリケーション状態の外部に、追記専用の影響台帳を保存し、各操作を照合できるだけのプロバイダー証跡を保持してください。

台帳には、意図の作成、引数ダイジェスト、承認、実行リース、試行、通信結果、プロバイダー参照、観測したプロバイダー状態、補償リンクを記録します。エージェントが古いエントリを上書きできるようにせず、状態遷移だけに変更を制限してください。訂正では履歴を編集せず、イベントを追加します。

明示的なエラーだけでなく、未解決状態も監視します。10分間残ったoutcome_unknownは、運用者が手動で再試行してしまう可能性があるため、明確な拒否より危険なことがあります。実行中に承認が期限切れになった場合、冪等性値が異なる引数ダイジェストとともに現れた場合、補償が失敗した場合にもアラートを出してください。

意図的に厄介な障害点を作って復旧訓練をします。プロバイダーがリクエストを受理した後、ローカルで成功を書き込む前にワーカーを終了させます。影響台帳を残したまま、アプリケーションデータを以前のスナップショットから復元します。計画と実行の間で承認を期限切れにします。観測APIを利用できなくします。システムが停止し、照合し、影響を重複させずに未解決の判断を示せれば、訓練は合格です。

Koder.aiを使う場合は、そのスナップショットとロールバックをアプリケーション復旧層として扱い、データベース履歴と、アプリケーションが引き起こし得る外部アクションごとに別の制御を設計してください。ソースのエクスポート、デプロイ制御、ロールバックはソフトウェアの復元に役立ちます。一方、アプリケーションのツール契約は、承認と補償を引き続き担います。

ロールバックボタンには、その横に境界を明記すべきです。コード、設定、管理対象データ、外部への影響のどれなのかを示します。画面がその一文を正確にできないなら、ロールバックを約束すべきではありません。正直な制御は魔法のようには見えないかもしれませんが、午前2時のインシデント対応チームに必要なもの、つまり何が変わり、何が外に出て、次にどの操作が安全かを信頼できる形で示してくれます。