Skip to Content
Docs02. 設計エラー処理・リトライ・フォールバック設計
中級error-handlingretries更新: 2026-10-03この記事の誤りを報告

この記事の音声は準備中です。

音声の一覧・再生リストへ

エラー処理・リトライ・フォールバック設計

この記事の目的

Agent システムで起きるエラーを 4 つの層に分類し、それぞれを「どこで・誰が(コードかモデルか)・どう」処理するかを設計できるようになります。Agent 特有の選択肢である「モデルに回復させる」を、コードによる処理と正しく使い分けられる状態がゴールです。

対象読者

  • Agent を本番投入するにあたり、失敗時の挙動を設計するエンジニア
  • 「Agent がたまに変な止まり方をする」問題を体系的に潰したいエンジニア

前提知識

  • Agent ループ — 停止条件と「失敗を観測として返す」原則
  • ツール使用 — エラーメッセージがモデルへの情報であること

本文

概要: 「モデルに回復させる」という選択肢

通常のシステムのエラー処理はコードがすべてを担いますが、Agent にはエラーをモデルに見せて回復させるという選択肢が加わります。強力な反面、使いどころを誤ると「モデルが認証エラーに 5 回挑戦する」ような無駄が生まれます。層の分類が出発点です。

詳細: エラーの 4 層分類

層例処理の主体方針
インフラ層レート制限、タイムアウト、一時的なネットワーク障害コード再試行可能性と副作用の成否を確認し、上限付き指数バックオフ。結果不明や上限到達は上位へ通知
ツール実行層: 入力・対象引数の形式不正、対象が存在しないコード + モデル観測として返し、許可された範囲内で引数訂正・代替対象を判断します
ツール実行層: 認証・認可認証失敗、権限不足、ポリシーによる拒否コード + 必要に応じ人間同じ要求を自動再試行せず、許可済み代替だけを検討します。権限変更や追加承認が必要なら指定の担当へ引き継ぎ、解決できなければ停止して報告します
モデル出力層出力形式の不正、存在しない対象への言及、指示違反コード + モデル検証で検出し、エラー内容を添えて再生成を求める
タスク層目標未達のまま行き詰まり、堂々巡りコード + 人間上限で停止し、途中経過とともにエスカレーション

判断基準はシンプルです — 決定論的に直せる失敗はコードで、判断が要る失敗はモデルで。レート制限の待機に判断は要りません。引数の間違いはエラーメッセージを読んだモデルが直せます。

認可拒否は引数訂正と別の制約です。別アカウントへの切替、権限昇格、拒否された操作を別ツールで行う経路を、モデルの回復判断として選ばせません。たとえば更新が拒否されたら、読み取りや下書きが既に許可されている場合だけ縮退し、更新が必要なら正規の承認手続きへ渡します。承認があっても、接続先の認可を上書きできるとは扱いません(エージェントのアイデンティティと認証・認可)。

詳細: リトライ設計の 3 つの注意点

  1. 冪等性同じ操作を複数回実行しても副作用の結果が 1 回と変わらない性質です。事前の実行済み確認だけでは並行実行や記録前クラッシュを防げず、受け側の原子的な重複排除などの実装条件が必要です。、エージェントの API 設計 — 副作用のあるツール(送信・登録・決済)は、受信側が受理する同じ冪等キーで再試行するか、同一 DB 内なら重複排除と更新を 1 トランザクションにします。事前の状態照会だけでは同時実行や「送信成功後・記録前の停止」を防げません。非対応の外部 API で結果が不明なら、自動再送を止めて業務 ID などで結果を照合し、未実行を確定できなければ人間に引き継ぎます。承認を得るだけで二重実行の可能性が消えるわけではありません(耐久実行の冪等性設計、Human-in-the-Loop 設計)
  2. 上限 — コードのリトライにもモデルの再試行にも上限を置きます。上限は Agent ループ の停止条件と連動させます
  3. 同じ失敗の繰り返し検出 — モデルが同じツールを同じ引数で呼んで同じエラーを受け取り続けることがあります(堂々巡り)。「直近 N 回のツール呼び出しが同一・同エラー」を検出したら、ループを打ち切って人間に渡します

詳細: フォールバック — 失敗しても価値を残す

  • 縮退運転 — Agent が失敗したら、定型応答・固定 Workflow・FAQ など、確実に動く簡易版に切り替えます。「Agent が使えないとき何も返せない」構成を避けます
  • 部分結果の保全 — 20 ステップ中 15 ステップまで進んだ成果は、未完了でも価値があります。強制終了時に「どこまで終わり、何が残っているか」を報告します
  • 人間への引き継ぎ — エスカレーション時は、生ログではなく「試したこと・失敗した理由・残りの作業」を要約して渡します。引き継ぎの質がエスカレーションの運用コストを決めます

設計判断: 失敗時のユーザー体験を先に決める

エラー処理の設計は、技術的な分類より先に「失敗したとき、ユーザーに何を見せるか」を決めると迷いません。「黙って失敗する」だけは選択肢から除外します。静かな失敗エラーを出さずに完走しながら、誤った結果を返す・誤った副作用を残す失敗。技術メトリクスに現れないため、品質シグナルによる検知設計が必要になる。は、ユーザーの信頼を最も深く損ないます。

実務での注意点

アンチパターン

  • 全エラーを一律リトライ → 認証エラーへの無意味な再試行でコストと時間を浪費し、副作用ツールでは二重実行事故を起こす → 4 層分類で方針を分け、冪等でない操作を自動リトライから外す
  • 権限不足をモデルが回避する問題と扱う → 別アカウントや禁止経路で認可境界を越える → 許可済み代替だけに限定し、必要な権限・承認は正規手続きへ引き継ぐ。できなければ停止・報告する
  • モデルの堂々巡りを放置 → 同じ失敗の繰り返しに気づかず、上限までコストを消費して結局失敗する → 同一呼び出し・同一エラーの反復検出で早期に打ち切る
  • エラーを握りつぶして成功として報告 → 「完了しました」と報告されたタスクが実は失敗しており、発覚時に信頼を全て失う → 失敗の報告経路を成功の報告と同じ品質で設計する

チェックリスト

  • 想定エラーを 4 層(インフラ / ツール / モデル出力 / タスク)に分類し、各層の処理方針を決めた
  • 引数不正と認証・認可拒否を分離し、拒否後の許可済み代替・正規承認・停止と報告の条件を決めた
  • 権限昇格・別アカウント・別ツールの禁止経路を自動回復に含めていない
  • 副作用の受信側の冪等契約・同一 DB 内の原子性・結果不明時の自動再送停止と照合手順を設計した
  • コードのリトライとモデルの再試行の両方に上限がある
  • 同じ失敗の繰り返し(堂々巡り)を検出できる
  • フォールバック先(縮退運転・人間への引き継ぎ)が定義されている
  • 失敗時にユーザーへ何を見せるかが決まっている(黙って失敗しない)

関連トピック

参考資料

TODO・未確認事項

なし

Human-in-the-Loop 設計ハーネスエンジニアリング