2026 AI AgentのJSON出力エラー？データフローで原因特定

2026 年 8 月 20 日 · AI Agent · 約 15 分で読める

AI Agentが無効なJSONを返したとき、原因をモデルだけに求めず、入力契約、生成、API応答、検証、ツール実行、結果回収の順に確認する方法を説明します。Structured OutputやFunction Callingの失敗を、ログと最小再現で短時間に切り分けるための比較表とチェック項目も掲載します。

Agentの実行は成功と表示されたのに、下流のパーサーでJSONエラーになり、ツールも呼び出されない状態です。

最短の解決策は、モデルを疑う前に「入力契約、モデル生成、API応答、解析・検証、ツール実行、結果回収」の順でログを分け、厳格な構造化出力を使える場合は先に有効化し、最後にアプリケーション側の業務検証を残すことです。

この手順が必要なチーム

JSONの解析エラーに悩むバックエンド開発者は、エラーが発生したデータフローの区間を確認することで、調査対象を狭められます。複数ステップのAgentを保守するエンジニアは、呼び出し識別子と実行結果の回収状態を確認してください。

本番障害を担当する運用チームには、脱落したフィールドだけでなく、入力、Schema、API応答、検証結果、ツール実行結果を同じ呼び出しIDで関連付ける設計が必要です。

まず失敗地点を6つの区間に分けます

「AI AgentのJSONエラー」は、モデルが不正な文字列を生成した場合だけの呼び方ではありません。実際には、次のどこでデータが壊れたかによって修正方法が変わります。

入力契約：Schemaの方言、必須項目、参照、許容される型をAPIが受け付けているか。
モデル生成：拒否、途中終了、長さ制限によって完全な出力が得られたか。
API応答：本文、ツール呼び出し、拒否状態、停止理由を正しく読み取ったか。
解析と検証：JSONの構文だけでなく、使用する検証器が想定したSchema方言で検証したか。
ツール実行：JSONは合法でも、対象のパス、アカウント、権限、業務範囲が有効か。
結果回収：前の呼び出しのID、ツール結果、必要な会話履歴を次のステップへ戻したか。

この順序で確認すれば、解析器に空文字や拒否メッセージをそのまま渡す設計も発見できます。

最小Schemaから契約を復元します

JSON Schemaは単なる項目一覧ではなく、データの方言を指定する契約です。$schemaは、どのSchema仕様に従うかを示す宣言であり、検証器が異なる方言を前提にすると、同じ定義でも解釈が変わる可能性があります。仕様の世代と宣言方法は、JSON Schemaの仕様一覧と$schemaの基礎説明で確認できます。

最初から業務条件をすべて含めるのではなく、文字列、数値、配列など最小限の型と必須項目だけでAPI受理を確認します。その後、列挙値、ネスト、参照、条件付き制約を一つずつ戻してください。最小Schemaでも失敗するなら、プロンプトの改善や再試行より先に、対応するSchemaサブセットとSDKの変換結果を確認するべきです。

Function Callingで引数の項目が欠ける場合

Function Callingの引数不足は、次の三つを分離して調べます。

定義側で項目が必須になっているか。
モデルが返した呼び出しの引数を、アプリケーションが別のキー名へ変換していないか。
ツール実行器が、モデルの呼び出し構造ではなく本文テキストを読んでいないか。

ツール呼び出しは「JSONとして読める」だけでは完了しません。公式のFunction Callingの処理フローでも、モデルの呼び出しを受け取り、アプリケーションが実際の関数を実行し、その結果をモデルへ返す段階が分かれています。したがって、引数を補完して黙って実行するより、欠落項目を検証エラーとして記録し、実行前に停止する方が安全です。

Structured Outputの失敗を状態別に処理します

Structured Outputを有効にしても、すべての失敗がSchema違反になるわけではありません。対応する型や制約の範囲はAPIごとに異なるため、Structured Outputの対応形式と制限を確認し、別のAPIや検証器の仕様を混ぜないようにします。入力した定義が受理されるかは、公式の検証・エラー処理案内に沿って最小リクエストで確認してください。

応答を受け取ったら、いきなりJSONパーサーへ渡さず、少なくとも次を別分岐にします。

成功：構造化された本文またはツール引数を構文解析し、業務検証へ進める。
拒否：拒否状態と理由を保存し、再試行ではなく安全な代替処理へ進める。
途中終了：停止理由と受信済みの断片を保存し、破損したJSONを実行しない。
APIエラー：HTTP応答、リクエストID、SDKエラーを記録し、瞬時的な障害だけを限定的に再試行する。

