Pydantic AIとは｜Pythonで型安全なAIエージェント開発

Pydantic AIとは何か

結論として、Pydantic AIは「LLMを、型のついた普通のPython関数のように扱う」ための層です。公式ドキュメントは自らを「the Python AI SDK: a typed, extensible agent loop with every model a string swap away」と表現しています。

条件として、恩恵を受けやすいのは型ヒントを書く習慣があるコードベースです。例外的に、型をほとんど使っていないスクリプト群に後から載せると、旨味が薄くなります。

Pydanticチームが開発しているという出自

Pydanticは、Pythonの型ヒントをもとに入力データを検証するライブラリで、FastAPIをはじめ多くのフレームワークが内部で採用しています。その開発チームが、同じ発想をLLM周りに持ち込んだのがPydantic AIです。

リポジトリは2024年6月に公開されました。ライセンスはMITです。GitHubリポジトリのスターは、2026年11月15日にGitHub上で確認した時点で約21,200でした。ただしスター数は注目度の目安にすぎません。採用可否は、更新頻度・Issueへの対応状況・ライセンス・自分たちの要件との相性まで含めて判断してください。

OSSとして公開されている点と、商用のLogfire（可観測性サービス）を持つ企業が本体を開発している点は、採用判断のときに両方見ておくとよい部分です。

「FastAPIのような書き心地」が指している中身

この表現は雰囲気の話ではなく、具体的に3点を指します。

1. 関数の引数と戻り値に型を書くと、それがそのままスキーマになる

2. 依存するリソース（DB接続、APIクライアント、ユーザー情報など）を外から注入する

3. 検証に失敗したら、曖昧に通さずエラーとして扱う

LLMアプリでこの3点目が効きます。従来は、モデルが返したJSONを手でパースし、キーが欠けていたら自前で場合分けし、ダメならプロンプトを書き直して再送していました。Pydantic AIはこの往復をフレームワーク側に持たせています。

ミニFAQ｜Pydanticを知らなくても使えるか

Pydantic本体を使ったことがなくても始められますか。

始められます。ただし出力の定義はPydanticモデルで書くため、最低限のモデル定義の書き方は押さえておくと早いです。Pydantic公式ドキュメントのモデル定義の章だけでも先に読んでおくと、つまずきが減ります。

LangChainの代わりになりますか。

用途によります。チェーン構築やドキュメントローダー群の広さを求めるならLangChain系が有利で、出力の型保証とアプリ統合を求めるならPydantic AIが噛み合います。両者は排他ではなく、役割の重心が違います。

Pydantic AIの主要機能

Pydantic AIの機能は、「出力を信頼できる形にする」「どのモデルでも同じコードで動かす」「本番で運用できるようにする」の3層に整理できます。

構造化出力と自動バリデーション

中心機能はこれです。エージェントの定義時に出力の型を指定すると、生成結果はその型のオブジェクトとして返ります。公式ドキュメントは「Structured outputs validated on every run」と書いています。毎回検証される、という点が肝です。

検証に失敗した場合、設定した上限の範囲でモデルに再生成を促します。リトライ回数は引数で指定できるため、無制限に走ることはありません。ただし、ここで検証できるのは型や必須項目といった構造であって、書かれている内容の事実性までは保証されません。形式としては正しく、値だけが誤っている出力は通過します。

実務でありがたいのは、失敗が「検証エラー」という扱いになることです。文字列処理の失敗ではなく型の失敗として表面化するので、ログにも載るし、テストも書ける。LLM出力の扱いについてはLLMの構造化出力とは｜JSON出力とFunction Callingの使い分けで整理しているので、JSONモードやFunction Callingとの関係はそちらを参照してください。

モデル非依存｜プロバイダを文字列で差し替える

エージェント定義のモデル指定は文字列です。公式の表現は「Any model, one Python API」で、対応プロバイダとしてOpenAI、Anthropic、Google、Bedrock、Azure AI Foundry、Groq、Mistral、xAI、Ollama、および「dozens more」が挙げられています。

これが効く場面は限定的ですが、効くときは大きい。たとえば検証はローカルのOllamaで回し、本番はAzure OpenAIというケース。あるいはクライアント都合でモデルを乗り換えるケースです。アプリ側の書き換え範囲が小さくなります。

