AIエージェントのツール呼び出しエラー処理｜本番で壊れないリトライ設計と障害の切り分け

AIエージェントのツール呼び出しエラー処理とは、外部API連携の失敗を層ごとに切り分けて復旧する設計手法。

開発環境では、AIエージェントが外部APIを叩くコードは気持ちよく動きます。ところが本番に載せた途端、連携先が一瞬落ちただけで自動処理が丸ごと止まる。夜間バッチが朝には全滅していた、という詰まり方をした経験はありませんか。原因の多くは、ツール呼び出しの失敗をモデル任せにしていることにあります。エラーが起きたときに何を再試行し、何を諦め、何をモデルに考え直させるか。この切り分けを設計していないエージェントは、連携先の小さな不調ひとつで全体が崩れる。ここでは、その崩れ方を止めるためのエラー処理設計を、障害の分類から実装の考え方まで具体的に見ていきます。

本記事のコードや値は概念理解用の最小例です。実運用時は各公式ドキュメントで最新の仕様・HTTPステータスの扱い・API制限を確認してください。

モデル任せのエラー処理が本番で壊れる理由

AIエージェントの中身は、突き詰めると4つの部品でできています。判断を担うLLM、外部を叩くツール、途中経過を覚えておく状態管理、そしてこれらを回すオーケストレーションループ。ツールを選び、実行し、結果をLLMに戻し、次の行動を決める。この輪を「最終的な答えが出た」と判断するまで繰り返す仕組みです。

問題は、この輪のどこか一箇所でツール呼び出しが失敗したときに起きます。開発中は連携先が安定して応答するので、例外処理を書かなくても最後まで通ってしまう。ところが本番では、連携先のサービスが数秒落ちる、レート制限に引っかかる、想定と違う形のデータを返す、といった事象が日常的に発生します。ここで失敗をLLMに丸投げすると、自動化されたパイプラインは連携先が不調になった瞬間に壊れやすくなる。これはn8nの解説でも中核に置かれている指摘です。

なぜモデル任せだと脆いのか。LLMは「接続が切れた」という低レベルの事象を、うまく処理できる保証がありません。TCP接続の切断やDNSの一時的なタイムアウトは、アプリケーションのロジックとは無関係な、インフラ側の一過性の揺らぎです。その揺らぎをモデルの推論に持ち込むと、本来なら数百ミリ秒待って再試行すれば済む話が、モデルが混乱して余計なツールを呼んだり、処理を止めたりする原因になる。

AIエージェントを「作る」段階の解説は多く、ノーコードからPythonまでアプローチも豊富です。ただ、作った後に本番で安定稼働させる話になると、途端に情報が薄くなる。安定運用には、プロンプトの磨き込みだけでなく、失敗をどう扱うかという運用ルールの設計が欠かせません。ここが今回の主題です。

「とりあえず再試行」が事態を悪化させる場面

失敗したらとにかくもう一度叩く。素朴なこの発想が、本番でいちばん危ない。リトライすべき失敗とすべきでない失敗を混同することは、本番エージェントを壊す最速の要因のひとつと言われます。

たとえば入力データの形式が間違っている場合、同じリクエストを何度送り直しても結果は変わりません。サーバーは毎回「そのリクエストは受け付けられない」と返すだけ。無駄な試行でAPIコールを消費し、レート制限に近づき、ログを汚し、最終的に諦めるまでの時間だけが伸びていきます。

逆に、決済リクエストのような「二度実行してはいけない処理」を機械的に再試行すると、今度は副作用が二重になる。ネットワークの遅延で応答が返らなかっただけで、実際にはサーバー側で処理が完了していた、というケースが典型です。ここで盲目的にリトライすれば、100ドルの請求が200ドルになる。失敗の原因を分類しないまま再試行する設計は、直すどころか壊す方向に働くわけです。

ツール呼び出しはどこで壊れるか｜失敗を4種類に分類する

