速報！本番AIエージェントで「構造化出力」が3回壊れた話から学ぶ「運用耐性」設計とは？

「スキーマのバリデーションは通ってる。テストも問題ない。なのに本番で壊れた…」

こんな経験、ありませんか？ 🥲

今、海外エンジニアの間で話題になっているのが、本番AIエージェントで「Structured output（構造化出力）」が3回に渡って異なる原因で壊れたという実話レポートです。

しかも厄介なのは、1回目・2回目の失敗は「プロンプトの改善」と「スキーマの厳格化」で対処できたのに、3回目は全く別の問題だったという点。

この話、AIエージェントを実務で使い始めた人なら絶対に他人事じゃないですよ。今回はその教訓を日本語でかみ砕いて解説します！

Contents

🔍 そもそも「Structured output」って何？
⚠️ 3回の壊れ方とその教訓
📝 まとめ

🔍 そもそも「Structured output」って何？

AI agent error / Photo by Vie Studio via Pexels

まず前提として整理しておきましょう。

Structured output（構造化出力）とは、LLM（大規模言語モデル）の出力を「決まったJSON形式」などに従わせる仕組みです。

たとえば契約書から情報を抜き出すエージェントなら、こんなスキーマを定義しておきます。

# 契約情報を抽出するスキーマ定義の例（Python + Pydantic）
from pydantic import BaseModel
from typing import Optional

class ContractInfo(BaseModel):
    # 契約当事者の名前
    party_name: str
    # 契約開始日（ISO 8601形式）
    start_date: str
    # 契約金額（円）
    amount: Optional[int] = None
    # 自動更新の有無
    auto_renewal: bool

このように型を定義しておくと、LLMの出力がそのスキーマに沿っているか自動でバリデーションできます。テスト環境では「97%の精度でバリデーション通過」という結果が出ることも普通にあります。

⚠️ 3回の壊れ方とその教訓

では、実際にどう壊れたのかをまとめます。

1回目の失敗：プロンプトの曖昧さ

出力スキーマはあっても、LLMへの指示が曖昧だとスキーマの解釈がブレることがあります。これはプロンプトを厳密にすることで解決しました。

2回目の失敗：スキーマが現実の多様性についていけない

「契約書の形式が想定外だった」という話です。エッジケース（例外的なケース）にスキーマが対応していなかったため、バリデーションエラーが頻発。スキーマを拡張して対処しました。

3回目の失敗：「operator-ready（運用耐性）」の欠如 ← ここが核心！

3回目は、モデルのバージョンアップによって出力の微妙な振る舞いが変わったことで発生しました。スキーマもプロンプトも変えていないのに、突然壊れた形です。

この失敗から学んだのが「operator-ready（運用耐性のある設計）」という考え方です。つまり、こういうことです。

✅ モデルのバージョン変更に耐えられる設計になっているか？
✅ 出力が「ほぼ正しい」ときのフォールバック処理はあるか？
✅ バリデーション失敗時にアラートを上げる仕組みはあるか？
✅ 人間がレビューできる「中間出力ログ」を残しているか？

# operator-readyな設計のイメージ：フォールバック付きパーサー
import json
from pydantic import ValidationError

def safe_parse_contract(raw_output: str) -> dict:
    try:
        # まずJSONとしてパースを試みる
        data = json.loads(raw_output)
        # スキーマでバリデーション
        contract = ContractInfo(**data)
        return {"status": "ok", "data": contract.dict()}
    except (json.JSONDecodeError, ValidationError) as e:
        # ❌ バリデーション失敗 → ログに残してアラート
        print(f"[ALERT] 構造化出力のパースに失敗しました: {e}")
        # フォールバック：生テキストとして保存し人間がレビュー
        return {"status": "fallback", "raw": raw_output}

ポイントをまとめるとこんな感じです 👇