信頼できるAgent操作:タイムアウト・再試行・復旧
ECの返金処理を承認から結果照合まで追い、永続状態、冪等性、再試行予算を体系的に学びます。確認応答の消失と再起動をローカル実装で検証します。
出典とバージョン
この記事の目次
1. 待機を諦めた後でも返金は成功している
注文7の25ドル返金をモデルが提案し、ポリシーが承認し、決済側が受理します。しかし成功を保存する前に応答が消失します。単純なAgentは失敗と判断し、別の返金を発行します。モデルの推論がどちらも正しくても、実行境界で業務エラーが起きます。目的は会話上の成功ではなく、不確実な通信を通して一つの承認済み意図を維持することです。
副作用は外部状態を変える操作、確認応答は呼び出し元に届く証拠です。応答がないことは効果がない証明ではありません。冪等性は同じ識別済み意図を繰り返しても効果を追加しない契約、永続性は指定した故障モデルで状態が残る性質です。永続ログにも重複支払いは記録できます。前提はトランザクション、要求・応答、権限制御です。ローカルDBのトランザクションは遠隔HTTP呼び出しを自動では含みません。
対象はチケット作成、在庫確保、承認済み返金を行うAgentです。読み取り検索には鮮度と予算が必要ですが、通常は決済のような効果照合は不要です。不可逆で冪等性も状態照会もない操作は人手または統合設計の変更が必要です。図は独自の参考設計、プログラムは二つのローカルDBを使い、実決済やモデルAPIは呼びません。
2. 計画の権限と実行の権限を分ける
計画器はツール名と引数を提案します。決定的なゲートがスキーマ、テナント、注文所有者、金額、承認期限を確認します。承認前に金額を整数の最小通貨単位へ正規化します。2500セントは25ドルですが、実システムでは通貨も記録します。承認は操作ID、正規化引数のダイジェスト、ポリシー版に結びます。金額変更は新しい意図で再承認が必要、同じ意図の再試行ではIDを保ちます。
実行器は送信前に意図を永続化します。効果の権威ある記録は提供側が持ちます。照合器は提供側を読み、検証済み証拠だけでローカル状態を進めます。画面は保留、確認済み、不明、拒否を区別します。ツール出力は次の購入の権限を与えません。新規の変更要求は権限を再確認し、既存操作の状態照会には別の読み取り権限を使います。
ローカルDBと遠隔提供側のトランザクションは独立し、間にネットワークがあります。Outboxはローカルの意図と送信予定を同時に保存し、少なくとも一回の配信を支援しますが、遠隔効果を同じ原子境界には入れません。変更要求は必ず実行ゲートを通し、照合経路は状態を読み記録するだけで、隠れた補償を発行しません。
3. 不確実性を状態として扱う
送信前にPREPAREDを保存します。SUBMITTEDは要求が外に出た可能性であり、受理の証明ではありません。意図と一致する確認からSUCCEEDEDへ進みます。応答消失や送信後のクラッシュはUNKNOWN、または照合を要するSUBMITTEDとして残ります。REJECTEDには確定的拒否が必要です。「見つからない」結果も可視性遅延や飛行中の要求を考慮します。同じキーの再送が安全なのは明示的な冪等契約がある場合です。
故障窓は三つです。意図のコミット前は送信禁止。コミット後・送信前なら同じ操作を再開できます。提供側コミット後・ローカル成功記録前なら提供側に問い合わせるか同じ重複排除操作を再送します。再試行ごとにUUIDを作ると最後の窓の連続性が失われます。永続的な業務IDからキーを導くか、送信前に独立した永続ステップで生成キーを保存します。
キャンセルは可能な範囲で将来の作業を止めますが、完了済み効果を戻しません。返金とキャンセルが競合したら照合結果を示し、救済は新たな承認操作として扱います。補償は原子ロールバックではありません。LangGraphの現行文書もノード再実行と外部効果を区別し、確認欠落を不明と扱います。実装時はフレームワーク版を固定してください。本例は版依存を避けています。
4. 冪等性の所有者・範囲・保持期限
提供側はテナントと操作IDを一意キーに、意図ダイジェスト、結果、保持規則を保存します。重複排除と効果をそのシステム内で原子的に行う必要があります。クライアントの照会後に無保護で書く方式では、二つのworkerが同時に不存在を見て実行できます。本例は一意制約とトランザクションを使い、実提供側には同等の契約が必要です。
生promptのハッシュやモデル生成tool-call IDだけを業務IDにしないでください。空白でもハッシュは変わり、意図的に二回行う同額返金は別操作でなければなりません。検証済み引数を正規化し、IDとダイジェストを分けます。本例は注文と整数セントだけですが、本番は通貨、口座、操作種別、スキーマ版も含めます。同じキーで異なる引数は履歴上書きではなく競合です。
保持期限は保証の限界です。Stripe API v1は応答再利用、引数不一致検査、少なくとも24時間後のキー削除を説明し、API v2の失敗操作は異なる扱いです。普遍的保証ではありません。復旧期間が重複排除保持を超えるなら自動変更を停止し、永続業務IDで照合します。必要に応じ簡潔な履歴マーカーや業務台帳を残し、キーに機微な個人情報を入れません。
5. 締切と再試行予算で過負荷を防ぐ
Timeoutは一回の待機、deadlineは操作全体を制限します。残りRは締切Dから現在tを引いた時間です。最終記録と返却にF秒を残し、待機bと試行上限Tについてb+T+FがR以下の場合だけ開始します。独自例では30秒中18秒経過、F=2、T=4。8秒の待機は合計14秒で残り12秒に収まらず、2秒の待機は合計8秒で収まります。プロセス内は単調時計、サービス間は制限した残時間を使います。
再試行前に分類します。不正引数、権限拒否、確定的業務拒否は一時的通信障害ではありません。一時的障害には回数上限、ジッター付き指数バックオフ、共有予算、依存先並列数制限を使います。下のfull jitter式ではiはゼロ開始、baseとcapは秒で、その回の上限まで一様分布の遅延を選びます。ジッターは時刻を分散するだけで総試行数を減らしません。
三層が各三回試行すると最悪27回の末端呼び出しになります。再試行の責任者を一つにするか木全体を予算化します。独立失敗確率0.2、最大三回なら期待値は1+0.2+0.04=1.24です。相関した過負荷では独立仮定は成立しません。見積りが崩れても予算は増幅を制限します。gRPCの締切伝播に加え、アプリが起動した仕事もキャンセルに協調する必要があります。
式のb_0は基本遅延、b_maxは上限、iはゼロ開始の再試行番号、Aは試行回数、mは最大回数、pは独立な各試行の失敗確率です。Aとmは個数、pは無次元で、期待値には最初の試行も含みます。
6. 永続実行と可観測性は別の役割
チェックポイントは制御状態、ツール台帳は識別された効果、監査は承認者と根拠、traceは試行・待ち行列・遅延を扱います。互換ではありません。LangGraphはスレッドのチェックポイントとスレッド横断storeを区別します。メモリ上の例はクラッシュ永続性を示しません。再生境界にモデル出力や決定を保存し、同じ承認意図の途中で確率的計画器が別操作を発明しないようにします。
操作ID、テナント、ダイジェスト、承認版、試行ID、締切、遠隔参照、状態遷移、秘匿化したエラー種別を保存します。一つの業務操作には複数のネットワーク試行があり得ます。UNKNOWNの数と経過時間、承認意図当たり効果数、競合率、再試行増幅、照合完了時間を測ります。後で返金成功が確認されたなら通信timeoutを返金失敗と数えません。ログにも個人情報保護と保持制御が必要です。
複数実行器ではleaseによる所有と、対応する宛先ではfencing世代を使います。lease期限切れは旧workerを殺さず、fencingや提供側冪等性がなければまだ実行できます。ローカルmutexを分散排他と呼べません。本コードは単一実行器とトランザクション提供側模型であり、分散lease、地域間切替、実認可サービスは実装しません。
7. 契約を守れる最小の復旧方法を選ぶ
読み取りは締切内で再試行し古さを表示します。冪等変更に状態照会があれば先に照合し、有効な認可で同じキーを再送します。照会がなければ再送による応答復元は保持とエラー契約次第です。非冪等で信頼できる状態もなければ人手調査へ止めます。再試行では欠けた契約を作れません。
長時間ステップ、タイマー、人間承認が多ければworkflow engineが役立ちます。単一の純粋計算には過剰です。Outboxはローカル配信、sagaは業務補償を定義しますが、任意の外部APIをexactly-onceにはしません。返金ではメールから成功を推測したり逆支払いするより、読み取り専用照合器が安全です。
残る問題はキー失効、照合先停止、状態スキーマ移行、遅延コールバック、イベント逆順、複数地域の所有です。意図スキーマを版管理し、終態の証拠を残し、担当者が明確な手動キューを設けます。受け入れ条件は各不確実窓での安全な振る舞いであり、無故障の約束ではありません。以下は限定された検証で、決済統合の認証ではありません。
| 機構 | 保護対象 | 保証しないこと |
|---|---|---|
| チェックポイント | 制御状態 | 外部効果のexactly-once |
| Outbox | ローカル意図と配信記録 | 提供側をまたぐ原子性 |
| 冪等キー | 同じ意図の重複排除 | 無期限保持や認可 |
| 照合 | 遠隔結果の証拠 | 遠隔APIの可用性 |
実践と検証
Python 3.11+標準ライブラリのみ。python3 agent-action-recovery.py を実行します。キー・通信・実効果・乱数はありません。二つの一時SQLiteファイルを使い、重複排除と返金模型だけが提供側の同一トランザクションで確定します。期待値はPASSとeffects=3; duplicate-effects=0。shopの二つの操作と別テナントの一つです。応答消失、再オープン、引数競合、書込権限失効、提供側コミット後のクラッシュ、重複配信をassertします。実IAM、プロセス強制終了、ネットワーク、返金上限は検証しません。対照は応答消失後に新IDで送る方式とし、余分な効果を確認して安定IDへ戻します。入力と故障位置を揃え、本番前に可視性遅延、提供側エラー、予算切れ、並行実行を追加してください。
agent-action-recovery.pypython3 agent-action-recovery.pyPython 3.11+
"""Python 3.11+, standard library. Local teaching model; never contacts a provider."""
import hashlib
import json
import sqlite3
import tempfile
from pathlib import Path
def connect(path):
db = sqlite3.connect(path)
db.execute('PRAGMA synchronous=FULL')
return db
def fingerprint(order, cents):
if type(cents) is not int or cents <= 0:
raise ValueError('positive integer cents required')
return hashlib.sha256(json.dumps([order, cents], separators=(',', ':')).encode()).hexdigest()
class Provider:
"""One transactional SQLite database models the external system's contract."""
def __init__(self, path):
self.db = connect(path)
self.db.executescript('''
CREATE TABLE IF NOT EXISTS refunds (
tenant TEXT, op TEXT, digest TEXT, cents INTEGER,
PRIMARY KEY (tenant, op));
''')
def submit(self, tenant, op, digest, cents):
# Atomic deduplication + effect, not a client-side check-then-act.
with self.db:
self.db.execute('BEGIN IMMEDIATE')
old = self.db.execute('SELECT digest FROM refunds WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
if old and old[0] != digest:
raise ValueError('provider key conflict')
if not old:
self.db.execute('INSERT INTO refunds VALUES (?,?,?,?)',
(tenant, op, digest, cents))
return {'state': 'succeeded', 'digest': digest}
def status(self, tenant, op):
row = self.db.execute('SELECT digest FROM refunds WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
return None if row is None else {'state': 'succeeded', 'digest': row[0]}
def count(self):
return self.db.execute('SELECT COUNT(*) FROM refunds').fetchone()[0]
class AgentExecutor:
def __init__(self, path, provider):
self.db, self.provider = connect(path), provider
self.db.execute('''CREATE TABLE IF NOT EXISTS operations (
tenant TEXT, op TEXT, digest TEXT, order_id TEXT, cents INTEGER,
state TEXT, PRIMARY KEY(tenant,op))''')
self.db.commit()
def state(self, tenant, op):
row = self.db.execute('SELECT state FROM operations WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
return row[0] if row else None
def mark(self, tenant, op, state):
with self.db:
self.db.execute('UPDATE operations SET state=? WHERE tenant=? AND op=?',
(state, tenant, op))
def execute(self, tenant, op, order, cents, *, authorized, lose_ack=False,
crash_after_provider=False):
digest = fingerprint(order, cents)
row = self.db.execute('SELECT digest,state FROM operations WHERE tenant=? AND op=?',
(tenant, op)).fetchone()
if row and row[0] != digest:
raise ValueError('same operation ID with different intent')
if row and row[1] == 'succeeded':
return 'succeeded'
if not row:
if not authorized:
return 'blocked'
with self.db:
self.db.execute('INSERT INTO operations VALUES (?,?,?,?,?,?)',
(tenant, op, digest, order, cents, 'prepared'))
# Reconcile first, even if permission to create a new effect has expired.
# This demo assumes a separate permission to inspect this tenant's status.
result = self.provider.status(tenant, op)
if result:
if result['digest'] != digest:
raise ValueError('status intent mismatch')
self.mark(tenant, op, 'succeeded')
return 'succeeded'
if not authorized:
return 'blocked'
# A missing status alone is NOT proof of no effect. Safe repeat here depends
# on Provider.submit's durable atomic idempotency contract, with no expiry.
self.mark(tenant, op, 'submitted')
self.provider.submit(tenant, op, digest, cents)
if crash_after_provider:
raise RuntimeError('injected crash after provider commit')
if lose_ack:
self.mark(tenant, op, 'unknown')
return 'unknown'
self.mark(tenant, op, 'succeeded')
return 'succeeded'
def run():
with tempfile.TemporaryDirectory() as folder:
root = Path(folder)
provider = Provider(root / 'provider.sqlite')
client = AgentExecutor(root / 'agent.sqlite', provider)
assert client.execute('shop', 'refund-1', 'order-7', 2500,
authorized=True, lose_ack=True) == 'unknown'
assert provider.count() == 1
client.db.close()
client = AgentExecutor(root / 'agent.sqlite', provider)
assert client.execute('shop', 'refund-1', 'order-7', 2500,
authorized=False) == 'succeeded'
assert provider.count() == 1
try:
client.execute('shop', 'refund-1', 'order-7', 3000, authorized=True)
raise AssertionError('changed intent accepted')
except ValueError:
pass
assert client.execute('shop', 'refund-2', 'order-8', 500,
authorized=False) == 'blocked'
try:
client.execute('shop', 'refund-3', 'order-9', 700,
authorized=True, crash_after_provider=True)
except RuntimeError:
pass
assert client.state('shop', 'refund-3') == 'submitted'
client.db.close()
client = AgentExecutor(root / 'agent.sqlite', provider)
assert client.execute('shop', 'refund-3', 'order-9', 700,
authorized=True) == 'succeeded'
# Direct duplicate delivery exercises provider-side atomic deduplication.
d = fingerprint('order-9', 700)
provider.submit('shop', 'refund-3', d, 700)
assert provider.count() == 2
# Distinct tenant namespace: same op is a different operation.
assert client.execute('shop-2', 'refund-3', 'order-9', 700,
authorized=True) == 'succeeded'
assert provider.count() == 3
client.db.close()
provider.db.close()
print('PASS: lost acknowledgement, restart, conflict, expired permission, crash window, duplicate delivery, tenant namespace')
print('effects=3; duplicate-effects=0; no network; deterministic; no random seed needed')
if __name__ == '__main__':
run()
独自面接演習・企業の実問題ではありません
なぜtimeoutは返金失敗の証明ではない?
ヒント
コミットと配信を分ける。
解答と分析
応答なしでも効果は存在できます。不明を保存し照合し、新しい意図を発行しません。
チェックポイントはexactly-onceを保証する?
ヒント
二つの境界を探す。
解答と分析
しません。外部効果後にノードが再実行されるので、原子的冪等契約か信頼できる照合が必要です。
承認失効で照合も止める?
ヒント
読みと書きを分ける。
解答と分析
新規変更は止めます。別の有効な読み取り権限で照会でき、本例はそれを仮定します。応答は承認を更新しません。
再送が危険になる条件は?
ヒント
保持・引数・範囲を見る。
解答と分析
重複排除失効、キーや意図変更、契約範囲外です。代替キーを作らず停止して照合します。
採点:1—概念定義、2—不確実性、3—実行と説明、4—故障対照、5—保持・認可・並列境界。
予測・検証・根拠の記録
解答を開く前に結果を予測し、演習後に差異と応用テストを記録します。端末内に保存し、言語版間で共有します。
記録を開く/書き出す/消去する →数学的確認の範囲は授業ごとに記録されています。論文の実証再現の証明ではありません。疑問点はメモに記録してください。 確認範囲
参考文献と次の学習
- AWS · Making retries safe with idempotent APIshttps://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/
- AWS · Timeouts, retries and backoff with jitterhttps://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/
- AWS · Transactional outboxhttps://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/transactional-outbox.html
- LangGraph · Fault tolerancehttps://docs.langchain.com/oss/python/langgraph/fault-tolerance
- LangGraph · Persistencehttps://docs.langchain.com/oss/python/langgraph/persistence
- Stripe · Idempotent requestshttps://docs.stripe.com/api/idempotent_requests
- gRPC · Deadlineshttps://grpc.io/docs/guides/deadlines/