対処を決める前に、まず失敗を種類で仕分けます。分類してから復旧層を割り当てる。この順番が守れているかどうかで、エージェントの堅牢性は大きく変わります。

n8nの解説は、本番の失敗を大きく4つのカテゴリに分けています。それぞれ「どの層が責任を持って回復するか」が違う。ここを取り違えると、インフラで直すべきものをモデルに考えさせたり、モデルが直すべきものを延々とリトライしたりする事故につながります。まず全体像を表で押さえます。

この表の左半分（トランスポート障害・外部サービスエラー）は、アプリケーションのロジックの外側で起きる一過性の問題です。503 Service Unavailable は、サーバーの一時的な過負荷やメンテナンスで処理できない状態を示し、時間が経てば解消される含みを持つコードです。500 Internal Server Error はサーバーが予期しない状態に遭遇したことを示す汎用的なエラーコードで、503のように「一時的で、待てば解消する」とまでは仕様上定義されていません。一時的な障害としてリトライ対象になることはありますが必ず回復するとは限らないため、API仕様・レスポンス内容・発生頻度・冪等性を見て扱いを決めます。クライアント側のリクエスト内容そのものは正しいため、インフラ層が黙って引き受けるという方針自体は503・500どちらにも共通します。

対して右半分（入力バリデーション失敗・ロジックエラー）は、リクエストの中身そのものに問題がある。400 Bad Request は、リクエスト構文の不正などクライアント側の誤りとみなされる状態です。ペイロードが構造的に間違っている以上、何度送り直しても直りません。ここはモデルが考え直す領域。

自動リトライしてよい障害・してはいけない障害

自動リトライが有効なのは、原因が一過性で、かつ同じリクエストを送り直しても意味が通る場合に限られます。503のような一時的なサービス不能や、API仕様・レスポンス内容から一時障害と判断できる500系エラーは、その条件に当てはまることがあります。放っておいても数秒で回復することが多く、インフラ層が裏でリトライすればユーザーもモデルも障害に気づかない。理想的な吸収の形です。

一方、400 Bad Request をインフラ層でリトライするのは筋が悪い。原因はサーバーではなくリクエストの中身にあるので、ネットワークレベルの再試行では絶対に直りません。ここでリトライループを回すのは、時間とAPIコールの浪費でしかない。同じように、DBクエリが0件を返す、APIがパース不能なJSONを返すといったロジックエラーも、機械的なリトライの対象ではありません。呼び出し自体は成功しているのに、返ってきた中身が想定と違う。この場合はモデルが状況を読み取り、次の一手を考える必要があります。

リトライ層とモデル層の責任境界

回復処理は、オーケストレーション層とLLM層の2層に責任を分けます。オーケストレーション層は、一時的な障害に対する裏側での自動リトライを担う。LLM層は、アプリケーションレベルの問題で振る舞いの修正が必要になったときの、推論による回復を担う。

境界線はシンプルに引けます。「同じリクエストをそのまま送り直して直るか」を問えばよい。直るならインフラ層のリトライ、直らないならモデル層の推論的復旧。接続断や503は前者、400やロジックエラーは後者。この一問で、多くのケースが正しい層に振り分けられます。

決定的な失敗を吸収する｜指数バックオフとジッターを備えたリトライ設計

インフラ層が引き受けると決めた一時障害を、具体的にどう再試行するか。ここで素朴な実装をすると、かえって連携先を追い詰めます。

一時的なエラーへのリトライの本番標準は、指数バックオフとフルジッターの組み合わせです。指数バックオフは、再試行のたびに待機時間を指数的に伸ばす考え方。1回目は短く、失敗が続くほど間隔を空けて、回復しない依存先を叩き続けないようにします。ただし指数バックオフだけでは足りない。

