第5章|安全に動かす運用を確かめる。
DAY 24 ・ 約15〜20分失敗・再試行・重複を制御する
失敗を消そうとせず、再試行してよい条件、止める条件、二重実行を防ぐ証拠を設計する。
一時的な失敗と恒久的な失敗を分け、タイムアウト、バックオフ、冪等性、復旧、停止条件を組み合わせた安全な回復設計を作れる。
言葉を知る
タイムアウト
処理が終わるのを無期限に待たず、一定時間や期限を超えたら待機を終了して失敗として扱う境界。
再試行
一時的な通信障害や混雑など、次は成功する可能性がある処理を条件付きでもう一度実行すること。
バックオフ
再試行の間隔を徐々に広げ、必要に応じて揺らぎを加え、障害中の相手へ要求が集中するのを防ぐ方法。
冪等性
同じ操作を同じ識別子で複数回受けても、最終的な外部状態が一回実行した時と同じになる性質。
復旧点
途中まで確定した状態と証拠を保存し、最初からやり直さず安全な位置から再開するための記録。
ジッター
タイムアウト、最大試行回数、初期待機、最大待機、ジッター、総期限を設定します。
Dead Letter Queue
相手がRetry-Afterのような待機指示を返した場合は、それも考慮します。
仕組みを理解する
長い仕事では、失敗しないことより失敗後の動きが品質を決める
チャットAIへ短い質問をして回答を一度受け取る場面では、失敗したら利用者がもう一度送るだけで済むことがあります。AIエージェントは、モデル呼び出し、検索、ファイル読込、外部API、承認、保存、公開を長い順番で進みます。途中の一工程が止まった時、最初から全部やり直すと費用と時間が増え、メール、決済、登録、公開を二重に実行する危険も生まれます。 失敗は例外ではなく通常の運用条件です。ネットワークは一時的に切れ、相手のサービスは混雑し、入力は不足し、権限は拒否され、モデルは指定形式を返さないことがあります。大切なのは「成功するまで繰り返せ」と指示することではありません。何が失敗し、外部へどこまで反映され、もう一度実行してよいかを判断できる状態にします。 OpenAI Agents SDKの公式資料では、ツールのタイムアウト、無効な出力、最大ターン超過などを別の例外として扱います。これは失敗名を覚えるためではなく、原因ごとに対応を変えるためです。回復設計は、失敗の分類、待つ上限、再試行条件、重複防止、復旧点、停止と人への引継ぎを一つの流れにします。
最初に、一時的・恒久的・結果不明の三つへ分ける
一時的な失敗は、少し待てば成功する可能性があります。通信の瞬断、処理量制限、短時間の混雑、503のような一時的なサービス停止が例です。恒久的な失敗は、同じ入力のまま繰り返しても直りません。認証情報の誤り、権限不足、存在しない対象、必須項目の欠落、規則違反が代表です。恒久的な失敗へ自動再試行を続けると、費用、遅延、ログ量だけが増えます。 特に危険なのが結果不明です。送信側ではタイムアウトでも、受信側は注文登録やメール送信を完了している場合があります。この時に「失敗した」と決めて同じ操作を送れば、二重処理になります。成功とも失敗とも断定せず、操作ID、相手側の状態、送信履歴、作成済み資源を照会します。 分類には、エラーコードだけでなく、操作の種類、外部効果、相手の公式な再試行指示を使います。読み取りは比較的やり直しやすくても、送信、決済、削除、公開は結果確認が先です。モデルにエラー文を読ませるだけで最終判断させず、機械的なルールと外部状態で再試行可否を確定します。
タイムアウトと実行予算で、終わらない待機を止める
タイムアウトは「この時間なら必ず失敗」という予言ではなく、待ち続けないための運用境界です。接続開始、応答待ち、ツール一回、仕事全体にそれぞれ上限を置きます。外側の仕事期限より内側の処理期限を短くし、失敗を記録して整理する時間を残します。モデルとツールのループには、ターン数、処理時間、費用、ツール呼出回数の予算も必要です。 OpenAI Agents SDKではmax_turnsを超えるとMaxTurnsExceeded、設定したツール時間を超えるとToolTimeoutErrorとして扱えます。上限を外せば完成しやすくなるとは限りません。検索語を変え続ける、同じツールを呼び続ける、別担当を往復するループが長くなるだけの場合があります。 タイムアウト後は処理を放置せず、取消可能なら取消し、実行中なら状態を照会し、復旧点を残します。利用者には「処理中」「結果確認中」「人の対応が必要」を分けて表示します。時間切れを完成や未実行へ勝手に読み替えないことが重要です。待つ上限と、超えた後の確認手順をセットで決めます。
再試行は、対象を絞り、間隔を広げ、回数を有限にする
再試行してよいのは、次の試行で直る可能性があり、同じ操作を繰り返しても安全か、安全にする仕組みがある場合です。AWSとGoogle Cloudの公式資料は、即時に連打せず、試行ごとに待ち時間を広げる指数バックオフを示しています。複数の実行が同時に同じ秒数で再開すると再び負荷が集中するため、待ち時間へランダムな揺らぎ、ジッターを加えます。 一回目は短く待ち、次は長く待ち、最大間隔と総期限を決めます。相手がRetry-Afterのような待機指示を返した場合は、それも考慮します。ただし、認証拒否、入力誤り、禁止操作へバックオフを入れても成功しません。即座に停止して修正や承認へ回します。 OpenAI Agents SDKのモデル再試行も、一般のモデル要求を無条件に繰り返すのではなく、再試行設定と方針を明示する方式です。回数、初期待機、最大待機、倍率、ジッター、対象となるネットワークエラーや状態コードを決めます。再試行回数を使い切ったら失敗を隠さず、復旧点と未完了項目を人へ渡します。
冪等性キーで、同じ意図を二回の外部効果にしない
冪等性は「同じAPIを二回呼ばない」という注意ではなく、二回届いても一回分の結果にそろえる仕組みです。注文番号、依頼ID、タスクIDなど、一つの業務意図へ一意なキーを付けます。受信側はキーと入力内容、処理状態、返却結果を保存し、同じキーを再び受けたら新しい処理を作らず既存結果を返します。 Stripeの公式資料では、作成や更新に冪等性キーを付け、接続エラー時に同じキーで安全に再送する考えが示されています。大切なのは、再試行ごとに新しいキーを作らないことです。新しいキーなら別の依頼と見なされ、二重作成を防げません。反対に、内容の違う操作へ同じキーを使い回すと、誤った結果を再利用します。 自分が呼ぶ外部サービスに冪等性機能がない場合は、送信前の業務台帳、対象別の一意制約、処理済みマーク、外部状態の照会を組み合わせます。メール本文の類似だけで重複判定せず、誰に何をいつ送る一件かを識別します。冪等性は失敗をなくしませんが、結果不明から安全に確認と再送へ進む土台になります。
復旧点と状態機械で、最初からのやり直しを避ける
長い仕事は「未着手、処理中、承認待ち、外部反映中、確認済み、失敗、要対応」のような状態へ分けます。各工程が終わるたび、入力版、成果物、外部操作ID、確認結果を保存します。再開時は最終回答の文章から推測せず、確定済み状態を読み、まだ終わっていない工程だけを進めます。 たとえば記事制作で調査と下書きが終わり、公開だけ失敗した場合、調査から再実行すれば参照日や本文が変わるかもしれません。確定した本文版と検査結果を復旧点へ残し、公開工程の状態を照会します。外部操作を始める前に「これから送る」を記録し、成功後に「確認済み」へ進めると、途中停止時の位置を追えます。 復旧点でできるのは、確定済み作業の再利用と再現です。外部側の実行を巻き戻すことや、壊れた入力を自動で正しくすることはできません。補償操作が必要なら、取消し、返金、非公開化などを別の承認付き工程として設計します。状態の遷移と所有者を明確にし、同時に二人が同じ未処理項目を取得しないようロックや予約期限も使います。
失敗が続く時は回路を開き、隔離して人へ渡す
相手サービスが長く停止している時、個々の依頼がそれぞれ再試行すると障害を悪化させます。サーキットブレーカーは、一定の失敗率や連続失敗を検知すると一時的に呼出しを止め、すぐ失敗を返す仕組みです。Microsoftの公式資料は、成功を期待して繰り返すRetryと、失敗しそうな操作を止めるCircuit Breakerの役割を分けています。 停止中は依頼を捨てません。再開可能なキューへ残す、代替経路へ回す、利用者へ遅延を知らせる、人の確認箱へ送るなど、仕事の重要度に応じて扱います。規定回数を超えた項目は隔離し、入力、試行回数、最後のエラー、外部状態、推奨対応を付けます。同じ失敗を無限にキューへ戻しません。 高リスク操作では、自動復旧より人への引継ぎを優先します。二重送金の可能性、誤送信、削除、権限変更、個人情報流出が疑われる場合は停止し、証拠を保全します。再試行回数が少ないことは弱さではありません。被害が広がる前に止まり、判断できる人へ必要な情報を渡せることが、安全なエージェントの能力です。
よくある失敗は、成功するまで繰り返す設計である
第一の失敗は、すべてのエラーを同じ再試行対象にすることです。入力誤りや権限不足は直らず、費用だけが増えます。第二は、即時再試行です。混雑した相手へ同時に要求が戻り、連鎖障害を起こします。第三は、再試行ごとに新しい操作IDを発行することです。相手には別依頼に見え、重複が発生します。 第四は、タイムアウトを未実行と決めることです。相手で成功している可能性を無視しています。第五は、エージェントの「再試行して成功しました」という文章だけで完了にすることです。作成件数、送信履歴、公開Version、決済記録を外部状態から確認します。第六は、途中成果を保存せず、毎回最初からやり直すことです。費用、入力差、判断差が大きくなります。 安全上の注意として、再試行ログへ秘密や本文全文を無制限に複製しません。操作ID、対象、入力版、試行番号、結果状態、次の待機時間、外部結果の参照を残します。再試行の成功率だけでなく、重複件数、結果不明の滞留、回復時間、人への引継ぎ件数も監視し、設計が本当に被害を減らしたか確認します。
読者演習では、一つの外部操作へ回復表を作る
自分の仕事から、メール送信、データ登録、ファイル公開など外部へ影響する操作を一つ選びます。正常、一時的失敗、恒久的失敗、結果不明の四行を作り、観測できるエラー、再試行してよいか、外部状態の確認先、最終的な担当を書きます。次に、操作へ一意な業務キーを付け、同じ依頼を二回受けた時の結果を決めます。 タイムアウト、最大試行回数、初期待機、最大待機、ジッター、総期限を設定します。処理前、処理中、処理済み、確認済みの状態を作り、どこを復旧点にするか描きます。相手が停止した場合に回路を開く条件と、隔離後に人へ渡す情報も定めます。 最後に、返答だけを失う試験をします。外部処理は成功したのに、エージェント側へ成功応答が届かなかった状況を再現し、同じキーで確認して二重処理が起きないか確かめます。次に権限不足を発生させ、再試行せず止まるか確認します。試行番号、待機、外部件数、最終状態を別の人が追えれば、失敗、再試行、重複、復旧が一つの設計として機能しています。
実例で理解する
具体例で考える
美容室の予約を登録する処理では、「予約日・開始時刻・顧客・担当者」を一つの業務キーとして扱います。一時的な通信エラーなら短く待って再試行できますが、ログイン権限がない場合は繰り返さず停止します。登録要求が時間切れになった時は、失敗と決めて同じ予約を作り直す前に、予約台帳とカレンダーを確認します。すでに登録済みなら再実行せず、日時と担当者を照合します。顧客情報と希望条件は復旧点として残し、登録だけ失敗しても最初の聞き取りからやり直しません。決めた回数で解決しなければ未完了として担当者へ引き継ぎます。
手を動かして理解する
- 外部へ影響する操作を一つ選び、一時的・恒久的・結果不明の失敗へ分類する
- タイムアウト、最大試行回数、バックオフ、ジッター、総期限を決める
- 一つの業務意図へ冪等性キーを割り当て、同じキーの再送時の動作を決める
- 処理前、処理中、処理済み、確認済みの状態と復旧点を描く
- 応答だけを失う試験と権限拒否の試験を行い、重複せず正しく停止するか確認する
04|今日の理解度を確認する
DAY 24の理解度を確認する
外部APIへの要求がタイムアウトしました。再送前に最初に行うこととして最も適切なのはどれですか。
タイムアウトは結果不明であり、相手側では処理済みの可能性があるため、外部状態の確認が先です。
未実行と決めて新しい操作IDで直ちに再送する: 相手側で完了済みなら、別依頼として二重処理が起きます。
成功したと決めて確認を省く: 未処理の可能性もあり、受入条件を満たした証拠がありません。
同じ業務キーで相手側の処理状態や作成済み結果を照会する: 正解です。結果不明を外部証拠で解消してから次の操作を選びます。
エージェントの推測だけで成功か失敗か選ぶ: 通信結果と外部状態は文章の推測では確定できません。
自動再試行の対象として最も適切なものはどれですか。
次の試行で回復する可能性があり、安全に繰り返せる一時的失敗だけを対象にします。
一時的な混雑で返った再試行可能なエラー: 正解です。有限回のバックオフを使って再試行できます。
認証情報が誤っているエラー: 同じ資格情報のまま繰り返しても直らず、修正が必要です。
必須項目が欠けている入力エラー: 入力を補わない限り同じ失敗を繰り返します。
明示的に禁止された操作: 再試行で規則を回避してはいけません。
同じ注文登録を安全に再試行できる設計として最も適切なのはどれですか。
同じキーを別処理として実行せず、既存結果へ結び付けることで二重登録を防ぎます。
試行ごとに新しい注文番号を発行する: 別の依頼として扱われ、重複作成を防げません。
本文が似ていれば重複と見なす: 似た別注文と同じ注文を安定して区別できません。
失敗した記録を削除して最初から実行する: 外部で成功していた証拠を失い、二重処理の危険が増えます。
同じ業務意図へ同じ冪等性キーを使い、処理済み結果を再利用する: 正解です。同じ意図を一つの外部効果へそろえられます。
外部サービスの失敗が長く続き、多数の仕事が再試行しています。最も適切な対応はどれですか。
故障中の相手への要求集中を止め、依頼を失わず回復や人の対応へつなげます。
すべての待機時間をゼロにする: 要求が集中し、相手と自分の両方で連鎖障害を起こします。
回路を一時的に開き、新規呼出しを止めて依頼を隔離・通知する: 正解です。障害の拡大を防ぎながら回復経路を残します。
最大試行回数を無制限にする: 費用と滞留が増え、恒久的失敗も止まりません。
成功するまで担当者へ知らせない: 重大な遅延や高リスク操作の判断が遅れます。
復旧点を使う目的として最も適切なものはどれですか。
入力版、成果物、外部操作ID、確認状態を保存し、最初からのやり直しと重複を減らします。
外部サービスの処理を必ず巻き戻す: 外部効果の取消しには別の補償操作や承認が必要です。
入力の誤りを自動的に正解へ直す: 復旧点は誤った入力の意味を判断して修正する仕組みではありません。
確定済みの成果と状態を再利用し、未完了工程だけを安全に再開する: 正解です。長い仕事を証拠のある位置から再開できます。
失敗ログを残さず見えなくする: 原因調査と重複確認に必要な証拠を失います。
04|今日の理解度を確認する
DAY 24の理解度を確認する
今日の整理をする
ここまで分かれば次へ
- ✓ 失敗を一時的・恒久的・結果不明へ分類し、結果不明では再送前に外部状態を確認する
- ✓ 再試行は有限回のバックオフとジッターを使い、冪等性キーと復旧点で二重実行と全やり直しを防ぐ
- ✓ 失敗が続く時は回路を開いて隔離し、高リスク操作は証拠を保全して人へ引き継ぐ
講義本文 4,295字