ここは誤解されやすいので補足します。差し替えが容易なのはコードであって、挙動ではありません。 モデルを変えると、出力品質・ツール呼び出しの挙動・コンテキスト長・料金・レート制限は変わります。乗り換えのたびに評価セットでの再検証は必要です。

型付き依存性注入とツール

エージェントに「外の世界」を触らせる仕組みがツールです。関数を登録しておくと、モデルが必要に応じて呼び出します。

Pydantic AIの特徴は、このツールが実行コンテキスト経由で依存リソースを受け取る点にあります。DB接続やAPIクライアントをグローバル変数で持たせるのではなく、エージェントの実行ごとに外から渡す。テスト時にモックへ差し替えるのが素直にできます。

既存のFastAPIアプリに載せるなら、この設計がそのまま効きます。FastAPIとは？Python製の高速API FW・Django/Flaskとの違いと案件単価をフリーランス視点で徹底解説で触れている依存性注入の考え方と同じ発想です。

MCP・観測・評価

本番運用で必要になりやすい周辺機能も、フレームワークや関連パッケージとして用意されています。認証・監査ログ・コスト管理・個人情報の取り扱いなどは、依然としてフレームワークの外側で設計する領域です。

MCPの仕組みそのものはModel Context Protocolとは｜MCPの仕組み・活用事例をエンジニア視点で解説に、評価の考え方はLLM評価（Evals）とは｜LLM-as-a-Judgeと品質保証の実務まで解説にまとめています。

観測バックエンドの選定は、同じPydantic社のLogfireに寄せるか、他のツールを使うかで分かれます。選択肢の比較はLangfuse・LangSmithの使い方｜LLMトレース管理と選び方が参考になります。OpenTelemetryネイティブなので、特定SaaSに縛られない構成も取れます。

耐久実行（Durable Execution）

長く走るエージェント処理が途中で落ちたとき、最初からやり直すのは現実的ではありません。公式ドキュメントは「Durable execution on nine engines」と記載し、対応エンジンとしてTemporal、DBOS、Prefect、Restate、AWS Lambdaなどを挙げています。対応状況は更新されるため、採用を検討する段階で公式の該当ページを確認してください。

ここは案件によって要否がはっきり分かれる領域です。社内の問い合わせボット程度なら不要。数十分かかるバッチ処理をエージェントに任せるなら、検討対象に入ります。

Pydantic AIの使い方｜最小構成から実務構成へ

結論から言うと、最小構成は「モデル指定」「出力型の定義」「実行」の3つだけです。そこにツールと依存を足し、最後に観測と評価を載せる。この順番で組み立てるのが素直です。

インストールと最小サンプルの確認

導入はPyPIのパッケージを入れるだけです。パッケージマネージャにuvを使っているなら「uv add pydantic-ai」、pipなら「pip install pydantic-ai」が入口になります。

ここで注意したいのは、ブログ記事のコードをそのまま貼らないことです。更新頻度が高く、引数名やAPIがバージョン間で変わります。公式ドキュメントの最小サンプルを起点にし、自分が入れたバージョンの記述と照合してから書き始めてください。この順番を守るだけで、初日のつまずきはかなり減ります。

STEP1｜エージェントを定義して構造化出力を受け取る

まずAgentオブジェクトを作ります。多くの例では、使うモデルを示す文字列と、出力の型を渡します。出力型にはPydanticモデルを指定します。モデル文字列の指定形式はプロバイダやバージョンで変わる可能性があるため、実装時は公式ドキュメントのモデル指定例を確認してください。

実行は同期・非同期どちらも用意されています。返り値のoutput属性を見ると、そこには文字列ではなく、指定した型のオブジェクトが入っています。ここまでで、JSONのパース処理は1行も書いていません。

最初の一歩としては、既存の業務で手作業になっている分類処理を題材にするのが分かりやすい。問い合わせ文面を「カテゴリ」「緊急度」「要約」の3フィールドに落とす、といった粒度です。

STEP2｜ツールと依存性注入を足す