問題になるのが、同時に失敗した全クライアントの動きです。ジッター（ランダムな揺らぎ）がないと、同じタイミングで落ちたクライアントが、同じ待機時間の後に一斉に再試行してしまう。回復しかけたサーバーが、その同時アクセスの波で再び過負荷になる。この現象はサンダリングハード（thundering herd）と呼ばれます。フルジッターは、待機時間に乱数の揺らぎを足してリトライを時間軸上に散らし、この波を崩す役割を持ちます。

指数バックオフとフルジッター

待機時間の計算を最小構成のイメージで示します。実際の初期遅延や上限値はAPIや実装によって変わるため、ここでは考え方の骨格だけを示します。

import random
import time

MAX_RETRIES = 5  # リトライ上限。無制限にはしない

def backoff_delay(attempt, base, cap):
    # 指数的に伸ばした待機の上限を cap で頭打ちにし、
    # 0〜その値の乱数(フルジッター)を実際の待機時間にする
    ceiling = min(cap, base * (2 ** attempt))
    return random.uniform(0, ceiling)

def call_with_retry(call_tool, base, cap):
    for attempt in range(MAX_RETRIES):
        result = call_tool()
        if result.ok:
            return result
        if not result.is_transient:  # 一時障害でなければ即座に上位へ返す
            return result
        if attempt == MAX_RETRIES - 1:  # 最後の試行なら待たずに諦める
            break
        time.sleep(backoff_delay(attempt, base, cap))
    raise RetryExhausted()  # 上限まで回復しなければエスカレーション

ここで大事なのは2点。まず、リトライは無制限にしないこと。間隔を指数的に伸ばしつつ、最大リトライ回数を必ず設ける。上限に達したら、諦めて上位にエスカレーションします。延々とリトライし続けるループは、障害を吸収しているようで、実際にはリソースを食い潰しているだけの場合が多い。もうひとつは、一時障害でない失敗（is_transient が偽）はリトライループに入れず、即座に上位へ返すこと。400のような失敗をこのループに巻き込むと、無駄な待機を重ねるだけに終わります。

レート制限（429 Too Many Requests）は、この基本形に上乗せの作法があります。429は、一定時間内にクライアントがリクエストを送りすぎたことを示すコードです。サーバーはRetry-Afterヘッダで、いつ再試行してよいかを明示できる。この場合はバックオフの計算値ではなく、サーバーが指定した待機時間に従うのが基本です。

Retry-Afterヘッダは、クライアントが後続のリクエストを送る前にどれだけ待つべきかを示す。RFC 9110ではHTTP-dateまたは秒数（delay-seconds、例: 120 なら2分）として定義され、503や3xxでの利用が説明されている。429 Too Many RequestsについてはRFC 6585で、Retry-Afterを含めてもよいとされる。実務上は429と503の両方で、返ってきたRetry-Afterを尊重するのが基本。 （RFC 9110 / RFC 6585 / MDN Web Docs の記述より要約 — https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/429 ）

Retry-Afterが返ってきたら、こちらのバックオフ計算を無視してでもその値を尊重する。サーバーが「120秒待って」と言っているのに5秒で叩き直せば、また429で弾かれるだけです。ヘッダを読み、指示された時間を待ってから再試行する。この一手間が、レート制限との付き合い方を安定させます。

サーキットブレーカーで連鎖障害を止める

リトライだけでは防げない失敗の形があります。連携先が完全に落ちて回復の見込みがないとき、リトライ設計はむしろ悪化要因になる。全リクエストがリトライを繰り返し、待機とタイムアウトでスレッドやコネクションを占有し、その詰まりが自分のサービス全体に波及する。これがカスケード障害（連鎖障害）です。

これを止めるのがサーキットブレーカー。アクティブな実行をまたいで連続失敗を追跡し、失敗が閾値を超えると回路を「開いて」、不健全な依存先への呼び出しを即座に失敗させる仕組みです。電気回路のブレーカーと同じ発想。異常な負荷を検知したら、回路を切って被害の拡大を防ぐ。

