Pydantic AIとは？Python向けAIエージェントフレームワークの使い方

本記事は2026年10月17日に、開発元のドキュメントとリポジトリのライセンスを確認しています。ここでの判断軸は性能ランキングではなく、出力の検証、アプリケーション内のサービスへのアクセス、ワークフローをどこで管理するか、そして障害からの復旧です。

AIエージェントフレームワーク「Pydantic AI」とは？

Pydantic AIは、Pydanticチームが開発するPython向けエージェントSDKです。 モデル、指示、呼び出し可能なPython関数、必要に応じて指定する出力型を、アプリケーションが実行するAgentというオブジェクトにまとめます。回答を生成するのがモデルで、その前後のやり取りを管理するのがSDKです。現在の概要ページでは、さらに広い範囲のSDKとして紹介されていますが、プロダクトの機能に組み込むうえでの核はこの部分です。

動きが予測しきれない協力者に、関数の入出力ルールを渡すイメージです。アプリケーション側がコンテキストと許可する操作を用意し、名前付きフィールドを持つ結果を求めます。たとえば、サポート機能が問い合わせの分類と次の対応を出力し、それを通常のPythonコードで処理したい場合に役立ちます。

Pydantic AIのAgentは何を再利用するのか

Agentは、ある仕事を行うための設定を保持します。実行（run）は、その仕事に対してプロンプトと実行時の依存オブジェクトを渡し、実際に処理を試みる単位です。同期スクリプトではrun_sync()、非同期のアプリケーションコードではawait agent.run()を呼び出せます。処理が完了すると、結果の.outputから最終的な値を取得できます。これらはAgent APIのドキュメントで説明されています。

ここで型には、異なる役割が2つあります。静的な型付けは、エディタや型チェッカーがPythonコード内の不整合を見つけるためのものです。一方、実行時の出力検証は、モデルが返したデータを宣言済みのスキーマに照らして確認します。どちらも、曖昧な問い合わせの意味そのものを明確にしてくれるわけではありません。

ツール関数にアプリケーションのコンテキストを渡す

関数ツールを使うと、契約プランの照会など、コードで実行できる処理をモデルから要求できるようになります。実行コンテキストを使う関数は@agent.toolで登録し、コンテキストが不要なら@agent.tool_plainを使います。型ヒントが引数を定義し、docstringがモデルにツールの用途を伝えます。これらがどのようにツールのスキーマになるかは、関数ツールのドキュメントで確認できます。

依存性注入とは、実行に必要なサービスを、その実行に渡すことです。 deps_type=CustomerContextで想定するPythonの型を宣言し、deps=customer_contextで実際のインスタンスを渡します。ツールはRunContext[CustomerContext]を受け取り、ctx.depsを通じて参照します。認証済みの顧客情報、データベース接続、APIクライアントなどを、このコンテキストに持たせられます。依存関係のガイドにも、deps_typeは型チェックを支援するものであり、依存オブジェクトを実行時に検証するものではないと明記されています。

SaaS開発では、この仕組みの利点がはっきりします。モデルが情報の照会を要求する前に、サーバー側で対象の顧客アカウントを決められるからです。ただし、認可の確認は照会を行うコードに残してください。型付きコンテキストでデータベースクライアントを渡しても、そのクライアントが読み取れる行は制限されません。

Pydantic AIの構造化出力は何を検証するのか

output_typeは、アプリケーションが受け取りたい結果を定義します。 型付きフィールドを持つPythonクラスであるPydanticのBaseModelを指定すると、Pydantic AIがスキーマを生成し、モデルの生成データを検証します。出力のドキュメントでは、dataclass、リスト、ユニオンなど、ほかの型への対応も説明されています。

3つの出力モードでは、モデルにデータを生成させる方法が異なります。

これはSDKに定義されている3つの出力モードであり、精度を3段階に分けたものではありません。モデルが対応する仕組みを選び、そのうえで対象のタスクにおける結果を評価してください。

検証に失敗した場合は、その内容をモデルに返して再試行させられます。ただし、再試行回数には上限があり、出力の再試行を使い切るとUnexpectedModelBehaviorが発生することがあります。不足情報を尋ねる、人に引き継ぐといった失敗時の処理を、アプリケーション側で用意する必要があります。詳しくは再試行の挙動を参照してください。

Pydantic AIの使い方：検証済みの問い合わせ分類を返す

