OpenAI Agents API ツール呼び出しに失敗したら？2026 デバッグガイド

「OpenAI Agents API ツール呼び出しに失敗したら？」と感じたら、まずモデル変更や権限拡大を止め、ツール定義、呼び出しリクエスト、実行結果、会話状態、再試行とロールバックの順に再現してください。単一ツールが安定するまでは、並列呼び出しや複雑なMCP連携を有効にしない方が安全です。

このガイドは、OpenAI Agents APIのQuickstart後に関数ツールの結果が安定しない開発者、function callingやMCPを本番Agentへ接続するアプリケーションエンジニア、クラウドAIエージェントのログと復旧機構を設計するプラットフォーム担当者向けです。

最初のマイルストーン：失敗を最小ケースに固定する

最初に作るのは、単一の関数ツール、固定した入力、毎回同じ目的を持つ短いタスクです。例えば「顧客IDから契約状態を取得する」のように、読み取りだけで副作用のない処理を選びます。入力を毎回変えると、モデルの判断、引数生成、業務APIの応答を同時に追うことになり、原因が隠れます。

記録する対象は、少なくとも次の順番です。

• Agentへ送ったリクエストとツール定義
• モデルが返したtool callの有無、ツール名、引数
• アプリケーションが実際に起動した関数と受け取った値
• 外部APIやMCPサーバーから返った結果
• その結果をAgentへ書き戻した内容
• 次のturnまたはitemsと、最終的なモデル応答

ここで「最終回答が間違っている」ことと「ツール呼び出しに失敗した」ことを混同しないでください。モデルがツールを正しく呼び出した後、業務データの解釈を誤る場合もあります。OpenAIのFunction Calling公式ガイドが説明するtool callの流れに沿って、生成、実行、結果の返却を分離すると、最初の故障点を特定できます。

判定チェックリストで次の作業を選ぶ

原因調査を始める前に、次のチェックリストを上から順に確認してください。チェックが付いた最初の項目が、次に修正する層です。複数の層を同時に変更せず、一つの条件を修正して同じ入力を再実行します。

• [ ] tool callがない
  送信リクエストに対象ツールが含まれ、モデル応答にもtool callがない場合は、ツール定義、説明、利用条件を確認します。実行器や外部APIの再試行はまだ行いません。
• [ ] tool callはあるが引数が不正
  ツール名が正しく、引数の型や必須項目が不一致なら、Schemaと実行器の入力契約を修正します。業務APIへ送る前に停止します。
• [ ] 引数は正しいが外部処理が失敗
  認証、権限、対象ID、タイムアウトを調べます。一時的な通信障害だけを条件付きで再試行し、権限エラーや入力不備は停止します。
• [ ] 外部処理は成功したがAgentが続行しない
  tool callとの対応識別子、結果の書き戻し、次のturnまたはitemsが同じ会話状態を参照しているかを確認します。
• [ ] 副作用の後に応答だけ失われた
  直ちに再送せず、状態照会、冪等キー、人手確認の順に進めます。支払い、削除、公開、書き込みを無制限に繰り返してはいけません。
• [ ] 単一ツールが安定している
  ここまで確認できた場合だけ、依存関係のある複数ツール、並列呼び出し、MCP連携へ進みます。

このリストで最初の失敗層が決まれば、次に調べるログと復旧方法も決まります。モデルを変更する、ツール権限を広げる、再試行回数を増やすといった操作は、該当層の証拠を保存した後に行ってください。

Schemaの検証を先に終わらせる

OpenAI Agents APIが関数ツールを呼び出さない、または引数検証で止まる場合は、説明文を増やす前に契約を確認します。ツール名が登録側と一致しているか、必須項目が実行器の要求と同じか、文字列・数値・真偽値の型がずれていないかを照合してください。

特に見落としやすいのは、次のような境界です。

• 必須項目を省略した場合の扱い
• null、空文字、空配列を受け付けるか
• enumにない値を受け取ったときの処理
• 入れ子オブジェクトの必須項目
• 数値として扱う値を文字列で受け取った場合の変換
• 実行結果のJSON構造と、次のAgent処理が読む構造

固定サンプルには、正常値だけでなく空値、型違い、未知の列挙値を含めます。検証エラーを握りつぶして既定値へ置き換えると、表面上は実行できても誤った対象へ書き込む危険があります。MCPを使う場合は、MCPとコネクターの公式説明も確認し、MCP側の入力契約とアプリ側の変換処理を別々に記録してください。

単一ツールの実行経路を分解する

Schemaが正しくても、ツール呼び出しが止まる場所は複数あります。次の対照リストを使い、症状ごとに復旧操作を変えてください。

モデルがtool callを出していない場合

• 検証するもの：ツール定義がリクエストへ含まれているか、名前と説明が目的に合っているか
• 主な仮説：モデルがツールを必要と判断していない、または利用可能なツールとして渡されていない
• 復旧：固定入力で再実行し、送信直前のツール一覧とモデル応答を保存する

tool callはあるが、引数検証で失敗する場合

