1. Pydanticとは何か
- PythonでAIエージェントやAPIを作っていると「どんなデータが渡ってくるのか」「想定外の値が来たらどうするか」という問題に直面する。Pydanticは、こうした問題をコードの段階で防ぐためのライブラリ、いわば「入力と出力の設計図」である。
- Pydanticは「データの形」と「ルール」をPythonコードで厳密に定義し自動的に検証してくれる。たとえば、以下の項目を「モデル」として定義すると、間違ったデータは早い段階でエラーとして弾かれるようになる。
(1) 入力データの項目
(2) 各項目の型（文字列・数値など）
(3) 値の範囲や制約
(4) 各項目の意味（説明文）
2. なぜPydanticが重要なのか
(1) 人間にもAIにも分かりやすい。
Pydanticで定義されたモデルには、①人間が読んでも意味が分かる、②LLMが見てもどんなデータを渡せばよいかが分かるという二重のメリットがある。Agents SDKでは、この分かりやすい構造がそのままツール仕様としてLLMに渡される。
(2) タイプヒント（Type hint）よりも強力な検証ができる。
Pythonのタイプヒント（str や int）だけでは、年齢がマイナス、異常に大きな数値、必須項目の欠落といった問題は防げない。この点、Pydanticでは、必須かどうか、数値の下限・上限、説明文まで含めて定義できる。
3. Pydanticモデルの基本構造
Pydanticでは、以下のように、入力データをクラス（class）として定義する。
from pydantic import BaseModel, Field
class PersonInput(BaseModel):
name: str = Field(..., description="人物の氏名（フルネーム）")
age: int = Field(..., ge=0, le=150, description="人物の年齢（年）")
email: str = Field(..., description="人物のメールアドレス")
上のモデルでは、①name は文字列（str）で必須（…）であること、②age は整数（int）で0〜150の範囲（ge,le）であること、③email は文字列で必須であることが定義・説明（description）されている。この「設計図」に合わないデータは実行前にエラーになる。
4. Pydanticとツール関数の組み合わせ
Pydanticモデルは、ツール関数の入力としてそのまま使える。
@function_tool
def process_person(input: PersonInput) -> str:
"""
人物情報を処理し、その要約を返します。
"""
return f"{input.name} は {input.age} 歳です。連絡先: {input.email}"
上のコードではツールが呼ばれる前に入力はPydanticで検証され、不正なデータは関数に届かない。そのため関数内では正しいデータが来る前提で安心してコードを書くことができる。
5. Agents SDKにおけるPydanticの役割
OpenAI Agents SDKでは、Pydanticは次のような場面で使われる。
(1) 構造化されたツール入力
LLMがツールを呼ぶ際、「どんなJSONを作ればいいか」を正確に理解できる。
(2) 構造化された出力
エージェントの出力形式を固定でき、後続処理が安定する。
(3) ガードレール（安全装置）
異常値や想定外のデータを早期に検出できる。
6. まとめ
Pydanticは単なる補助ライブラリではなく、①AIエージェントの入力を安全にする、②LLMとのやり取りを明確にする、③後続処理やAPI設計を安定させるという、エージェント設計の土台となる存在である。