エージェントに変更操作を許可する前に、読み取りだけで判断結果を返すところから始めましょう。 次の例は、ドキュメントにあるAgent、RunContext、output_typeの使い方を、小さな問い合わせ振り分けタスクに応用したものです。

現在のインストールガイドでは、Python 3.11以降が必要です。仮想環境でライブラリをインストールします。

python -m pip install pydantic-ai

対象モデルを利用できるアカウントのOPENAI_API_KEYを環境変数に設定してください。以下をtriage.pyとして保存し、python triage.pyを実行します。モデル識別子は現在のAgentドキュメントに合わせています。自分のアカウントで利用できる、対応済みのモデルに置き換えてもかまいません。

from dataclasses import dataclass
from typing import Literal

from pydantic import BaseModel
from pydantic_ai import Agent, RunContext

@dataclass
class Customer:
    plan: str

class Triage(BaseModel):
    category: Literal['billing', 'technical']
    priority: Literal['normal', 'urgent']
    summary: str

agent = Agent(
    'openai:gpt-6.1-sol',
    deps_type=Customer,
    output_type=Triage,
    instructions=(
        'Triage the support message. Use customer_plan for context. '
        'Summarize the issue without inventing account facts.'
    ),
)

@agent.tool
def customer_plan(ctx: RunContext[Customer]) -> str:
    """Return the authenticated customer's plan."""
    return ctx.deps.plan

if __name__ == '__main__':
    result = agent.run_sync(
        'I was charged twice for my subscription.',
        deps=Customer(plan='business'),
    )
    print(result.output.model_dump())

正常に実行できると、result.outputはTriageオブジェクトになります。分類と優先度は、宣言した選択肢に一致する必要があります。model_dump()を使うと、そのオブジェクトを辞書に変換できます。この例のコンテキストツール、型付きの結果、不正な分類値が拒否されることは、TestModelを使ってオフラインで確認済みです。モデルが生成する文面や振り分けの精度は、実際の自分のケースで評価する必要があります。

この顧客コンテキストは説明用です。プロダクトでは、認証済みのリクエストとアカウントの記録から組み立ててください。また、どのような場合に緊急とするかも定義します。スキーマが列挙しているのは有効なラベルだけで、緊急度を判断する方針は含まれていません。エージェントを増やすよりも、まずこの業務ルールを補うことが大切です。

モデルを切り替えても、同じ挙動になるとは限りません

Pydantic AIはプロバイダーごとの接続処理を減らしますが、モデルを変えれば挙動も変わります。 多くの接続先では<provider>:<model>形式の識別子を使います。一方、モデルやクライアントの明示的な指定、適切な認証情報、追加パッケージのインストールが必要なものもあります。プロバイダー一覧にもあるとおり、使える機能は選んだモデルとAPIによって異なります。

一覧にはOpenAI、Anthropic、Google/Gemini、AWS Bedrock、Groq、Mistral、xAI、Ollamaが含まれています。そのほか、次の接続先もドキュメントに記載されています。

• モデル・推論サービス： Alibaba Cloud/Qwen、Cerebras、Cohere、Crusoe、DeepSeek、Fireworks AI、Heroku AI、Hugging Face、Meta、Moonshot AI/Kimi、Nebius AI Studio、OVHcloud AI Endpoints、SambaNova、Snowflake Cortex、Together AI、Z.AI。
• クラウド、ゲートウェイ、セルフホスト： Google Cloud/Vertex AI、Microsoft Azure/Foundry、Pydantic AI Gateway、LiteLLM、OpenRouter、Vercel AI Gateway、vLLM。
• その他のアクセス手段・意思決定モデル： GitHub Copilot、OpenAI Codex、OpenAI Decisions API、System One API、TypeSafe (Jev)。

これらの名前が示すのは、モデルにアクセスするさまざまな方法です。同じ機能をそのまま使えるという意味ではありません。ローカルモデルとホスト型の最先端モデルでは、ツールの扱いが異なることがあります。互換APIであっても、スキーマに課される制約が同じとは限りません。

事業を立ち上げる側にとって、モデルを切り替えられることは、特定のサービスから移行する余地と実験の自由につながります。ただし、実装する開発者が確認すべきことは変わりません。同じケースに対して、移行先のモデルが適切なツールを選び、出力スキーマを守り、許容できる判断を返すかどうかです。本番の標準モデルを変える前に、その検証結果を残してください。

MCPと永続実行：ツールへの接続と進捗の保存