ストリーミングでは、拒否が通常の本文とは異なるイベントとして届く場合があります。Responses APIの拒否イベントに関する公式仕様を参照し、本文の断片だけを連結して成功と判定しない実装にしてください。厳格な出力を使う場合も、Structured Outputsの公式ガイドが示す制約と、アプリケーション側の検証を分けて扱います。

注意：再試行はJSONエラー全般の薬ではありません。タイムアウトや一時的な上流障害には候補になりますが、Schema不受理、権限不足、必須項目欠落を無制限に再試行すると、原因を隠したまま同じツールを重複実行する危険があります。

解析器とSchemaの組み合わせを固定します

開発環境では通るのに本番だけ失敗する場合、入力データよりも検証器のバージョンや既定の方言が異なる可能性があります。検証器名、バージョン、Schemaの$schema、使用したSDKバージョンをログへ残し、開発と本番で同じ組み合わせを使います。

特に、Schemaの参照解決、フォーマットの扱い、追加プロパティの既定値は、検証器の設定によって変わります。APIが受け付けたことは、アプリケーションの検証器が受け付けることを意味しません。まずAPI受理、次に構文解析、最後に同一Schemaでの検証という三段階に分けると、責任範囲が明確になります。

JSONが合法でも実行前に業務条件を検証します

構文上正しいJSONでも、注文番号が存在しない、指定されたファイルパスにアクセスできない、対象アカウントに権限がない、金額や件数が業務上の上限を超えている、といった失敗は残ります。Schemaは「形」を保証しても、外部リソースの存在性や現在の権限までは保証しません。

ツール実行前には、リソース存在性、認証・認可、フィールド間の関係、業務上の範囲を検証します。検証失敗時は、モデルへ返す安全なエラーと、運用担当者が読む詳細ログを分離し、秘密情報や個人情報をそのまま会話履歴へ戻さない設計にします。

履歴と呼び出し識別子をそのまま回収します

多段Agentで結果が消える場合、モデルの推論能力より、状態管理の欠落を先に確認します。モデルが返したツール呼び出しのID、ツール名、引数、実行結果、次のステップに必要な会話コンテキストが、保存・再送の途中で欠けていないかを比較してください。

インターフェースごとに状態の保持方法は異なるため、別APIの慣例を流用しないことが重要です。MCPを利用する場合は、MCPのツール仕様でツール定義と結果の構造を確認し、全体の状態規則は公式仕様の総覧に合わせます。

確認対象	観測された症状	優先する確認	先に行う修正
入力契約	APIがリクエストを受理しない	Schema方言、対応サブセット、必須項目	最小Schemaへ縮小
モデル・API応答	JSONが途中で終わる、拒否される	停止理由、拒否状態、長さ制限	解析前に状態分岐
検証器	開発と本番で結果が違う	方言、検証器とSDKのバージョン	実行環境を固定
ツール実行	合法なJSONなのに処理失敗	権限、存在性、業務範囲	実行前の意味検証
状態回収	次のステップで文脈が消える	呼び出しID、履歴、結果の再送	保存単位を統一

最小再現と相関ログで修正を確定します

障害対応では、次のチェック項目を一つの呼び出しIDに結び付けます。

[ ] 脱敏済みの入力とシステム指示を保存したか。
[ ] 送信したSchema全文と$schemaを保存したか。
[ ] モデル、API、SDK、検証器のバージョンを記録したか。
[ ] 生のAPI応答、停止理由、拒否状態を保存したか。
[ ] 構文解析エラーとSchema検証エラーを分けたか。
[ ] ツールの入力、権限確認、実行結果を保存したか。
[ ] 次のステップへ返した履歴と呼び出しIDを比較したか。

最小再現では、ツールを実行せず固定レスポンスを使い、入力契約、応答判定、検証、状態回収を順番に再現します。原因が確定してから、実際のリソースと権限を使う段階へ戻してください。これにより、無限リトライで本番データを重複更新する事故を避けられます。

本番とは分離した検証環境が必要で、手元のMacだけでは再現条件を揃えにくい場合は、地域を選べるnuvcloudの日本向けMac環境や、nuvcloudのシンガポール向け環境を候補にできます。APIキーは環境変数で管理し、ログには実値を残さない運用が前提です。

現在の環境をそのまま使い続ける方法は、権限や依存関係が混在し、再現用の隔離環境を毎回作り直す手間があり、物理的なMac環境が必要な検証では制約も残ります。短期間だけ同じ条件の検証環境を用意し、障害ログを安全に再生したい場合は、nuvcloudのMacレンタルを使う方が、自前端末を止めずに切り分けを進めやすくなります。長期の高負荷運用や物理インターフェースが必須の処理では自社設備が適しますが、今回のような一時的な再現・検証なら、必要な期間だけ環境を分離する選択が現実的です。