次に、エージェントから外部を触らせます。デコレータで関数を登録すると、モデルが判断して呼び出すようになります。

ここで重要なのは、ツールの中で使うリソースを引数経由で受け取ることです。実行時に依存オブジェクトを渡し、ツール側は実行コンテキストからそれを取り出す。この形にしておくと、単体テストで本物のDBを立てる必要がなくなります。

STEP3｜観測と評価を最初から入れる

後回しにすると苦労する部分です。OpenTelemetryの計装を有効にし、トレースを送る先を決めておく。あわせてPydantic Evalsで、代表的な入力に対する期待出力を数件でも用意しておきます。

なぜ最初かというと、LLMアプリは「壊れたことに気づけない」形で劣化するからです。例外は飛ばず、ただ精度が落ちる。モデルのバージョンが変わった日に、評価セットがないと何も言えません。運用面の全体像はLLMOpsとは｜MLOpsとの違いと評価・監視・運用の実務を参照してください。

学習にかかる時間の目安

目安として、Pydanticと型ヒントに慣れている人なら、最小構成（エージェント定義・構造化出力・ツール1本）は半日程度で動かせます。依存性注入とテストまで含めた実務構成に落とすと、1〜2日見ておくと安全です。

条件はあります。LLM API自体がはじめてなら、モデル選定やトークンコストの感覚をつかむ時間が別途必要です。逆にLangGraphやOpenAI Agents SDKの経験があるなら、概念の対応付けだけなので数時間で読み替えられます。

ミニFAQ｜実装時に最初に迷うところ

出力型はどこまで細かく定義すべきですか。

最初は粗くてかまいません。フィールドを増やすほどモデルの負荷と失敗率が上がるため、必要な項目だけから始めて、運用しながら足すほうが安定します。

ストリーミング表示はできますか。

対応しています。ただし構造化出力とストリーミングを同時に扱うと、途中の不完全な状態をどう画面に出すかという設計判断が発生します。UI要件を先に固めてから実装順を決めてください。

V1とV2の違い｜capabilities中心の再設計

V2は2026年6月23日に安定版となりました。公式のリリースノートは「After seven betas, Pydantic AI V2 is now stable.」とし、設計方針をharness-firstと説明しています。

harness（ハーネス）は、エージェントを動かすための土台や足回りを指す言葉です。個々のエージェント実装よりも、実行・拡張・観測・評価を支える仕組みのほうを先に設計する方針だと捉えると、V2の変更点が読みやすくなります。

V2で中心に置かれた「capability」という単位

capabilitiesのドキュメントは、capabilityを「A reusable, composable unit of agent behavior.」と定義しています。従来は個別の引数として渡していた要素を、ひとつの単位にまとめて扱えるようにしたものです。

公式は「This makes them the primary extension point for Pydantic AI.」と書いています。拡張の入口がここに一本化された、と読めます。

実務的な意味は、社内で共通化したいエージェントの振る舞いを、部品として配れることです。たとえば「全エージェントで同じ監査ログを残す」「社内APIツール群をまとめて付与する」「モデル設定を開発環境と本番環境で切り替える」といった共通処理を、個別の実装から切り出せます。各エージェントに同じコードを書き写す必要がなくなる、と言い換えてもいいです。

既存案件でv1系に当たったときの注意

ここは参画前に確認しておきたい部分です。v1系は本記事執筆時点でもリリースが続いており、GitHubのReleases上ではv1.107.10が2026年11月4日に公開されています。つまり、v1のまま動いている本番システムは普通に存在します。なお保守方針は変わる可能性があるため、参画時には公式のリリース状況を必ず確認してください。

注意点が2つあります。

ひとつは、ネット上の解説記事の多くがv1前提だということ。v1.0の安定版公開が2025年9月5日で、v2.0が2026年6月23日ですから、記事の蓄積量には差があります。コードをそのまま持ってきて動かない場合、まず対象バージョンを疑ってください。

もうひとつは、移行の工数を軽く見積もらないことです。capabilities中心への再編は拡張ポイントの整理を含むため、独自のフックやツール管理を作り込んでいる現場ほど影響が出ます。参画時には、移行計画の有無と、どのバージョンを前提に開発するのかを必ず確認しておきましょう。