MCPはエージェントをツールサーバーに接続し、永続実行は中断後も処理を続けられるようにします。 解決する課題はそれぞれ異なります。

Model Context Protocol（MCP）は、アプリケーションがツールやコンテキストをAIクライアントに公開する方法を標準化するプロトコルです。Pydantic AIのMCP機能では、サーバーURLのほか、クライアントやツールセットを指定できます。対応している場合は、プロバイダーが提供するネイティブのMCP機能も利用できます。エージェントごとに新しい連携処理を書かずに、ツールサーバーを再利用するための仕組みです。どの顧客にそのサーバーの操作を許可するかは、MCPが決めるわけではありません。

永続実行とは、進捗を保存し、障害、再起動、長い待機時間を経ても処理を続けられるようにすることです。現在の永続実行のドキュメントには、9つのソリューションが挙げられています。

• 各ベンダーのチームと共同で保守： Temporal、DBOS、Prefect、Restate、AWS Lambda。
• 外部SDKによる連携： Kitaru、Apache Airflow、Absurd、pgtask。

ほかのエンジン向けにバックエンドを構築する仕組みもあります。エージェントを開始したリクエストやプロセスが終了した後も処理を続ける必要があるなら、ドキュメントにある連携方法を選んでください。連携機能が用意されているからといって、Agentを単に呼び出すだけで永続実行の運用環境ができるわけではありません。

返金を提案し、承認を待ってから実行するサポート業務を考えてみてください。実行状態を保存すれば、承認待ちの仕事を保持できます。しかし、決済処理には引き続き冪等性が必要です。同じリクエストを繰り返しても、返金が重複してはいけません。実行済みの操作をどう識別するか、結果が不明な場合にどう照合して確定するかを決めておきます。これはエンジンの導入とあわせて、アプリケーション側が担う責任です。

Pydantic Evalsで、出力の形式だけでなく判断を評価する

Pydantic Evalsは、出力をパースできるかだけでなく、エージェントの仕事が許容できるものだったかをテストします。 コードを中心に評価を定義する独立したパッケージで、Pydantic AIは必須ではありません。ケースと評価器を定義し、それらに対してタスクを実行してレポートを確認します。ドキュメントでは、最終出力に加え、実行中にどのような順序でツールを呼び出したかという行動の流れも評価対象にしています。

問い合わせ振り分けの例なら、二重請求、ログイン失敗、アカウントのコンテキスト不足、アシスタントに指示を無視するよう求めるメッセージをケースにします。分類、エスカレーションの判断、必要なアカウント照会が実行されたかを確認してください。追加の質問を返すことが適切なケースも含めます。

運用では、トレースで個々の実行を説明し、評価で複数のケースにわたる挙動を測ります。 Pydantic AIは、アプリケーションのテレメトリー標準であるOpenTelemetryを使用し、計測機能を通じてほかの可観測性バックエンドにも対応しています。ケースが失敗したら、モデルへのリクエストとツール呼び出しを調べ、そのケースを評価セットに残します。

任意で利用できるPydantic Logfireは、エージェント、モデル、ツールのトレースを提供します。料金ページによると、Personalプランは無料、Teamプランは月額$49からで、追加の利用量とシートには別途料金がかかります。

ほかのフレームワークよりPydantic AIを選ぶのはどんなときか

機能の実装で何が難しいのかに合わせて、抽象化の仕組みを選びます。 既存のドメインモデルやサービスを持つPython開発者なら、型付きの入力、ツール、出力をつなぐことが主な課題のときにPydantic AIを候補に入れるとよいでしょう。技術に詳しい創業者が考えるべきなのは、どの選択なら、事業側が説明でき、保守できる運用システムを最小限にできるかです。

Pydantic AIとLangGraphの違い

エージェントを取り巻くワークフローを明示的に設計したいなら、LangGraphを出発点にするほうが適しています。 ドキュメントの中心は、長時間稼働して状態を保持するエージェント、永続実行、人による介入です。情報を集め、承認を得て、許可された操作を実行し、結果を照合する、といった必須の段階を持つアプリケーションを想像するとわかりやすいでしょう。

アプリケーションがすでに制御している処理の中に、型付きエージェントを部品として組み込むなら、Pydantic AIが有力です。Pydantic AIも永続的なワークフローに組み込めるため、状態を永続化したいという理由だけでは選択は決まりません。判断の分かれ目は、エージェントの周囲にある業務プロセスをモデル化したいのか、主にエージェント自身の挙動を設定したいのかです。LangGraphでは、ワークフローの設計と状態管理を自分で担う必要があります。Pydantic AIでは、エージェントの入出力を手軽に定義できても、プロセス全体の設計までは任せられません。