回路が開いている間、その依存先へのリクエストはリトライすらせず、すぐに失敗を返します。これには2つの効果がある。ひとつは、落ちているサービスを叩き続けないことで、こちら側のリソースの浪費を止める。もうひとつは、依存先に回復のための猶予を与える。誰も叩かなくなれば、サーバーは立て直す時間を得られます。一定時間が経ったら回路を半開にして試験的なリクエストを通し、回復していれば閉じる。この開閉のサイクルで、連鎖障害を封じ込めます。

このパターンはMichael Nygardの著書『Release It!』が起源で、Martin Fowlerの解説を通じて広く知られるようになった耐障害性の定番です。リトライが「一時的な失敗を吸収する」ための道具なら、サーキットブレーカーは「持続的な失敗から自分を守る」ための道具。役割が違うので、両方を組み合わせて初めて防御が完成します。

この『何度実行しても結果が変わらないか』の見落としは、n8nの解説が正面から扱っていない盲点でもあります。「一時障害は静かにリトライ」という原則は正しい。ただしその原則は、リトライ対象がこの性質を持つことを暗黙の前提にしています。取得系のツールなら問題ない。しかし書き込み・送信・課金を伴うツールを同じループに載せると、静かなリトライが静かな二重実行に化ける。エージェントにリトライを組み込むときは、そのツールが再送しても安全かどうかを1つずつ確認する。安全でないなら冪等キーで守る。この確認を省くと、堅牢化のつもりが事故の温床になります。

モデル層の推論的復旧｜エラーを文脈に戻してフォールバックへ誘導する

インフラ層で吸収できない失敗、つまりリクエストの中身に問題がある失敗は、モデルの出番です。ここでの発想の転換は、エラーを「例外として投げる」のではなく「モデルへの入力として返す」こと。

400 Bad Requestが返ってきたとします。スキーマ不一致、必須パラメータの欠落、不正なデータ形式。ペイロード自体が構造的に誤っているので、オーケストレーション層では修復できません。ここでエラーメッセージをそのままツールの実行結果としてモデルに返す。するとモデルは、そのエラーを読み、どこが間違っていたかを推論し、正しいリクエストを再生成できます。「必須の日付フィールドが欠けている」というエラーが返れば、モデルは次の試行で日付を補って呼び直す。人間がAPIのエラーを読んでコードを直すのと同じことを、ループの中でモデルにやらせる形です。

エラーメッセージをモデルへ返す形式

Function CallingやMCP（Model Context Protocol）を経由してツールを呼ぶ場合、エラーをどう返すかがモデルの回復力を左右します。ポイントは、エラーを人間にもモデルにも読める形で構造化して返すこと。

{
  "status": "error",
  "error_type": "validation_error",
  "http_status": 400,
  "message": "field 'due_date' is required and must be ISO 8601 format",
  "hint": "リクエストに due_date を ISO 8601 形式で含めて再試行してください"
}

スタックトレースを丸ごと返したり、「エラーが発生しました」とだけ返したりすると、モデルは何を直せばいいか判断できません。何が問題で、どう直せばよいかの手がかりを含める。これがモデル層の推論的復旧を機能させる条件です。

ロジックエラーや想定外の出力形式も、この経路で扱います。DBクエリが0件を返した、APIがパース不能なJSONを返した。呼び出しは成功しているのに中身が想定外、というケースです。この想定外の出力をモデルに取り込ませ、運用上の失敗を推論させる。モデルは、実行経路を変える、バックアップの代替ツールに切り替える、あるいは人間にエスカレーションする、といった次の行動を動的に判断します。持続的な失敗に備えて、実行コンテキストを二次的なプロバイダやバックアップツールへ切り替えるフォールバック連鎖を設計しておくと、主たるツールが機能しなくても処理が止まりません。

