LLM機能をリリースし、本番環境で不正な形式のJSONが返されるのを見たことがあるなら、PydanticAIはあなたのために作られました。Pydanticを開発したチームによるPythonエージェントフレームワークであり、型安全で検証済みの出力をエージェント開発の中心に据えています。このガイドでは、PydanticAIとは何か、なぜ型安全性がエージェントにとって重要なのか、実際に使用する主要な概念、そしてLangGraphのような他のPythonフレームワークとどのように比較されるのかを説明します。
PydanticAIとは
PydanticAIは、Python向けのオープンソースでプロバイダーに依存しないエージェントフレームワークです。Pydantic ValidationとPydantic Logfireを開発しているチームによってメンテナンスされており、強力な検証基盤と「FastAPIのような感覚」をエージェント構築にもたらすという明確な設計目標を受け継いでいます。
簡単に言えば、エージェントが何を行うべきか、どのツールを呼び出せるか、出力がどのような形式を取るべきかを記述します。PydanticAIはモデルの呼び出しを処理し、すべての出力をPydanticモデルと照合して検証し、モデルが適合しないものを返した場合は再試行します。
このプロジェクトはベータ版を経て、2026年6月23日に安定版v2.0.0をリリースしました。v2では、エージェントのツール、フック、指示、モデル設定が再利用可能なユニットとして構成される、ハーネスファーストの設計を採用しています。`pip install pydantic-ai` または `uv add pydantic-ai` でインストールできます。
なぜ型安全性がエージェントにとって重要なのか
LLMは非決定論的です。同じ質問を2回すると、2つの異なる形式の回答が得られることがあります。チャットボックスであれば問題ありませんが、モデルの出力を実際のコード（データベースへの書き込み、API呼び出し、請求計算など）に接続した瞬間に破綻します。
ほとんどのエージェントのバグはこのギャップから生じます。モデルは「ほとんど」有効なJSONを返しますが、テストではパーサーが機能しても、本番環境の応答でフィールドが欠落したり、回答が散文に包まれたりすると、パイプラインがエラーを吐き出します。結局、防御的なパース、正規表現によるクリーンアップ、手動での再試行ループを書くことになります。
PydanticAIは、出力契約をフレームワークの一部とすることで、このギャップを埋めます。Pydanticモデルを定義し、それを出力型として渡すと、フレームワークは返される値がそのモデルと一致することを保証します。モデルが無効なものを返した場合、PydanticAIは検証エラーをLLMに送り、再試行を促します。下流のコードは、曖昧な文字列ではなく、型付けされたオブジェクトを受け取ります。
同じ考え方がツール引数にも適用されます。モデルがツールの1つを呼び出す際、関数が実行される前に、PydanticAIは引数を関数の型ヒントと照合して検証します。不正な引数がビジネスロジックに到達することはありません。
主要な概念
PydanticAIは表面積が小さいです。ほとんどの構築物で5つのアイデアがカバーされます。
エージェント
`Agent`クラスは主要なエントリポイントです。モデル識別子とオプションの指示でエージェントを作成します。このクラスは、依存関係の型と出力型の2つの型パラメーターでジェネリックであり、これによりエディターと型チェッカーがエージェントを明確に認識できるようになります。
from pydantic_ai import Agent
agent = Agent(
'anthropic:claude-sonnet-4-6',
instructions='Be concise, reply with one sentence.',
)
result = agent.run_sync('Where does "hello world" come from?')
print(result.output)
このモデル文字列を変更するだけでプロバイダーを切り替えることができ、コードの移植性を保ちます。
型付き出力
Pydanticモデルを`output_type`として渡すと、エージェントの結果はそれに対して検証されます。型付けされたオブジェクトが返され、IDEはすべてのフィールドを認識します。以下に構造化出力のスケッチを示します。
from pydantic import BaseModel
from pydantic_ai import Agent
class SupportTicket(BaseModel):
category: str
priority: int
summary: str
agent = Agent('openai:gpt-4o', output_type=SupportTicket)
result = agent.run_sync('My payment failed three times today.')
print(result.output.priority) # an int, validated, not a guess
モデルが優先度をテキストとして返したり、概要を省略したりした場合、検証は失敗し、フレームワークは再プロンプトします。生の結果を自分でパースする必要はありません。
ツール
ツールを使用すると、モデルは自身の外部にアクセスできます。データベースのクエリ、REST APIの呼び出し、計算の実行などです。`@agent.tool`デコレーターを使ってツールを登録します。PydanticAIは関数の型ヒントとdocstringを読み取ってモデルが認識するスキーマを構築し、それに対してすべての呼び出しを検証します。
from pydantic_ai import Agent, RunContext
agent = Agent('openai:gpt-4o', deps_type=str)
@agent.tool
async def get_user_balance(ctx: RunContext[str], account_id: str) -> float:
"""Return the current balance for an account."""
# ctx.deps holds your injected dependency
return await lookup_balance(ctx.deps, account_id)
モデルはツールをいつ呼び出すかを決定します。あなたの関数は、すでに検証をパスした引数でのみ実行されます。
依存関係
実際のエージェントは、データベース接続、HTTPクライアント、現在のユーザー、APIキーなどのコンテキストを必要とします。PydanticAIは依存性注入でこれを処理します。エージェントで`deps_type`を宣言し、ツールや動的な指示内で`RunContext`を介して読み取ります。チェーン全体が型安全に保たれ、実際の依存関係をフェイクに置き換えられるため、テストが容易になります。
モデルに依存しないプロバイダーとストリーミング
PydanticAIは、OpenAI、Anthropic、Gemini、DeepSeek、Grok、Cohere、Mistral、Perplexity、さらにAzure AI FoundryやAmazon Bedrockのようなクラウドオプション、および自己ホスト型モデルなど、多数のプロバイダーをサポートしています。プロバイダーの切り替えは通常、モデル文字列を1行変更するだけです。
また、データが到着するにつれて検証を適用した構造化出力をストリーミングするため、型保証を放棄することなく部分的な結果をレンダリングできます。そして、チームがPydantic Logfireも開発しているため、オブザーバビリティ（トレーシング、デバッグ、各実行のコスト追跡）が組み込まれています。
PydanticAIが他のPythonエージェントフレームワークとどう比較されるか
単一の「最良の」フレームワークというものはありません。それぞれ異なるものを最適化しています。PydanticAIがどこに位置づけられるかについて、正直な見解を以下に示します。
| フレームワーク | 主な強み | こんな時に最適 |
|---|---|---|
| PydanticAI | 型安全で検証済みの出力とツール引数 | 本番環境での信頼性とクリーンな型付きデータフロー |
| LangGraph | 明示的なステートフルグラフと制御フロー | 長期間実行される、分岐のある多段階ワークフロー |
| Google ADK | Googleエコシステムでのマルチエージェントオーケストレーション | GeminiおよびVertex AIとの深い統合 |
| OpenAI Agents SDK | ハンドオフを伴う緊密なOpenAI統合 | OpenAIファーストのスタックと迅速なセットアップ |
PydanticAIの強みは検証レイヤーです。エージェントが型付けされたデータを他のシステムに供給する場合、出力がPydanticモデルと一致するという保証により、あらゆる種類のランタイムエラーが排除されます。LangGraphは、ステートマシンや複雑なフローに対するより詳細な制御を提供します。OpenAI Agents SDKは、OpenAIにすでにコミットしていて、エージェントハンドオフやMCPサーバーサポートなどの機能を求める場合に自然にフィットします。
これらを組み合わせることもできます。PydanticAIは、より大規模なオーケストレーション内の型付き出力レイヤーとしてうまく機能します。
PydanticAIを使用すべき時
PydanticAIを検討すべきなのは、次のような場合です。
- エージェントの出力がチャットウィンドウだけでなくコードに入力され、その形式が正しい必要がある場合。
- 型チェッカーやIDEがエージェントをエンドツーエンドで理解できるようにしたい場合。
- すでにコードベースでPydanticを使用しており、モデル定義が自然に感じられる場合。
- プロバイダーの柔軟性が必要で、モデルを切り替えるためにエージェントを書き直したくない場合。
- 可観測性が重要であり、Logfireの組み込みトレーシングが魅力的な場合。
複雑な分岐を伴う大規模なグラフベースのオーケストレーションが必要で、ステートマシンフレームワークがより直接的な制御を提供する場合には、別の選択肢を検討してください。
エージェントの背後にあるAPIのテストとモック
PydanticAIエージェントの信頼性は、それが依存するAPIの信頼性に依存します。すべての実行はLLMプロバイダーを呼び出し、ほとんどの有用なエージェントは独自のRESTエンドポイントやサードパーティツールも呼び出します。これらの呼び出しは、不安定な動作、予期せぬコスト、および形式の不一致が生じる場所です。PydanticAIはモデルの出力を検証しますが、呼び出している上流ツールAPIが期待するものを返すかどうかは検証できません。
Apidogがここに適合し、これはフレームワークとは異なる役割です。Apidogは、エージェントが通信する基盤となるAPIをテストおよびモックするためのAPIプラットフォームです。
いくつかの具体的な使用例：
- LLMまたはツールエンドポイントをモックする。開発中に、決定論的な応答を返すモックAPIにツールを向けます。これにより、テスト実行ごとにトークンを消費することなく、イテレーション中にプロバイダーのレート制限を回避できます。
- 応答形式をアサートする。RESTエンドポイントを`@agent.tool`関数に組み込む前に、APIアサーションを使用して、実際の応答がツールが期待する構造と一致することを確認します。エージェントの実行の奥深くではなく、APIレイヤーで欠落したフィールドを検出します。
- 環境ごとにキーを管理する。プロバイダーキーとベースURLを個別のApidog環境に保持することで、コードを変更することなく、ローカル、ステージング、CIの実行が正しいターゲットに到達するようにします。
- LLMエンドポイントを直接検証する。HTTP経由でプロバイダーを呼び出す場合、ApidogでChatGPT APIをテストして、エージェントがそれらに依存する前に認証、ストリーミング、ツール呼び出しの形式を確認できます。
Apidogはエージェントを構築したりオーケストレーションしたりするものではなく、PydanticAIの代替品でもありません。それは、エージェントが実行されるAPIサーフェスをテストおよびモックするためのベンチです。試してみたい場合は、Apidogをダウンロードして、まずツールのエンドポイントの1つをモックしてみてください。
よくある質問
PydanticAIは無料かつオープンソースですか？
はい。PydanticAIはオープンソースであり、PyPIから`pip install pydantic-ai`または`uv add pydantic-ai`でインストールできます。フレームワークはあなたに代わってLLMプロバイダーのAPIを呼び出すため、使用するLLMプロバイダーには引き続き料金がかかります。開発中にプロバイダーのコストを抑えるには、実行ごとにライブモデルにアクセスする代わりに、テスト中にAPI応答をモックできます。
PydanticAIはどのモデルと連携しますか？
プロバイダーに依存しません。ドキュメントには、OpenAI、Anthropic、Gemini、DeepSeek、Grok、Cohere、Mistral、Perplexity、さらにAzure AI FoundryやAmazon Bedrockなどのクラウドオプション、および自己ホスト型モデルが記載されています。モデルは`Agent`コンストラクタに`'anthropic:claude-sonnet-4-6'`や`'openai:gpt-4o'`のような文字列を渡すことで選択し、切り替えは通常1行の変更で済みます。
PydanticAIはLangChainやLangGraphとどう異なりますか？
PydanticAIは型安全性、つまりPydanticモデルに裏打ちされた検証済みの構造化出力と検証済みのツール引数を中心としています。LangGraphは、多段階の分岐ワークフローのための明示的なステートフルグラフを中心としています。出力形式の保証とクリーンな型付きデータフローが優先事項である場合、PydanticAIはうまく適合します。複雑なステートマシンをきめ細かく制御する必要がある場合は、グラフフレームワークがより直接的な手段を提供します。
Pydanticを使うにはPydanticを知っている必要がありますか？
知っていると役立ちますが、基本的な部分はすぐに習得できます。`BaseModel`を継承するクラスとしてデータ形式を定義し、PydanticAIはそれらを出力およびツールスキーマに使用します。APIテストにPythonを使用した経験がある、またはFastAPIで作業したことがある場合、その精神モデルは馴染み深く感じるでしょう。
結論
PydanticAIは、エージェント開発に実用的なものをもたらします。それは、モデルの出力とツール呼び出しが宣言した型と一致するという保証です。これにより、本番環境でのバグの実際の原因が排除され、データフローがクリーンに保たれます。大規模なグラフオーケストレーションよりも信頼性と型付き出力が重要である場合に選択してください。
どのフレームワークを選択するにしても、エージェントの基盤となるAPIはテストが必要です。ApidogでLLMとツールエンドポイントをモックし、その応答形式をアサートし、環境ごとにキーを管理することで、実際に検証済みの基盤でエージェントを実行できます。