他フレームワークとの違いと選び分け

結論を先に書きます。制御フローの複雑さが主題ならLangGraph、出力の正しさとPythonアプリ統合が主題ならPydantic AI。まずはこの一軸で絞り、そのうえで既存資産・チームの使用言語・クラウド制約・運用体制・セキュリティ要件を確認すると判断しやすくなります。

LangGraphとの違い

LangGraphは、エージェントの処理を状態遷移グラフとして明示的に書くフレームワークです。分岐・ループ・途中停止といった制御を自分で設計したい場合に向きます。

対してPydantic AIは、エージェントループ自体は標準的なものを提供し、入出力の型と拡張ポイントに力点を置いています。どちらが優れているという話ではなく、作りたいものの重心が違います。詳細はLangGraphとは｜LangChainとの違い・エージェント構築の基本にまとまっています。

OpenAI Agents SDKとの違い

OpenAI Agents SDKもPython製で、エージェント定義とツール、ハンドオフを扱います。差が出るのはモデルの選択肢と型の扱いです。

Pydantic AIはプロバイダ非依存を前面に出しており、出力検証がフレームワークの中核にあります。OpenAI中心の構成で完結するなら公式SDKの素直さが効き、複数プロバイダを跨ぐ、あるいは出力の型保証を厳しくしたいならPydantic AIが噛み合います。比較はOpenAI Agents SDKとは｜使い方とLangGraphとの違いもあわせてどうぞ。

LangChainとの関係

競合というより、レイヤーが違います。LangChainは連携先の広さとエコシステムが強みで、Pydantic AIは出力の確からしさとアプリ統合が強みです。既存のLangChain資産があるなら、無理に置き換える理由は薄い。新規でPython製の業務アプリに組み込むなら、Pydantic AIのほうが依存は軽くなります。

TypeScript中心のチームなら

Pydantic AIはPython専用です。フロントエンドと同じTypeScriptで統一したいなら、Mastraとは｜TypeScript製AIエージェントフレームワークの使い方が選択肢になります。言語の選択は、チームの運用能力で決めるのが結局いちばん堅い。

選定早見表

3つ以上のフレームワークを横断で比べたい場合は、AIエージェント開発フレームワーク比較｜LangGraph・CrewAI・AutoGenに判断フローを置いています。本記事はその比較記事でカバーしていないPydantic AI単体の解説という位置づけです。

向かない場面も書いておく

• ノーコードで完結させたい場合。Pydantic AIはコードを書く前提のフレームワークです。

• エージェントの思考過程そのものを細かく設計したい場合。グラフとして書きたいならLangGraphのほうが素直です。

• Pythonを使わない場合。言語の制約は回避できません。

フリーランス視点で見た案件での位置づけ

フリコンの掲載案件と主要フリーランスエージェントの公開案件を、2026年11月時点でフレームワーク名のキーワードで確認した範囲では、「Pydantic AI」と名指しされた案件はまだ目立ちません。名前が挙がる頻度としては、LangChain系やクラウド各社のAI基盤のほうが依然として多い状況です。

一方で、スキル要件に「Python」「FastAPI」「LLM連携」が並ぶ案件は公開案件でも見つかります。こうした案件では、実装手段としてPydantic AIのような型付きエージェントフレームワークが候補になりやすいと考えられます。これは公開案件の要件欄から読み取れる傾向であって、採用実績を集計した数字ではない点はご留意ください。

名前が挙がりやすい3つの場面

ひとつ目は、既にFastAPIで動いている業務システムに、分類・要約・抽出といったLLM機能を足す案件。既存の型定義をそのまま出力スキーマに使えるため、採用の摩擦が小さい。

ふたつ目は、出力の正しさが業務要件になっている領域です。帳票の読み取り、審査の下書き生成、データ移行の補助など。「とりあえず動く」では受け入れられない場面で、検証つきの構造化出力が効きます。

3つ目は、社内の複数チームにエージェント基盤を配る案件。V2のcapabilityが、共通要件を部品として配布する単位になります。あわせて権限まわりの設計も問われるため、AIエージェントの権限設計｜最小権限とHuman-in-the-loopの実装を押さえておくと面談で話が通じやすくなります。