ただし、モデルに任せるからといって無制限にループさせてはいけない。モデルが引数を修正して再試行、また失敗、また修正、という輪が延々と回る事故は現実に起きます。モデル層にも再試行の上限を設ける。上限に達したらエスカレーションに切り替える。インフラ層と同じく、諦めどきを決めておくことが安全弁になります。

プロンプトでなく「ハーネス」を設計する視点

ここまでの層分けを、もう一段上の視点から捉え直してみます。エージェントが安定しない理由を、プロンプトの磨き込み不足だと考える向きは多い。同じプロンプトなのに出力が毎回ぶれる、多段のワークフローで途中から混乱する。こうした症状に直面すると、まずプロンプトを直そうとします。

ただ、Dev.toで論じられている「ハーネスエンジニアリング」という見方では、これらの症状の多くは最適化する層を取り違えたサインだとされます。プロンプトエンジニアリングは指示を明確にする技術、コンテキストエンジニアリングはモデルに渡す情報を整える技術。そしてハーネスエンジニアリングは、その2つを超えて、AIシステム全体の信頼性とスケーラビリティを担う領域です。

エラー処理の層分けは、まさにこのハーネスの一部です。どれだけプロンプトを磨いても、連携先が落ちたときの復旧経路が設計されていなければ、エージェントは同じ場所で転びます。出力のぶれや多段ワークフローの混乱は、プロンプトの文言ではなく、失敗をどう吸収するかという土台の設計で決まる。障害を分類し、層で復旧を分け、リトライとサーキットブレーカーとフォールバックを組む。この一連の作業は、プロンプトの外側にあるシステム設計です。信頼性は、良い指示文からではなく、良い土台から生まれる。エラー処理をハーネスの問題として捉え直すと、どこに手を入れるべきかが見えてきます。

大容量レスポンス・長時間HTTPをどう捌くか

トランスポート障害を「接続断」と抽象的に語ってきましたが、実運用でつまずくのはもっと生々しい場面です。n8nコミュニティで挙がっていた例が分かりやすい。学術データを扱うRAGパイプラインで、外部APIから論文の全文とメタデータを取得する。このJSONレスポンスが、1バッチで数MBに達することがある。

大容量ペイロードと長時間のHTTPリクエストは、それ自体がタイムアウトとメモリ膨張の原因になります。上流のAPIが処理に時間をかけると、既定のタイムアウト設定では途中で失敗する。巨大でネストの深いJSONを単一の処理で丸ごと抱えると、メモリを圧迫する。ここは「サーバーが落ちた」わけではないのに、こちら側の設定不足で失敗が起きる領域です。

タイムアウトと再試行プロファイルの調整

対処の方向は2つあります。ひとつは、耐障害的なプロファイルの設計。長時間かかる呼び出しを想定して、タイムアウトを延ばし、リトライの設定を調整する。既定値のまま大容量処理を流すと、正常に完了できる処理まで一律のタイムアウトで切られてしまう。処理の重さに合わせて、待てる時間を設定し直す必要があります。

もうひとつは、単一処理の負荷を下げる工夫。数MBのJSONを一度に処理するのではなく、データを分割してバッチやストリーミングで少しずつ捌く。1回あたりの処理を小さく保てば、タイムアウトにもメモリ膨張にもかかりにくくなる。大きな塊を小さく割る、という素朴な発想が、長時間HTTPの安定化には効きます。

なお、こうしたクラウドのLLMエージェントやワークフローは、GPUを積んだマシンでなくても動きます。監視・実行する側の環境は軽量で構いません（クラウド側でエージェントを動かす構成の前提はClaude Code推奨スペックの解説（ai-hardware-zukan.com）でも整理されています）。ローカルでモデルを自前運用する場合はハード選定の話が別途絡みますが、外部APIを叩くエージェントの信頼性設計は、今回のエラー処理の層分けがそのまま効いてきます。

まとめ

