← 実験室トップへ戻るニャ🐾

AIをプログラムに完璧に組み込む：PythonとPydanticで実現する『構造化出力（Structured Outputs）』超実践ガイド

公開日: 2026-05-23

みなさん、こんにちは。

これまでの連載では、AIエージェントが自律的に動き回り、決済プロトコルを使って商取引を行うといった、マクロな未来のトレンドを数多く解説してきました。

では、それらの高度なAIエージェントシステムを、実際のシステムやWebアプリケーションの裏側で動かすとき、エンジニアはどのようなコードを書いているのでしょうか？

現在、AIを活用したシステム開発において、Pythonエンジニアの間でデファクトスタンダード（標準技術）となっているのが、「Structured Outputs（構造化出力）」という強力なAPI機能と、データバリデーションライブラリ「Pydantic（パイダンティック）」の組み合わせです。

今回は、資料に眠っていた開発ノウハウをベースに、「AIの気まぐれな返答を、プログラムで扱える完璧なデータへと変換する」ためのPythonスクリプトの手法を分かりやすく解説します。

1. なぜ「普通のプロンプト」ではシステムがバグるのか？

PythonからAIのAPI（GeminiやClaudeなど）を呼び出して、社内システムの自動化ツールを作る際、誰もが最初に突き当たる「絶望」があります。

それが、「AIの返答が毎回微妙に変わってしまう」という問題です。

例えば、ユーザーのメール文面から「顧客名」「要件」「緊急度」を抜き出すPythonプログラムを作りたいとします。プロンプトで「必ずJSON形式で、余計な挨拶は抜きで返して」とどれだけ厳しく指定しても、AIは時々優しさ（？）を発揮して、

こちらが抽出結果です：
{
  "customer_name": "山田太郎",
  ...
}

といったように、おまけのテキストを付けて返してきたり、キーの名前を勝手に name に変えたりしてしまいます。
これをPythonの json.loads() で読み込もうとすると、一発で「パースエラー（JSONDecodeError）」を起こしてシステムがクラッシュします。これまでのAI駆動開発（AI-Driven Development）において、この「確率的な挙動」を飼い慣らすのは至難の業でした。

2. 救世主：Pydanticによる「データ構造の強制化」

この問題を根本から解決するのが、最新のAPIがサポートする「Structured Outputs」です。
これは、プロンプトで形式を指定するのではなく、APIのリクエスト段階で「このPythonのクラス構造（Schema）に沿ったデータ以外、出力することを物理的に認めない」とAIの脳（モデル）に強力なガードレールを敷く機能です。

具体的なPythonのコード例を見てみましょう。

import os
from typing import Literal
from pydantic import BaseModel, Field
from google import genai
from google.genai import types

# 1. AIに吐き出させたい「理想のデータ構造」をPythonのクラスで定義する
class TaskExtractor(BaseModel):
    customer_name: str = Field(description="問い合わせをしてきた顧客の氏名")
    request_summary: str = Field(description="要件の簡潔な要約")
    priority: Literal["High", "Medium", "Low"] = Field(description="対応の緊急度")
    estimated_minutes: int = Field(description="対応にかかる予測時間（分単位）")

# 2. クライアントの初期化
client = genai.Client(api_key=os.environ["GEMINI_API_KEY"])

# 分析したい生のテキスト（メールの文面など）
raw_email = """
いつもお世話になっております。ねここ要塞の佐藤です。
昨日納品いただいたシステムのログイン画面でエラーが出てしまい、業務が止まっております。
大至急、調査をお願いできないでしょうか。よろしくお願いいたします。
"""

# 3. Structured Outputsを使ってAPIを呼び出す
response = client.models.generate_content(
    model='gemini-2.5-pro', # または最新のgemini-3.5コアモデル
    contents=f"以下のテキストからタスク情報を抽出してください:\n{raw_email}",
    config=types.GenerateContentConfig(
        response_mime_type="application/json",
        response_schema=TaskExtractor, # ここでPythonのクラスを直接渡すのがポイント！
        temperature=0.0 # 決定論的な挙動にするために0に設定
    ),
)

# 4. 抽出結果の確認（すでに完璧なPythonオブジェクトとして扱える）
# response.text はすでに自動パースされており、検証済みのデータになっている
extracted_data: TaskExtractor = response.parsed

print(f"顧客名: {extracted_data.customer_name}")
print(f"緊急度: {extracted_data.priority}")
print(f"予測時間: {extracted_data.estimated_minutes}分")

3. このスクリプトがもたらす開発・運用の劇的なメリット

この数行のPythonスクリプトが、システム開発の現場にもたらすイノベーションは計り知れません。

  1. パースエラーによるシステムダウンの根絶
    AIモデルの内部で確率をサンプリングする際、このSchema（Pydanticクラス）に合致するトークンしか選ばれないよう制御されるため、文字通り「100%確実に」指定したJSONフォーマットが戻ってきます。エラーハンドリングのための泥臭いコード（正規表現での切り出しなど）は完全に不要になります。
  2. 型安全（Type Safety）な開発
    抽出されたデータは、単なる辞書型（dict）ではなく、IDE（VS CodeやCursor、Claude Codeなど）で補完が効く「型安全なオブジェクト」として扱えます。extracted_data.priority と打つだけでタイポなく開発を進められるため、AI駆動開発のスピードがさらに加速します。
  3. エージェント決済やツール実行（Function Calling）との親和性
    私たちがこれまでの記事で取り上げてきた「AIエージェントによる自動決済（AP2）」や「外部ツールとの接続（MCP）」の裏側でも、この構造化データがやり取りされています。AIが「どの口座から、いくら、どの宛先に送金するか」を正確なデータ（構造体）としてPython側に渡してくれないと、安全な決済をプログラムで実行することは不可能です。

まとめ：AIを「気まぐれなAI」から「高精度なシステム部品」へ

PythonとPydanticを組み合わせたStructured Outputsの手法は、AIチャットを単なる「おしゃべりツール」から、業務システムを支える「極めて打率の高い高精度なシステム部品」へと昇華させるための必須技術です。

これからのPythonエンジニアに求められるのは、プロンプトをこねくり回すことではありません。「AIに入力するデータと、AIから受け取るデータの『境界線（インターフェース）』を、いかに綺麗にクラス定義（コード化）できるか」という設計力です。

もし、社内の定型業務やデータ抽出の自動化を考えているなら、ぜひこの最新のPython連携スクリプトをテンプレートにして、あなた専用のスマートな自動化ツールを作ってみてください。AIの進化スピードを、そのままあなたのシステムの戦闘力へと変えることができるはずです。