本稿の要点
- 「JSONとして解析できるのに、項目名やデータ型が毎回変わって後続処理が止まる」
- 最短の解決策は、普通のJSONを無理に使い続けず、下流システムが必要とする項目・型・必須条件をJSON Schemaで定義し、Structured Outputで出力契約を設定することです。ただし、形式が正しくても内容の正確さ、権限、対象リソースの存在までは保証されないため、実行前の業務検証を分けて実装します。
- このページは、AIアプリケーションの初学者、モデル出力をAPIやデータベースへ渡すバックエンド開発者、そしてAI Agentのツール連携を設計するアーキテクト向けです。人が読む回答だけを作る場合は過剰なSchemaを避け、機械が継続的に消費する箇所だけに構造契約を置く判断を説明します。
「JSONとして解析できるのに、項目名やデータ型が毎回変わって後続処理が止まる」
最短の解決策は、普通のJSONを無理に使い続けず、下流システムが必要とする項目・型・必須条件をJSON Schemaで定義し、Structured Outputで出力契約を設定することです。ただし、形式が正しくても内容の正確さ、権限、対象リソースの存在までは保証されないため、実行前の業務検証を分けて実装します。
このページは、AIアプリケーションの初学者、モデル出力をAPIやデータベースへ渡すバックエンド開発者、そしてAI Agentのツール連携を設計するアーキテクト向けです。人が読む回答だけを作る場合は過剰なSchemaを避け、機械が継続的に消費する箇所だけに構造契約を置く判断を説明します。
Structured OutputとAI Agentを最初に区別する
まず、3つを同じものとして扱わないことが重要です。
- 普通のJSON：データを表現する記法です。構文上正しいオブジェクトでも、項目の意味や必須条件までは決まりません。
- JSONモード：モデルにJSON形式で返すよう促す実装です。JSONとして読めることと、アプリケーションが期待するSchemaに一致することは別問題です。
- Structured Output：定義したSchemaに従うようモデル出力を制約する機能です。対応範囲や保証条件は利用するAPI、モデル、Schema機能によって異なります。
JSON Schemaは、JSONデータそのものではなく、データが満たすべき構造や制約をJSON形式で記述する契約です。公式仕様の現行版は2020-12で、type、required、properties、enumなどを使って検証条件を表現できます。詳しくはJSON Schemaの公式入門と仕様一覧を確認してください。 (json-schema.org)
| 消費する相手 | 適した方式 | 主な利点 | 注意点 |
|---|---|---|---|
| 人間の読者 | 自然言語 | 説明、例外、背景を柔軟に表現できます | 機械処理には向きません |
| 軽い連携や試作 | 普通のJSON | 実装が簡単で、項目追加にも柔軟です | 項目名や型が揺れます |
| 形式だけ必要なAPI連携 | JSONモード | JSONとして解析しやすくなります | 必須項目や値の妥当性は別途確認が必要です |
| 本番の抽出・保存 | Structured Output＋Schema | 項目、型、列挙値を契約化できます | 対応するSchema範囲と失敗処理が必要です |
| ツール実行 | 厳格な引数Schema＋業務検証 | 不正な引数を早期に検出できます | Schema一致だけでは実行許可になりません |
人が読む回答にSchemaを強制しない理由
議事録の要約、製品比較、障害原因の説明など、出力を人が読んで判断する処理では自然言語が適しています。回答に「必須の説明項目」「列挙値」「固定型」をすべて要求すると、例外や前提条件を表現しにくくなり、プロンプトとクライアント側の実装だけが複雑になる場合があります。
一方、抽出した顧客番号、請求日、重要度、担当部署をデータベースへ保存するなら判断は変わります。項目名がpriorityとseverityで揺れたり、数値として扱うべき値が文字列になったりすると、後続のSQL、ワークフロー、画面表示で個別対応が増えるためです。
データ抽出では「解析できる」から「契約に一致する」へ
プロンプトに「JSONだけで返してください」と書く方法は、試作では十分役に立ちます。しかし、モデルが余分な項目を追加する、必須項目を省略する、日付の表記を変える、未確定値を推測して埋めるといった問題は、構文解析だけでは防げません。
JSONモードは、主にJSONとして扱える出力を得るための仕組みです。Structured Outputは、Schemaに沿った形を求めるため、項目と型が固定された抽出タスクに向きます。ただし、Schemaに一致した値が事実とは限りません。公式ドキュメントでも、対応するSchemaが一部に限られることや、アプリケーション側で値を検証する必要があることが示されています。 (ai.google.dev)
注意：
statusが"approved"という列挙値になっていても、承認者が実在するか、承認権限があったか、対象レコードが現在も有効かは別の検証です。構造検証を業務承認の代わりに使わないでください。
Tool Callingでは引数Schemaと実行許可を分ける
AI Agentが在庫照会、チケット登録、ファイル操作、請求処理などを実行する場合、ツールの引数にはSchemaが必要です。product_idを文字列にするのか整数にするのか、actionに許可する値は何か、任意項目を省略できるのかを明示しないと、モデルの判断と実装側の期待がずれます。
ただし、Tool Callingで正しいJSONが返ったからといって、そのまま関数を実行してはいけません。次の順番で二重に確認します。
- モデルから受け取ったツール名が許可リストにあるか確認します。
- 引数をJSON Schemaで検証し、型、必須項目、列挙値、長さを確認します。
- ログイン中の利用者、対象テナント、操作対象の所有者を照合します。
- 破壊的操作、送金、削除、公開などは、追加確認や人間の承認を要求します。
- データベースや外部サービスへ問い合わせ、対象リソースが実在し、現在の状態で操作可能か確認します。
- 実行結果を
tool_resultなどの機械可読イベントとしてAgentへ返し、最終回答を生成させます。
ツール利用の公式仕様では、入力Schemaがツールに渡す引数の期待形式を定義します。実際の実行、結果の照合、権限判断はアプリケーション側の責任です。 (docs.anthropic.com)
動的UIと多段階Agentでは互換性を先に設計する
Structured Outputは、フォーム、カード、検索結果一覧、承認パネルなどのUIをモデル出力から生成する用途にも使えます。例えば、component_type、label、value、optionsをSchemaで固定すれば、フロントエンドは自由文を解析せずに表示できます。
しかし、Schemaに項目を追加しただけでも、古いクライアントが想定外の値を受け取る可能性があります。実運用では、次の設計を先に決めておきます。
- Schemaにバージョン識別子を持たせる。
- 新しい項目には安全なデフォルト値を用意する。
- 既存クライアントが無視しても壊れない拡張方式を採用する。
- 未対応のコンポーネントには回退用のテキスト表示を用意する。
- 検証失敗時は空画面にせず、再生成、手動編集、自然言語表示へ切り替える。
多段階Agentでは、中間状態と最終結果も分けて考えます。ツール呼び出しID、処理状態、再試行回数、外部サービスの結果は機械可読であるべきですが、内部の推論過程まで必須JSON項目として保存する必要はありません。保存すべきなのは、再実行や監査に必要な入力、イベント、結果、エラー、承認記録です。
各APIのSchema互換性は同じではありません。例えば、ある公式実装では厳格なSchema適用時にJSON Schemaの一部だけがサポートされ、別の実装ではStructured OutputとFunction Callingの用途が分けて説明されています。導入前にStructured Outputの公式仕様、Geminiの構造化出力仕様、ツール入力Schemaの公式説明を読み、使用予定のキーワードが対応範囲に含まれるか確認してください。 (ai.google.dev)
FAQ：導入前に混同しやすいポイント
Structured OutputとJSON modeは同じ機能ですか？
同じではありません。JSON modeはJSONとして解析できる形式を促す仕組みですが、項目名や型、必須条件まで固定するとは限りません。Structured Outputは指定したSchemaに沿うことを目標にするため、機械連携の契約として使いやすくなります。
JSON SchemaはJSONそのものですか？
JSON SchemaはJSONで記述できますが、通常のデータJSONとは役割が違います。データJSONが実際の値を運ぶのに対し、JSON Schemaは項目、型、必須条件、許可値など、データが満たすべき規則を記述します。
AI Agentは普通のJSONだけでは運用できませんか？
小規模な試作や人間が内容を確認する処理なら運用できます。ただし、Agentが次のツールを選び、処理状態を保存し、結果を別サービスへ渡す場合、項目の欠落や型の揺れが障害になります。その段階ではSchemaによる契約が適しています。
構造化出力を使えば内容の正しさも保証できますか？
保証できるのは主に形式面です。正しい型の日時や列挙値が返っても、対象が実在するか、権限があるか、内容が事実かまでは自動的に保証されません。Schema検証に加えて、業務ルール、データ照合、権限確認が必要です。
ツールの引数と最終回答の両方にSchemaが必要ですか？
ツール引数は実行前に機械が読むため、原則として厳格なSchemaを設定します。最終回答は人が読む説明を含めるなら、構造データと自然言語を併用すると扱いやすくなります。用途が異なるため、同じSchemaを無理に共有する必要はありません。
導入時に選ぶべき方式
判断に迷ったら、下流の消費者から逆算してください。
- 人間が読むだけなら、自然言語を選びます。
- ログや軽い連携で、多少の揺れをアプリケーション側で吸収できるなら、普通のJSONを選びます。
- JSONとして読みたいが、厳密な契約までは不要ならJSONモードを検討します。
- データベース登録、バッチ処理、画面生成、Tool Callingで固定項目が必要なら、Structured OutputとJSON Schemaを選びます。
- 長時間動くAgentや継続的なバッチでは、Schemaだけでなく、タイムアウト、再試行、バージョン管理、監査ログ、失敗時の回退処理まで含めて運用環境を設計します。
実装前には、同じ抽出タスクを自然言語、プロンプトによるJSON、JSONモード、厳格Schemaで比較してください。確認する項目は、構文解析の成否だけではなく、必須項目の欠落、型の揺れ、未知の項目、列挙値違反、意味的な誤り、再試行時の挙動です。APIやモデルを変更したときは、同じ評価データで再確認します。
本番運用では、Schemaを細かくしすぎることにも注意が必要です。説明文、曖昧さ、未確定値まで一つの固定構造に押し込むと、モデルが不自然に推測したり、クライアントの変更範囲が広がったりします。機械が分岐に使う値は厳格にし、人が読む補足は別のテキスト項目として扱う構成が現実的です。
現在の環境がローカルのノートPCや一時的な共有サーバーだけの場合、モデルの評価、Schemaの回帰確認、Tool Callingの権限試験を同じ条件で繰り返しにくいという弱点があります。電源管理、実行環境の差、依存パッケージの更新、アクセス権限のばらつきも、AI Agentの失敗原因になります。必要な期間だけMac環境を確保して検証したい場合は、kvmbootのヘルプセンターで接続方法や利用条件を確認し、継続利用の前に利用環境の案内も確認してください。
Structured Outputは、モデルを正しくする機能ではなく、モデルと下流システムの間に明確なデータ契約を置く機能です。自然言語、普通のJSON、JSONモード、Schema制約を同じ用途に当てはめず、誰が何を消費するのか、失敗時にどこへ戻すのかを基準に選ぶと、不要な実装コストを抑えながらAI Agentを安定運用できます。
自前の環境だけで大量抽出や継続ワークフローを検証すると、環境差分の切り分け、実行時間の確保、権限設定の再現に手間がかかります。長期の高負荷処理や物理インターフェースが必要な用途では自前のMacが適しますが、短期の評価、チーム内デモ、Schema互換性の確認なら、必要な期間だけkvmbootのMac環境を使う方が、購入後に余る機材や固定運用費を抱えずに済む場合があります。試す構成が決まったら、日本向けの利用案内から、検証期間と必要な作業環境を照合してください。