AIエージェントのツール呼び出し障害：8つのモードと再試行ルール

1つの論理操作と複数の試行をモデル化する

業務意図を制御単位にする

操作レコードには、依頼者、対象、望む変化、禁止事項、承認、締切、成功判定を保存する。プロンプト全文ではなく正規化した意図を識別し、後続の試行が同じ目的かを比較できるようにする。

試行はツールとの1回の相互作用である

各試行には開始・終了時刻、接続先、認証主体、要求ハッシュ、レスポンスコード、プロバイダー要求ID、例外種別、受信バイト、観測した状態を記録する。再試行のたびに新しい attempt ID を発行するが、operation ID は変えない。

通信結果と業務結果は一致しないことがある

HTTP 200でも誤った顧客を更新していれば業務上は失敗であり、HTTPタイムアウトでもサーバー側の書き込みは成功している場合がある。通信、構文、業務効果を別々に検証し、権威ある対象システムを成功の根拠にする。

相関IDは冪等性ではない

correlation ID は観測をつなぐだけで重複実行を防がない。冪等性には、同一意図を表す安定キー、保持期間、同一キーで異なるペイロードを拒否する規則、既存結果を再提示する契約が必要である。

ツール公開前に操作契約を書く

ID・権限・承認を定義する

誰の権限で何を実行できるか、承認者と承認期限、委任範囲を宣言する。エージェント自身の広いサービス資格情報より、利用者または限定サービス主体の最小権限を優先する。

入力と業務不変条件を定義する

型、必須項目、列挙値だけでなく、通貨、地域、顧客所有者、状態遷移、上限額などを検証する。モデルが欠損値を推測して埋める設計は避け、修正可能なフィールド証拠を返す。

副作用と権威ある状態を定義する

作成、更新、送信、請求などの効果、二次効果、取り消し可否を列挙する。成功確認に使う取得API、イベントログ、残高、バージョン番号も指定し、応答本文だけを信頼しない。

最初の障害より前に復旧を定義する

再試行可能条件、禁止条件、照合クエリ、補償、手動キュー、期限切れ時の扱いを実装契約に含める。障害後にモデルへ即興させるのでは遅い。

明示的な状態機械を使う

実行前の状態

received、validated、authorized、approved、ready を区別する。入力不正や承認不足はツール送信前に確定的に拒否できるため、再試行対象ではない。

実行中と確認済みの状態

送信したら in_flight、受理確認なら acknowledged とする。受理は業務完了ではない。非同期ジョブならプロバイダーIDを保存し、完了イベントまたは状態取得まで待つ。

終端状態と回復可能状態

succeeded、failed_terminal、cancelled に加え、retry_wait、reconcile、partial、human_hold を持つ。遷移理由と根拠を保存し、プロンプトの自由文だけで状態を変更しない。

unknownは実在する運用状態である

コミット境界後に接続が切れた場合、結果は不明である。unknown を消して再送せず、同じIDで結果照会、対象スナップショット比較、イベント検索を行う。解消できなければ所有者へ渡す。

プロバイダー別の再試行判断表を作る

要求の意味を証明する

HTTPメソッド名だけで安全性を決めない。対象サービスの契約、実際の副作用、冪等キー範囲、保持時間を確認する。同じ POST でも検索と請求では危険度が異なる。

再試行責任者を1層に限定する

SDK、ゲートウェイ、キュー、オーケストレーター、agent loop が同時に再試行すると増幅する。実行ロジックの1層だけを責任者にし、下位層の再送は試行証拠として可視化する。

回数・時間・同時実行をすべて制限する

最大試行数だけでなく、実時間の締切、同時実行上限、キュー年齢を設定する。バックオフ中に承認や業務意図が失効したら停止する。

プロバイダー指示を尊重しつつ判断を委ねない

Retry-After、文書化済みステータス、要求IDは使うが、業務期限、優先度、安全境界は自分たちで適用する。サーバーが再試行可能と言っても、既に期限切れの送信を続けてはならない。

予算枯渇を設計済み遷移にする

予算を使い切ったら、無限ループではなく human_hold、遅延キュー、または終端失敗へ移る。担当者、必要証拠、次に可能な操作を表示する。

障害モード1：認証または認可の拒否

状態を認識する

無効トークン、失効セッション、権限不足、テナント不一致、ポリシー拒否を分ける。401と403だけでなく、サービス固有の拒否コードと監査イベントを見る。

拒否が証明する範囲を知る

実行前の確定的拒否が保証される場合、業務効果は発生していない。ただしプロバイダーが認証前に副作用を起こさないという契約が必要であり、推測で決めない。