Pydantic AIとLangChainの違い

既存のモデル・ツール連携やエージェントの構成がアプリケーションに合うなら、LangChainは自然な選択です。 LangChainの概要によると、LangChainのエージェントはLangGraph上に構築されています。そのため、より高水準のエージェントAPIを選んでも、その実行基盤がなくなるわけではありません。

依存関係と出力の定義方法が、普段のコードの書き方に合うPythonサービスなら、Pydantic AIを選ぶ理由になります。すでに動いているLangChainの機能は、移行で取り除ける複雑さを具体的に説明できる場合を除き、維持するのがよいでしょう。処理がエージェント層とワークフロー層をまたぐときは、LangChainが何を抽象化しているのかを理解する必要があります。ライブラリを変えるだけでは、その作業の場所が移るにすぎません。両者の関係はLangChainとLangGraphの比較で詳しく扱っています。

OpenAI Agents SDKとAPIの直接呼び出しはどう選ぶか

ツール、ハンドオフ、トレースを備えたエージェントの処理ループをアプリケーション側で動かすなら、OpenAI Agents SDKが適しています。 SDKはアプリケーション内で動作し、構造化出力に対応しています。プロバイダーインターフェースでは、OpenAI以外のモデルも扱えます。型付き出力やプロバイダーの選択肢を、Pydantic AIだけの特徴と考えるのは正確ではありません。

今後保守していくOpenAI連携に、そのSDKのエージェントとハンドオフの仕組みが合うなら、OpenAI Agents SDKを選びます。Pythonの依存関係の扱いやプロバイダー設定がより合うなら、Pydantic AIを選んでください。どちらの場合も、デプロイ、ツールの認可、アプリケーションとしての正しさは開発側の責任です。

モデルへのリクエストと、その前後の少量の決定論的な処理だけで済む仕事なら、APIを直接呼び出しましょう。 APIを直接使っても、すでにスキーマで制約された出力を返せます。レシートから情報を抽出する機能に、結果がPydanticオブジェクトだからという理由だけでエージェントフレームワークを導入する必要はありません。ツールの呼び出しループ、検証の再試行、計測処理を機能ごとに何度も作り直すようになったら、直接呼び出しの限界を考えるタイミングです。

より広い選択肢については、AIエージェントフレームワークのガイドを参照してください。明示的なワークフロー制御と、専門の役割を持つエージェントのどちらを重視するかが決まらない場合は、LangGraphとCrewAIの比較が次の読み物になります。

型付きエージェントに期待しすぎてはいけないこと

型付きエージェントを使えば、自動的に正しく動く本番システムになる、という期待は行きすぎです。 ライブラリでは解消できない境界がいくつかあります。

• 型安全性は、事実の正確さを保証しません。 形式が整った回答でも、ユーザーの依頼を読み違えることがあります。信頼できる記録と照合すべき項目を決めてください。
• モデルを切り替えられても、品質が同じとは限りません。 新しいプロバイダー設定には、新しいプロンプトと同じようにタスクの評価が必要です。
• 永続実行に対応していても、運用環境は自動で整いません。 機能に必要なエンジン、ストレージ、復旧手順を選び、運用する必要があります。
• 再試行には追加の処理が発生します。 モデルへのリクエストが増えると、待ち時間と利用量も増えます。再試行を使い切ったときにアプリケーションがどう処理するか、明示的に決めておきましょう。

次に作るPythonの機能が、すでにツールと構造化された判断結果を必要としているなら、導入を進める理由があります。既存のシステムが動いていて、移行の利点がデモコードの見栄えだけなら、フレームワークの移行は待つべきです。十分な検証とエラー処理を備えた、単純な情報抽出の呼び出しで済む機能なら、大きな影響はありません。

Pydantic AIのよくある質問

来週のリリースに向けて、何から始めるか

エージェントに任せる範囲を広げる前に、小さな読み取り専用の機能で、受け入れ条件を明確にしましょう。 サポート製品なら、例で示した問い合わせ分類のオブジェクトから始め、アカウントに対する最終的な操作は通常のアプリケーションコードに残します。

AI機能の開発に役立つ実践的な情報は、ニュースレターでお届けしています。