単価と案件の探し方

AIエージェント開発案件の単価レンジや求められるスキルセットは、AIエージェント開発案件の単価相場｜必要スキル・獲得ルートを解説に整理しています。Python案件全体の相場観はPythonフリーランスの単価相場｜AI・データ案件の獲得ロードマップをご覧ください。

探す際は、フレームワーク名よりも「Python」＋「LLM」「生成AI」の組み合わせで絞ったほうが母数が取れます。フリコンのPython案件一覧から、業務内容に生成AI連携が含まれるものを拾っていくのが現実的な進め方です。

自分がどのくらいの単価を狙えるか気になる方は、無料のフリーランスエンジニア単価診断で、入力したスキル・経験年数をもとにした単価の目安を確認できます。あくまで目安で、実際の金額は商流・稼働日数・契約条件で変わります。単価を体系的に上げる考え方は【2026年最新版】フリーランスエンジニアの単価相場と単価の上げ方とは？で整理しています。複数の案件を比べる段階に入ったら、案件の選び方｜フリーランスエンジニアが単価・稼働・スキルで決める優先順位の判断軸が使えます。

よくある失敗と対策

出力型を最初から作り込みすぎる

フィールドを20個も並べたモデルを初手で定義すると、検証失敗とリトライが頻発します。必要な項目から始めて、運用しながら足す。入れ子構造が深いモデルも、失敗率を押し上げる要因になります。

リトライ任せにしてコストが膨らむ

検証失敗時の再実行は便利ですが、そのぶんトークンを消費します。リトライ回数の上限を明示し、失敗が多いならプロンプトか出力型のほうを直す。リトライは最後の安全網であって、精度を上げる手段ではありません。

観測を後から入れようとする

前述のとおり、LLMアプリは静かに劣化します。計装は最初に入れる。これは工数の問題ではなく順番の問題です。

v1前提の情報をv2に当てはめる

検索で出てくるコードが動かない場合、コードが間違っているのではなくバージョンが違うだけ、というケースが少なくありません。v2.0の安定版公開は2026年6月23日です。参照している記事の公開日とバージョン表記を必ず確認してください。

「型があるから安全」と考える

型が保証するのは構造であって、内容の正しさではありません。正しい形式で間違った値が返ることは普通にあります。誤りを減らす設計についてはLLMのガードレールとは｜出力制御の実装パターンとツール選定もあわせて検討してください。

導入前チェックリスト

案件で採用を検討する、あるいは参画前に確認するときの観点です。

このうち上4行が埋まれば、採用可否はだいたい判断できます。

まとめ

Pydantic AIは、LLMの出力を型で受け取って毎回検証するという一点に軸を置いたPython製エージェントフレームワークです。制御フローの自由度を求めるならLangGraph、出力の確からしさと既存Pythonアプリへの統合を求めるならPydantic AI。この軸で選べば大きく外しません。

要点を整理します。

• 開発元はPydanticチーム。MITライセンスのOSSで、GitHubのスターは2026年11月15日時点で約21,200

• v1.0安定版は2025年9月5日、v2.0安定版は2026年6月23日。執筆時点の最新はv2.68.0

• V2はcapabilityを中核に据えた再設計。共通の振る舞いを部品として配れる

• 主要機能は構造化出力・モデル非依存・型付き依存性注入・MCP・OpenTelemetry計装・Pydantic Evals・9エンジンの耐久実行

• 学習の目安は、Pydanticに慣れていれば最小構成で半日、実務構成で1〜2日

• v1系の保守も続いているため、案件参画時は前提バージョンと移行計画を確認する

次の一歩としては、公式ドキュメントのサンプルを動かし、手元の業務で分類や抽出にあたる処理をひとつ置き換えてみるのが早いです。そのうえで観測と評価を足せば、そのまま案件で通用する構成になります。

参照した一次情報は以下のとおりです。

• Pydantic AI 公式ドキュメント

• Capabilities（V2の中核概念）

• pydantic/pydantic-ai（GitHub）

• Pydantic 公式ドキュメント