資格情報の差し替えを禁止する

別利用者、管理者、別テナントの資格情報へ自動切替して成功させない。権限拡大は意図と監査可能性を壊す。正しい所有者へ再承認を依頼する。

決定論的制御を強制する

ツールゲートウェイで主体、スコープ、対象テナント、操作を照合し、拒否を構造化して返す。モデルは資格情報を見たり生成したりせず、必要な再認証経路だけを提示する。

2つの拒否テストを注入する

失効トークンと権限不足を別々に試す。ツールが呼ばれないこと、代替資格情報を探索しないこと、承認担当者が特定されることを確認する。

障害モード2：スキーマまたは業務検証の失敗

構文不正と意味不正を認識する

型違い、必須欠落、列挙外に加え、存在しない顧客、禁止された状態遷移、通貨不一致などを区別する。自由文エラーをそのままモデルへ渡さずフィールド単位にする。

実行が始まっていない時を知る

サービスが原子的に事前検証すると文書化されていれば未実行として扱える。一括処理や遅延検証では一部効果があり得るため、項目別結果または照合が必要である。

想像による修正を禁止する

モデルが電話番号、金額、顧客ID、承認理由を推測して再送してはならない。許可済み変換だけを決定論的に実行し、曖昧な値は依頼者へ返す。

フィールド証拠を安全に返す

項目パス、期待型、許容範囲、修正主体を返す。秘密値や他テナントの候補を漏らさない。修正後は新しい入力ハッシュを保存し、同一操作内の意図変更として監査する。

2つの検証テストを注入する

スキーマ違反と業務不変条件違反を試す。送信回数が増えないこと、推測値が追加されないこと、正しい人へ具体的な修正要求が届くことを確かめる。

障害モード3：結果不明のタイムアウト

曖昧性の窓を認識する

接続前、送信途中、サーバー受理後、コミット後のどこで切れたかで意味が変わる。クライアントの timeout はサーバーの未実行を証明しない。

failedではなくunknownへ移す

確証がない書き込みは unknown にし、利用者へ成功とも失敗とも断言しない。operation ID、request ID、送信時刻、対象バージョンを保存する。

書き込み再送前に照合する

冪等キーによる結果取得、対象オブジェクトの読取、イベントログ、プロバイダーサポート照会の順で確認する。既存効果が一致すれば新規送信せず既存結果を返す。

解消しない曖昧性を扱う

権威ある状態でも判断できない場合、期限と影響に応じて人へエスカレーションする。高影響操作は自動再送せず、二重効果のリスクを明示する。

タイムアウト前後の2テストを注入する

送信前タイムアウトとコミット後の応答消失を試す。前者だけが再送可能で、後者は照合で既存結果を見つけることを検証する。

障害モード4：レート制限と一時的スロットリング

容量指示を認識する

429、明示的クォータコード、ヘッダー、サービスイベントを読む。認証拒否や恒久上限を一時的混雑と混同しない。

優先度と締切を保持する

待機で業務期限を越えるなら再試行しない。重要度、顧客影響、キュー年齢を使い、高優先度を無制限に優遇せず公平性を守る。

上限付きジッター・バックオフを適用する

プロバイダーの待機指示を下限として、指数バックオフとジッターを使う。各待機前に残り期限と承認有効性を確認する。

再試行ストームを避ける

集中制御、同時実行上限、トークンバケット、回路遮断で群れを抑える。複数層がそれぞれ再試行しないよう観測可能にする。

バーストとハードクォータを注入する

短期429は待機後に回復し、恒久クォータは所有者へ移るべきである。締切超過後に古い操作が突然実行されないことも確認する。

障害モード5：許可リスト済みの一時的サービス／ネットワーク障害

文書化された一時状態だけを認識する

接続リセット、選択した5xx、サービス利用不可など、契約で一時的と確認した条件だけを候補にする。未知の例外を一律に再試行可能へ分類しない。

読み取りと重大な書き込みを分ける

読み取りは鮮度制約の下で再試行できることが多い。請求、送信、削除などの書き込みは、コミット境界と冪等契約が証明されるまで照合を優先する。

IDと操作文脈を再利用する

再試行時も同じ operation ID、冪等キー、認証主体、意図ハッシュ、承認を使う。新しいキーを発行するとサービス側から別操作に見え、重複防止が働かない。

予算枯渇後に回路を開く

試行数と実時間の上限に達したら回路を開き、可視の保留または失敗状態にする。古い業務意図を自動リプレイせず、再開前に期限と承認を確認する。

送信前障害とサーバー障害を注入する

