【Python】PydanticAI入門!型安全にLLMエージェントを構築する新スタンダード

投稿者: | 2026-11-15

近年、大規模言語モデル(LLM)を活用したエージェント開発が急速に進化しています。しかし、従来のフレームワークではレスポンスの型保証が難しかったり、抽象度が高すぎて挙動の追跡が困難だったりする課題がありました。

そこで今、大きな注目を集めているのが、Pydantic公式チームが開発したPydanticAIです。データバリデーションのデファクトスタンダードであるPydanticの強みを活かし、Pythonエンジニアにとって最も直感的で信頼性の高いエージェント開発環境を提供してくれます。

PydanticAIの概要

PydanticAIは、型安全性と開発者体験(DX)を最優先に設計されたPython向けのLLMフレームワークです。OpenAIやAnthropic、Geminiなどの主要プロバイダを柔軟に切り替えながら、モデルからの出力をあらかじめ定義したPydanticモデルへと安全にパース・検証できます。

また、Web開発で馴染み深い「依存性注入(Dependency Injection)」の仕組みを取り入れているため、テストコードの作成やモック化が容易に行える点も大きな特徴です。

FastAPIなどを使い慣れている方なら、驚くほど自然に手に馴染む設計になっていますよ!

PydanticAIを採用するメリット

  1. 厳密な型安全性と自動バリデーション
    モデルの出力をPydanticスキーマで拘束できます。もしLLMが不正なフォーマットを出力した場合でも、自動でリトライを促して修正させる機構が標準で備わっています。
  2. 依存性注入による高いテスト容易性
    データベース接続や外部APIクライアントを型付きコンテキストとしてエージェントに渡せるため、単体テスト時のモック差し替えがスムーズです。
  3. 直感的なツール定義(Function Calling)
    Pythonの標準的なデコレータと型ヒントを用いて関数を定義するだけで、LLMが利用可能なツールとして即座に認識されます。

サンプルコード

都市名を受け取り、その天気情報とおすすめのアクティビティを構造化データとして返すシンプルなエージェントを実装してみましょう。

pip install pydantic-ai pydantic python-dotenv
import os
from dotenv import load_dotenv
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext

# .envファイルから環境変数を読み込む
load_dotenv()

# Gemini APIキーを確認
api_key = os.getenv("GEMINI_API_KEY")
if not api_key:
    raise ValueError(".envにGEMINI_API_KEYが設定されていません。")

# 1. 出力形式を定義するPydanticモデル
class CityGuide(BaseModel):
    city: str = Field(description="対象の都市名")
    weather: str = Field(description="現在の天気状況")
    recommended_activity: str = Field(
        description="天気に合わせたおすすめの過ごし方"
    )


# 2. エージェントの初期化(Gemini 3.8 Flash)
agent = Agent(
    model="google:gemini-3.8-flash",
    output_type=CityGuide,
    system_prompt=(
        "あなたは優秀な旅行アシスタントです。"
        "都市の情報とアクティビティを提案してください。"
    ),
)


# 3. エージェントが利用するツール
@agent.tool
def get_weather(ctx: RunContext[None], city: str) -> str:
    """都市の天気を取得するツール(モック実装)"""
    mock_weather = {
        "東京": "晴れ",
        "京都": "雨",
        "札幌": "雪",
    }
    return mock_weather.get(city, "曇り")


# 4. エージェントの実行
def main():
    result = agent.run_sync(
        "京都へ日帰り旅行に行く予定です。"
        "天気を確認してプランを考えてください。"
    )

    # 構造化されたデータを取得
    guide: CityGuide = result.output

    print(f"【都市】{guide.city}")
    print(f"【天気】{guide.weather}")
    print(f"【提案】{guide.recommended_activity}")


if __name__ == "__main__":
    main()

実行すると、エージェントが自動的にget_weatherツールを呼び出し、その結果を組み込んだ上でCityGuideクラスのインスタンスとして正しい型で返してくれることが確認できます。

result.data にアクセスした時点で型定義が効いているので、エディタの自動補完もバッチリ効くのが嬉しいですね。

【都市】京都
【天気】雨
【提案】雨の風情が引き立つ三十三間堂や京都国立博物館などの屋内中心の見学、
または雨の庭園が美しい寺院(詩仙堂や青蓮院など)の観賞がおすすめです。
合間に風情ある町家カフェで抹茶や和菓子を楽しむプランが適しています。

みーちゃんのワンポイント

PydanticAIで堅牢なアプリを作る最大のコツは、Pydanticモデルの各フィールドに丁寧なField(description="...")を付与することです。これがそのままLLMへの強力なプロンプトとして機能し、パース失敗によるリトライを劇的に減らしてくれますよ。