エージェント ワークフロー リカバリ ワークフローとは
エージェント ワークフロー回復ワークフローは、エージェント実行中のエラー、タイムアウト、または外部中断によりワークフローが失敗した場合に、自動的または手動で一貫した状態に復元できる一連のメカニズムです。これは単一のツールではなく、状態の永続性、チェックポイント、再試行ロジック、補償操作を組み合わせたシステム設計です。
多くの開発者は、最初にエージェントの作業を開始するとき、ツールの定義、ステップの調整、通常の結果の処理という前方のパスのみに焦点を当てます。ただし、ネットワークのジッター、LLM 出力形式の異常、またはツール呼び出しのタイムアウトが発生すると、ワークフロー全体が停止したり、ダーティ データが生成されたりします。このとき、回復ワークフローが必要になります。
なぜ重要なのか: 現実のシナリオ
ユーザーの質問を受信する -> ナレッジ ベースを検索する -> CRM を呼び出して注文情報を取得する -> 応答を生成する、という役割を担うカスタマー サービス エージェントを構築するとします。ナレッジ ベースの検索ステップがタイムアウトし (サードパーティ API がハングするなど)、回復ワークフローがない場合、エージェントが直接エラーを報告し、ユーザーは応答を受け取らない可能性があります。さらに悪いことに、CRM 呼び出しはすでに行われており、注文ステータスが変更されています (「処理中」としてマークされるなど)。この時点で失敗するとステータスに一貫性がなく、その後の手動介入が困難になります。
リカバリ ワークフローを使用すると、タイムアウト後に次のことが可能になります。 ① 検索を 2 回再試行します。 ② それでも失敗する場合は、ローカル キャッシュにダウングレードします。 ③ キャッシュがない場合は、ステップを失敗としてマークし、「一部の情報が利用できない」ことをユーザーに通知し、その後の手動レビューのためにコンテキストを記録します。補償アクションによりダウングレード前に CRM コールがロールバックされるため、プロセス全体では CRM 状態は破壊されません。
エージェント ワークフロー リカバリ ワークフロー セットアップの実践的な手順
1. チェックポイント (チェックポイント) を定義します。
ワークフローの重要なステップごとにチェックポイントを挿入します (通常は、外部システムに副作用をもたらす操作の前後)。現在のエージェントの完全なコンテキスト (状態、実行されたステップ、中間結果) をデータベースやオブジェクト ストアなどの永続ストアにシリアル化します。
# 示例：在步骤前后保存 checkpoint
import json, boto3
s3 = boto3.client('s3')
def save_checkpoint(session_id, step_name, context):
data = {
'session_id': session_id,
'step': step_name,
'context': context, # 包含所有变量、工具调用历史
'timestamp': datetime.utcnow().isoformat()
}
s3.put_object(Bucket='agent-checkpoints', Key=f'{session_id}/{step_name}.json', Body=json.dumps(data))
最もよくある間違い: 軽量状態のみを保存し、ツール呼び出し履歴を無視します。復元するとき、LLM は以前に何が言われたのかを認識しないため、それを繰り返し呼び出したり、競合を引き起こしたりします。完全な会話履歴とツール呼び出し結果を保存する必要があります。
2. 冪等性の実装 (冪等性)
副作用がある可能性のあるすべてのツール呼び出しには冪等キーが必要です。たとえば、電子メールの送信 API は、再試行が 2 回発生しないように重複排除キーをサポートする必要があります。冪等でない場合、再試行自体が失敗の原因になります。
3. 回復戦略を設計する
一般的な回復戦略は 3 つあります。
- 自動再試行: 一時的なエラー (ネットワーク タイムアウト、429 要求が多すぎます) の場合、最大再試行は 3 回で、指数バックオフが行われます。
- ダウングレード パス: 重要なツールが利用できない場合、代替ツールやキャッシュされたデータはありますか?たとえば、検索が失敗した場合は、代わりにローカル インデックスが使用されます。
- 手動介入: 自動的に回復できない障害 (データ検証の失敗など) の場合、セッション状態が保存されて手動キューにプッシュされ、適切なエラー メッセージがユーザーに返されます。
4. レジスタ補正操作(Compensation)
ステップが失敗した場合、すでに実行されている前のステップをロールバックする必要がある場合があります。たとえば、注文が作成されたものの、その後の支払いが失敗した場合、注文は自動的にキャンセルされる必要があります。補正操作は前方ステップと 1 対 1 に対応し、ワークフローの開始時に登録する必要があります。
compensation_map = {
'create_order': 'cancel_order',
'deduct_inventory': 'restore_inventory',
}
def execute_compensation(session_id, failed_step):
# 反向遍历已执行步骤，执行对应补偿
for step in reversed(executed_steps):
if step in compensation_map:
invoke_tool(compensation_map[step], session_id)
失敗シナリオ: 補償操作自体も失敗する可能性があります。設計時には、補償の再試行や結果整合性を考慮したり、運用や保守のための障害を手動で記録したりする必要があります。
最も陥りやすい罠
- 自動再試行への過度の依存: 一部のエラー (ツールが存在しない、パラメータが間違っているなど) の場合、再試行は成功せず、時間とリソースの無駄になります。エラーはそのタイプに応じて分類し、一時的なエラーの場合にのみ再試行する必要があります。
- コンテキスト ウィンドウを無視する: 保存されたチェックポイントには大量の LLM 会話履歴が含まれており、復元時にコンテキスト ウィンドウの制限を超える可能性があります。要約または切り詰める必要があります。
- デバッグの難しさ: リカバリがトリガーされると、ログがあちこちに分散して追跡が困難になります。すべてのステップを通じてトレース ID を導入し、ログを一元管理することをお勧めします。
フォールバック: リカバリ ワークフロー自体が失敗した場合
リカバリ ワークフローの足場 (チェックポイント ストレージが利用できず、補償操作が失敗するなど) の場合、最も外側の グローバル カバー が必要です。
- 手動へのフォールバック: エラーの詳細とコンテキストを運用およびメンテナンスの通知 (Slack、PagerDuty など) に送信し、手動回復のためにセッション データを保持します。
- 最終ステータス記録: リカバリが成功したかどうかに関係なく、イベント後の分析を容易にするために、最終ステータス (成功、失敗、部分的成功) を常にデッド レター キュー (DLQ) または監査テーブルに書き込む必要があります。
- 進行性の低下: チェックポイントの書き込みが失敗した場合、実行を継続できるかどうかを検討します (例: 状態を保存せず、ログのみにダウングレードする)。
回復ワークフロー全体の設計原則は、結果整合性を確保し、ゴースト ステートを決して生成しないです。完全なリカバリを追求するのではなく、監視可能、補償可能、ロール可能であることを確認してください。
次のステップ
普通の開発者からエージェント エンジニアに移行する場合、回復ワークフローを理解することは最初のステップにすぎません。より体系的に学習するには、エージェントのコンテキスト管理、権限モデル、llm 評価、実稼働環境のデプロイメントを深く理解する必要があります。
コメントはまだありません