接続前の失敗と、サーバーが受理し得る5xxを別々に試す。後者はプロバイダー契約に応じて照合または同一キー再試行へ進むことを確認する。

障害モード6：部分書き込みまたは部分バッチ

項目単位の結果を認識する

バッチ全体の200だけで成功としない。各項目の状態、対象ID、バージョン、エラー、再試行可否を保持し、成功・失敗・不明の合計が入力件数と一致するか検証する。

依存する後続動作を止める

連絡先作成に失敗したのに歓迎メールを送るなど、未成立の前提に依存する工程を進めない。依存グラフで安全な独立項目だけを継続する。

再開・補償・受容を選ぶ

未処理項目のみ再開できるか、成立済み効果を補償できるか、部分結果を人が受容できるかを契約化する。補償は完全な巻き戻しとは限らない。

元の履歴と復旧履歴を両方残す

最初の操作を上書きせず、どの項目を誰がいつ再実行・補償したかを別イベントで残す。最終スナップショットだけでは原因と責任を再構成できない。

バッチと複数工程のテストを注入する

一部項目成功と、工程1成功・工程2失敗を試す。二重処理せず未完項目だけが対象になり、依存工程が停止し、所有者が明確になることを確認する。

障害モード7：重複要求、リプレイ、意図衝突

重複配送経路を認識する

利用者の連打、キュー再配送、SDK再送、Webhook重複、オーケストレーター復旧を列挙する。同じ操作が異なる経路から届いても一意に束ねる。

冪等キーの範囲と保持期間を正しく設定する

キーをテナント、ツール、操作種別、対象にスコープし、最大再配送期間以上保持する。予測可能な短いキーやテナント横断共有は避ける。

同じキーで異なるペイロードを事故として扱う

既存キーと異なる正規化ペイロードが来たら再利用も上書きもしない。意図衝突として停止し、両方のハッシュと依頼者を監査へ送る。

等価なときだけ既存結果を返す

主体、対象、意図、承認、業務条件が等価で、既存結果が現在も有効な場合に限り再提示する。古い成功を新しい要求の成功として見せない。

リプレイと衝突テストを注入する

完全に同一の再配送と、同一キー・異なる金額などの衝突を試す。前者は効果1件、後者は効果0件の追加で人へ通知されるべきである。

障害モード8：不正形式、古い、または敵対的なツール出力

通信成功でも危険なデータを含み得ると認識する

200応答でもJSON欠損、型違い、対象不一致、古いキャッシュ、埋め込み命令があり得る。構文と意味をスキーマおよび業務ルールで検査する。

返却された命令をデータとして扱う

Webページ、メール、チケット本文、ツール出力にある「制御を無視せよ」といった記述を命令として実行しない。出所、信頼境界、引用範囲を保持する。

下流への伝播を止める

検証に失敗した出力を次のツール引数、顧客メッセージ、長期メモリへ渡さない。隔離し、必要なら安全な要約または担当者レビューを要求する。

IDと鮮度を検証する

要求した対象ID、テナント、バージョン、時刻、署名を照合する。古い状態を根拠に不可逆操作を進めず、権威あるソースから再取得する。

パーサーと間接インジェクションを注入する

不正JSON、余分な項目、古いオブジェクト、命令を含む外部本文を試す。いずれも下流書き込みが起きず、理由付きで隔離されることを確認する。

完全な架空復旧ラン：TC094

固定したシステムと操作セット

Relay Desk は架空企業 Pinehaven Supply の架空エージェントである。TC094では agent A09、orchestrator O04、integration contract IC07、retry policy RP03、identity I05、tool catalog T01–T08、trace schema TS06、clock K02、target snapshot S01–S08を固定した。すべて合成データで、実在企業の成果ではない。

論理操作、試行、レビュー

8モードごとに4件、合計32件の論理操作をF01–F32として実行した。ネットワーク再送を含む物理試行は47行、独立レビューは32行である。26件が合格、6件が不合格、そのうち2件は高影響の拒否条件だった。

ダウンロードとリリース状態

編集可能なTC094復旧ワークシートとTC094操作・試行・レビュー資料を用意する。教材であり本番証拠ではない。最終状態は NOT_DEPLOYED、本番呼び出し0、顧客記録0、実メッセージ0、課金0、展開0である。

TC094の7指標を再計算する

契約合格率

操作契約の必須判定を満たしたのは32件中26件。26 ÷ 32 × 100 = 81.25%。高い平均値でも6件の欠陥と2件の拒否条件は消えない。

結果分類完全率