本番でエージェントを落とさないエラー処理は、失敗を種類で分けることから始まります。トランスポート／ネットワーク障害と外部サービスエラー（接続断・503・429・一時障害と判断できる5xxなど）はインフラ層が引き受け、モデルに通知せず静かにリトライする。入力バリデーション失敗（400）とロジックエラー（0件・パース不能JSON）はモデル層に返し、推論で引数を直させるか、代替手段へフォールバックさせる。

インフラ層のリトライは、指数バックオフとフルジッターで再試行を時間軸上に散らし、サンダリングハードを避ける。ただしリトライ回数には必ず上限を設け、回復しなければエスカレーションする。持続的な失敗にはサーキットブレーカーで回路を開き、連鎖障害を止めて依存先に回復の猶予を与える。そして最重要の前提として、自動リトライが安全なのは同じリクエストを何度送っても結果が変わらない操作に限られる。書き込み・送信・課金を伴う、送り直すと処理が積み重なってしまう呼び出しは、冪等キーで二重実行を防いでから再試行する。

モデル層では、エラーを例外として投げるのではなく、構造化した実行結果としてモデルに返す。何が問題でどう直せばよいかの手がかりを含めれば、モデルは軌道修正できます。ここでも再試行の上限を忘れない。これらの層分けを1つのエージェントに組み込めば、個々のツール障害で全体が停止することはなくなります。自分のエージェントの各ツール呼び出しに、この表の分類を当てはめてみてください。どの失敗をどの層で受けるか、抜けている経路が見えてくるはずです。

よくある質問

Q. リトライは何回まで試せばよいですか？

具体的な回数はAPIや処理の性質によって変わるため一律の正解はありませんが、無制限にはしないのが原則です。指数的に間隔を伸ばしつつ最大リトライ回数を設け、上限に達したら諦めてエスカレーションする設計が推奨されます。延々とリトライを続けるループは、障害を吸収しているようで実際にはリソースを浪費するだけになりがちです。

Q. レート制限（429）が返ってきたらどう扱えばよいですか？

429 Too Many Requests は、一定時間内にリクエストを送りすぎたことを示します。サーバーがRetry-Afterヘッダで待機時間を指定していれば、その値に従ってください。Retry-AfterはRFC 9110でHTTP-dateまたは秒数として定義され、503や3xxでの利用が説明されています。429での利用はRFC 6585で「含めてもよい」とされており、実務上は429と503の両方で返ってきたRetry-Afterを尊重するのが基本です。即時リトライせず、指示された時間を待ってから再試行してください。

Q. 何度実行しても結果が変わらない処理でなくても、自動リトライしてよいですか？

そのままでは危険です。決済やリソース作成のように、送り直すたびに処理が積み重なる呼び出しを無条件に再試行すると、実行が重複します。ネットワーク遅延による二重送信で、100ドルの請求が200ドルになるといった事故が起きます。冪等キー（idempotency key）をリクエストに付けてサーバー側で重複を検出できるようにするか、リトライ対象から外してください。

Q. エラー処理をすべてモデルに任せてはだめですか？

層で分けるべきです。接続断や503のようなインフラの一時障害は、モデルに見せず裏側で自動リトライするのが適切です。モデルに低レベルの障害まで扱わせると、余計な混乱を招きます。一方、400 Bad Request やロジックエラーのようにリクエストの中身に問題がある失敗は、モデルが読んで推論で直す領域です。「同じリクエストを送り直して直るか」で振り分けてください。

Q. 400 Bad Request はリトライで直りますか？

同じリクエストをそのまま再送しても直りません。400はリクエスト構文の不正など、クライアント側の誤りとみなされる状態で、ペイロード自体が構造的に間違っている限り、何度送っても結果は変わらないためです。ただし、エラー内容をもとに欠けているパラメータや形式を修正したうえで、別の正しいリクエストとして再試行することはあります。モデルにエラー内容を返し、正しいリクエストを再生成させるのはこの経路です。

参考資料

• AWS Builders’ Library: Timeouts, retries, and backoff with jitter