• 検証するもの：Schema、型変換、enum、null処理
• 主な仮説：生成された引数と実行器の契約が一致していない
• 復旧：自動補正を止め、元の引数を保存して明示的なエラーをAgentへ返す

引数は正しいが、業務APIが失敗する場合

• 検証するもの：認証、権限、対象ID、タイムアウト、外部サービスの状態
• 主な仮説：Agentではなく実行環境または業務APIの障害
• 復旧：読み取り系だけを条件付きで再試行し、権限エラーや入力不備は停止する

業務APIは成功したが、Agentが続行しない場合

• 検証するもの：tool callとの対応関係、結果の書き戻し、会話識別子
• 主な仮説：結果をアプリ側だけに保存し、Agentの会話へ返していない
• 復旧：呼び出し識別子と結果を同じ実行単位へ関連付け、次のモデル応答まで追跡する

Agentsの実行方法や会話状態の扱いは、Agents API公式ドキュメントの境界に合わせて設計します。アプリ独自のジョブIDだけを信頼せず、Agent側の状態と実行器側の状態をログ上で関連付けることが重要です。

多段タスクの順序と状態を検証する

単一ツールが安定したら、依存関係のある二つの処理を追加します。例えば、最初に顧客情報を取得し、そのIDを使って契約状態を取得する流れです。この場合、後段の処理は前段の結果を受け取るまで実行できません。依存関係を無視して並列化すると、空のIDや古い状態で呼び出されます。

一方、同じ入力を参照する二つの読み取り処理は並列化できる可能性があります。対照する際は、次の状態を明確にしてください。

• Agentのsession：会話や実行を継続するための状態
• turn：現在のモデル処理単位
• items：入力、tool call、tool resultなどの個別要素
• アプリ側のジョブ状態：キュー、認証情報、業務処理の進捗
• 外部API側の状態：更新済みか、未完了か、失敗したか

これらを一つの「セッション」として扱うと、再開時に前の結果を二重送信しやすくなります。Agentsの可観測性については、公式のObservabilityガイドを参照し、相関ID、実行時間、エラー種別、結果の要約を同じ検索単位で残してください。

本番前のマイルストーン：再試行と人手介入の境界を決める

再試行は、失敗を隠す機能ではありません。通信の一時的な失敗や一時的な過負荷と、入力不備、認証失敗、権限不足を分けて扱います。後者を繰り返しても復旧せず、ログだけが増えます。

書き込み、支払い、削除、外部公開を行うツールには、少なくとも次の境界を設定してください。

• 冪等キーを渡し、同じ要求を再送しても二重処理にならないようにする
• 実行前に権限と対象状態を再確認する
• 高い影響を持つ操作には承認または人手確認を置く
• 成功応答を受け取れない場合は、再送前に状態照会を行う
• 副作用が発生した後の失敗は、無条件の再試行ではなく補償処理または担当者確認へ回す

承認やガードレールの設計は、OpenAIのGuardrails and Human Reviewガイドに示される考え方と整合させます。実行環境の資格情報や外部接続を分離する場合は、Agents環境のセキュリティ説明も確認してください。

長時間の再現作業で手元の環境が不安定な場合は、Kvmkitの日本向けMacレンタルのように、作業環境を固定できる選択肢もあります。重要なのは、環境を変えたこと自体を解決とせず、同じ入力、同じ資格情報の範囲、同じログ項目で再現結果を比較することです。

故障記録を長期観測へつなげる

毎回の障害について、「どのツールを呼んだか」だけでなく、「どの層で止まったか」を記録します。最低限、入力の識別子、Schemaの版、tool call、実行器の応答、Agentへ返した結果、再試行理由、最終状態を一つの記録へまとめてください。秘密情報や個人情報はマスキングし、プロンプト全文を無制限に保存しない運用も必要です。

クラウド環境で同じ問題を調べる場合は、Agentの実行ログと作業環境のネットワーク、資格情報、プロセス状態を分けて採取します。Kvmkitのサービス案内を確認する場合も、レンタル環境を採用するかどうかは、必要な物理インターフェース、継続負荷、保持すべき認証情報、作業期間で判断してください。

よくある疑問

FAQの内容は、上記の切り分けを実装へ落とし込む際に参照してください。特に、モデルが呼び出さない問題と、呼び出した後に実行器や会話状態で止まる問題は、同じ再試行処理へ入れないことが重要です。

OpenAI Agents APIの障害を調べるために、いきなり別モデルへ変更する必要はありません。現在のモデルと単一ツールで再現ログを揃え、Schema、実行結果、会話状態のどこが崩れているかを確認してから、並列化やMCPの追加へ進めてください。

それでも手元の環境で再現条件を固定できない場合は、クラウドAIエージェントの作業環境を一時的に分離して、同じ故障記録テンプレートで比較すると判断しやすくなります。長期的な高負荷処理や物理デバイス接続が必要なら自前環境が適しますが、短期の検証や環境差分の切り分けでは、KvmkitのMacレンタルを試す方が準備作業を抑えやすいケースがあります。

よくある質問