結果状態を証拠付きで分類できたのは32件中29件。29 ÷ 32 × 100 = 90.63%。残る3件は未知を誤って終端状態へ畳み込んだ。

安全再試行適合率

再試行を選択した12件のうち、契約上安全だったのは11件。11 ÷ 12 × 100 = 91.67%。1件でも危険な再送があれば重大操作の公開は止める。

再送前照合率

結果不明で照合が必要な8件のうち、再送前に照合したのは7件。7 ÷ 8 × 100 = 87.5%。未照合の1件は重複効果につながり得る。

重複効果封じ込め率

重複またはリプレイの6件中、追加効果を防げたのは5件。5 ÷ 6 × 100 = 83.33%。分母を全操作にすると欠陥が隠れるため、対象ケースだけを使う。

部分復旧完全率

部分結果5件のうち、項目別証拠と復旧所有者が揃ったのは4件。4 ÷ 5 × 100 = 80%。失敗項目だけでなく成立済み効果も記録する。

試行証拠完全率

必要な試行証拠が揃った論理操作は32件中30件。30 ÷ 32 × 100 = 93.75%。47試行を分母にせず、操作単位で証拠完全性を判定した。

復旧ロジックを統制されたプログラムとして構築・検証する

1. ツール契約を棚卸しする

各ツールについて主体、権限、入力、業務不変条件、副作用、コミット境界、冪等性、照合、補償、担当者を記録する。不明な契約は「再試行可能」と仮定せず、公開範囲を狭める。

2. 状態機械をプロンプト外に実装する

遷移、期限、再試行予算、承認、拒否条件を決定論的コードまたはワークフローで強制する。モデルは候補の分類や説明を支援できるが、状態変更の唯一の権限にはしない。

3. コミット境界の前後へ各障害を注入する

送信前、受理後、部分コミット後、応答消失後に障害を作る。成功系だけでは、二重効果や未知状態の欠陥を見つけられない。8モードを重要度別に反復する。

4. 根本原因別に不合格をレビューする

モデル、オーケストレーター、SDK、サービス契約、権限、観測、運用所有権のどこに欠陥があるか分類する。「再試行回数を増やす」を万能修正にしない。

5. 重要変更後に再実行する

ツールスキーマ、モデル、プロンプト、SDK、認証、サービス仕様、冪等保持期間が変わったら関連ケースを再実行する。manual、native、automation、agent の成熟段階ごとに証拠を更新し、過去の合格を流用しない。

人間レビューと運用所有権

未解決状態に合う所有者を割り当てる

認証はアクセス管理者、入力は依頼者、サービス障害はプラットフォーム運用、部分業務結果は業務所有者、敵対的出力はセキュリティへ渡す。単一の「人へ確認」キューに積まない。

レビュアーへ小さな証拠束を渡す

意図、対象、承認、試行タイムライン、要求ハッシュ、プロバイダーID、現在状態、成立済み効果、候補動作、期限をまとめる。長い会話履歴を読ませるだけでは迅速で一貫した判断にならない。

リリース判断を平均性能から分離する

合格率が高くても、高影響拒否条件、未解決unknown、重複効果、証拠欠損があれば公開しない。TC094もその原則により NOT_DEPLOYED のままである。

OpenMaxがツール呼び出し復旧を支援できる部分

適切な調整役

OpenMaxは、役割、ツール、権限、記憶、ログ、人間承認を組み合わせるAIエージェント運用の文脈を提供する。復旧では、ケース受付、証拠収集、担当者ルーティング、承認待ち、結果通知の調整に適する。

決定論的制御は統合層に残す

冪等キー、スキーマ検証、認可、期限、回路遮断、対象照合、監査イベントはAPIゲートウェイや統合サービスで強制する。OpenMaxを含むエージェント層の文章判断だけに任せない。

単純なワーカーが適する場合

処理が確定的で言語理解や複数システムの証拠整理を必要としないなら、固定job runner、queue consumer、プロバイダーSDKを使う。エージェントは曖昧な入口と人間調整に価値がある限定部分だけに置く。

ツール呼び出し復旧ガイドの限界

プロバイダーごとに意味が異なる

同じステータスコードでも、検証順序、コミット点、冪等キー保持期間、照合APIは異なる。本ガイドの表をそのまま本番契約とせず、現行文書とサンドボックスで確認する。

補償で結果を完全に戻せないことがある

メール削除は受信者の閲覧を取り消せず、返金は元の請求が無かったことにはならない。補償後も履歴と影響を残し、不可逆な結果には事前承認を強くする。

観測が不完全なことがある

ログ欠損、時計ずれ、サンプリング、プロバイダーの保持制限で確証を得られない場合がある。unknownを正直に保ち、推測で成功率を上げない。

よくあるツール復旧の失敗と修正

すべてのエラーを再試行する

誤り：401、検証エラー、衝突、未知結果まで再送する。修正：プロバイダー別許可リストと状態機械を使い、安全性を証明できない書き込みは照合または停止へ送る。

冪等性を魔法のヘッダーとして扱う

誤り：任意キーを付ければ安全だと思う。修正：キーの生成、範囲、保持、ペイロード等価性、既存結果の返却、衝突処理を契約として検証する。

複数層に再試行させる

誤り：SDK、ゲートウェイ、キュー、エージェントが独立に再送する。修正：責任者を1層に固定し、全物理試行を同じ論理操作へ関連付ける。

もっともらしい応答から成功を報告する

誤り：200や自然な文章を業務完了の根拠にする。修正：対象ID、バージョン、イベント、残高など権威ある状態を確認してから利用者へ報告する。

unknownとpartialを消す

誤り：ダッシュボードを単純にするため失敗か成功へ丸める。修正：両状態を第一級にし、所有者、期限、成立済み効果、次の安全動作を表示する。

実装チェックリストと次のステップ（Next step）

ツールを有効化する前

操作契約、最小権限、承認、冪等性、コミット境界、照合方法、再試行所有者、予算、補償、監査項目を確認する。未確認の高影響書き込みは読み取り専用にする。

自律範囲を広げる前

8モードを境界前後で注入し、重複、部分、敵対的出力を含めて人間レビューする。平均値だけでなく拒否条件を確認し、変更後の再実行条件を設定する。

運用中

unknown、partial、重複効果、再試行増幅、期限超過、証拠欠損を監視する。定期的にプロバイダー契約を再確認し、事故から新しいケースを追加する。

よくある質問（FAQ）

どのツールエラーなら安全に再試行できますか？

文書化された一時障害で、操作の冪等性または未実行が証明され、期限・承認・予算が有効な場合だけである。ステータスコード単独では判断しない。

タイムアウト後はどうすべきですか？

書き込み結果を unknown にし、同一操作IDで対象状態やプロバイダー結果を照合する。コミット後の可能性を排除できるまで新しいキーで再送しない。

冪等キーだけで十分ですか？

十分ではない。キー範囲、保持期間、ペイロード比較、衝突拒否、既存結果返却、サービス側の実装を確認する必要がある。

モデルが無効な引数を修正してよいですか？

許可済みの決定論的変換だけに限定する。顧客ID、金額、連絡先、承認理由などを推測せず、曖昧な値は依頼者へ返す。

部分成功はどのように報告しますか？

成功、失敗、不明を項目別に示し、既に発生した効果、停止した依存工程、復旧担当者、次の安全動作を明記する。「一部成功」だけでは不十分である。

高いテストスコアで展開を承認できますか？

できない。高影響拒否条件、未知状態、重複効果、監査欠損を別に評価する。TC094は81.25%の契約合格率でも NOT_DEPLOYED である。

OpenMaxはどこで役立ちますか？

OpenMaxは限定されたエージェントの調整、証拠収集、人間承認、運用ルーティングに利用できる。認可、冪等性、検証、照合などの決定論的制御は統合層に残す。

出典と編集方法

OpenMax製品文脈

• OpenMax — AI Agent Platform — 役割、ツール、権限、ログ、レビュー、運用復旧の製品文脈。

信頼性・プロトコル・安全性の出典

• RFC Editor — RFC 9110 HTTP Semantics — 冪等メソッド、自動再試行境界、Retry-After。
• AWS Well-Architected — Control and limit retry calls — 単一層再試行、上限、バックオフ、ジッター。
• AWS Builders' Library — Making retries safe with idempotent APIs — 要求ID、遅延到達、意味の等価性。
• Stripe — Idempotent requests — キー保持、ペイロード比較、実行前検証の実装例。
• OpenTelemetry — HTTP span semantic conventions — 試行span、再送回数、応答状態、エラー種別。
• OWASP — LLM06:2025 Excessive Agency — 最小機能、最小権限、利用者文脈、高影響の人間承認。
• OWASP — LLM01:2025 Prompt Injection — 間接インジェクションと信頼できないツール出力。

編集方法

OpenMax編集チームは2026年9月5日に上記の公式または主要資料を確認し、プロトコル／サービス事実と独自の運用整理を分離した。TC094は透明に示した架空教材であり、数値はベンチマーク、認証、顧客成果、OpenMax実測ではない。本番利用前に現行サービスおよびテナントの挙動を検証する必要がある。