pydantic-ai

Pydantic AI

「FastAPI のような感覚」で本番環境向けの GenAI アプリケーションを構築するための Python エージェントフレームワークです。

クイックナビゲーション

トピック	リファレンス
エージェント	agents.md
機能	agents.md
ツール	tools.md
モデル	models.md
埋め込み	embeddings.md
評価	evals.md
インテグレーション	integrations.md
グラフ	graphs.md
UI ストリーム	ui.md
インストール	installation.md

使用する場面

• 構造化出力を使う AI エージェントを構築する場合
• 型安全で IDE に適したエージェント開発が必要な場合
• ツールに依存性注入が必要な場合
• 複数のモデルをサポートする場合（OpenAI、Anthropic、Gemini など）
• Logfire による本番環境でのオブザーバビリティが必要な場合
• グラフを使った複雑なワークフローが必要な場合

インストール

フルインストール／スリムインストールのオプションと、オプションの依存関係グループについては、references/installation.md を参照してください。Python 3.10 以降が必要です。

リリースの主な内容（2.40.0 -> 2.48.0）

• セキュリティ（アップグレード）（2.44.0、1.107.6 にバックポート）：web_fetch_tool または OTel のインストルメンテーションを介して到達可能な 4 件の修正です。ローカル URL が許可されている場合の、IPv6 のゾーン識別子によるプライベート IP ブロックリストの回避、イベントループを停止させる可能性があった web_fetch の HTML／文字セット処理の超線形的な計算量、リゾルバーによる正規化を行わずに比較されていたドメインブロックリスト、include_content=False の場合のスパン内容の漏えいに対応しています（GHSA-vmxc-h2x2-jmf3、GHSA-fpf4-vwcp-v4hp、GHSA-22h6-qm39-v87j、GHSA-4x9p-g9wm-8q7f）。
• リアルタイムセッション制御（2.40.0／2.46.0）：handle_barge_in=True と interrupt(played_bytes=...)、帯域外プロンプト用の RealtimeSession.enqueue()、send() の respond=、wait_for_playback()、および @agent.on_event リスナーに対応しました。
• 画像生成（2.41.0）：組み込みツールに加えて、直接利用できる ImageGenerator API を追加しました。ImageGeneration／XSearch の fallback_model は非推奨となり、fallback_subagent_model が推奨されます。
• プロバイダーとモデル（2.41.0／2.42.0／2.48.0）：ChatGPT／Codex のサブスクリプション認証に対応する openai-codex プロバイダーと GitHubCopilotProvider、および OpenAI の gpt-6-sol／gpt-6-luna と Claude Opus 5.5（claude-opus-5-5）に対応しました。
• 料金（2.40.0）：pydantic_ai.prices.update_in_background() により、genai-prices のデータをバックグラウンドで更新できます。
• Temporal（2.46.0）：TemporalDurability の event_stream_topic により、Workflow Streams を介してエージェントのイベントをストリーミングできます。

リリースの主な変更点（2.23.0 -> 2.39.0）

• リアルタイム音声間通信（2.28.0）：ブラウザーの WebRTC とサーバー側サイドバンドに対応した Agent.realtime()、azure_voice_live 設定による Azure AI Voice Live（2.29.0）、非同期イテラブルを受け付ける RealtimeSession.send_audio()（2.36.0）。
• 実行のキャンセル（2.26.0）：AgentRun.cancel()、RunContext.cancel()、RunCancelled。stream_run_events() は、cancel() と実行状態へのアクセスを備えた公開の AgentRunEvents ハンドルを返します。
• ツールの遅延公開（2.23.0／2.26.0／2.30.0）：ネイティブの tool_addition／additional_tools に対応した ToolAvailabilityDeltaPart。ツールは、各プロバイダーのネイティブな遅延公開／追加チャネルを通じて、ツール検索、load_capability、または ToolReturn.tools によって公開されるまで非表示にできます。遅延公開されたツールは、呼び出す前に公開する必要があります。
• コストの追跡（2.23.0）：RunUsage の cost と UsageLimits の cost_limit。コンテキストウィンドウ（2.38.0）：ModelProfile の context_window と RunContext の context_window_used。
• 型付きイベント（2.38.0）：アプリケーションコードとケイパビリティは、型付きの CustomEvent／CapabilityEvent を実行イベントストリームに送信し、@on_event でサブスクライブできます。永続的な実行（2.36.0）：ケイパビリティ向けの @durable_operation と、サードパーティ製の永続実行エンジン向け公開バックエンド API。
• プロバイダーとモデル：Crusoe（2.28.0）、Snowflake Cortex（2.27.0）、vLLM（2.38.0）の各プロバイダー。gemini-3.7-flash（2.30.0）、gemini-3.8-flash（2.38.0）、Claude Fable 5.1／Mythos 5.1（2.38.0）、OpenAI gpt-6-astra（2.39.0）、ZaiModel の GLM-5.3（2.34.0）、DeepSeek V4 Flash（2.26.0）。
• MCP および HTTP クライアント：MCPToolset は FastMCP 3 に加えて、FastMCP 4 と MCP SDK v2 に対応します（2.29.0）。ビルドでは httpx2 クライアントに移行しました。pydantic-ai[anthropic] には anthropic>=1.0.0 が必要で、カスタムの AnthropicProvider の http_client には httpx2.AsyncClient を指定する必要があります（2.32.0／2.33.0）。
• clai CLI（2.36.0）：--mcp-config とツール呼び出しのストリーミングに対応。OpenRouter（2.30.0／2.32.0）：ウェブ検索用の openrouter:web_search と、provider_details["annotations"] 内のウェブ検索ソースに対応。
• セキュリティ（アップグレード）：2.24.0 では、ローカルの web_fetch ツール／FileUrl によるメディアのダウンロードでメモリ使用量が無制限になる問題を修正しました（GHSA-v2xh-2vp8-57h8）。2.27.1 では、include_content=False の場合にリトライ用プロンプトの秘匿化が漏れる低深刻度の問題を修正しました（GHSA-3gh4-cghq-f8v4）。2.28.0 では、開発用ウェブチャット UI で Content-Type の検証が欠けていた高深刻度の問題を修正し、任意のクロスオリジンリクエストによってエージェントが実行されないようにしました（GHSA-h4xc-3qfq-jf93）。2.30.0 では、開発用ウェブチャット UI に Host ヘッダーの検証を導入して DNS リバインディングを修正し、ループバック以外のデプロイメント向けにオプトインの allowed_hosts を追加しました（GHSA-q2xc-rrxj-58x9）。

リリースの主な変更点（2.13.0 -> 2.22.0）

• 耐久性機能がラッパーエージェントに置き換わりました：TemporalDurability、DBOSDurability、PrefectDurability（2.14.0）は、capabilities=[...] を介して通常の Agent に追加でき、非推奨となった TemporalAgent / DBOSAgent / PrefectAgent ラッパークラス（v3 で削除）に置き換わります。既存のラッパーを使ったワークフローは、切り替え後も正しくリプレイされます。更新された Temporal／DBOS／Prefect の例については、integrations.md を参照してください。
• 新しいモデル／プロバイダー：Claude Opus 5（2.20.0）、gemini-3.6-flash／gemini-3.5-flash-lite（2.16.0）、Mistral の reasoning_effort（2.14.0）と mistral_prompt_cache_key（2.16.0）、gpt-5.6 向け OpenAI の明示的なプロンプトキャッシュ（2.15.0）、BedrockMantleProvider（2.18.0）、Anthropic／OpenRouter 向け組み込みツール AdvisorTool（2.18.0）。
• 使用状況と制限：RequestUsage／RunUsage の cache_hit_ratio（2.13.0）、リトライを消費しないモデルから確認可能な失敗を扱う ToolFailed（2.16.0）、実行時に指定できる省略可能な run_id=（2.16.0）、run／iter／override 時のツール再試行予算の上書き（2.15.0）、UsageLimits の per_request_input_tokens_limit（2.21.0）。
• エラー処理と計測：ModelHTTPError に、各プロバイダーの SDK から取得した headers と解析済みの retry_after が含まれるようになりました（2.19.0）。RaiseContentFilterError 機能と include_model_request_parameters 計測設定（2.13.0）。メッセージごとの OTel シリアライズをキャッシュし、O(n^2) のコストを回避します（2.17.0）。
• 依存関係：fastmcp オプショングループで fastmcp<4 が制約されるようになりました（2.19.0）。

リリースの主な変更点（2.0.0 -> 2.12.0）

• V2 の安定版（2.0.0）：ハーネスを中心とした設計で、機能を中核的なプリミティブとしています。エージェントのツール、フック、指示、モデル設定をまとめた、単一の組み合わせ可能な単位です。V1 からの移行には公式アップグレードガイドが必要です。1.9x 系を通じて非推奨となった機能ベースの方法が、標準の方法になりました。
• メッセージ履歴と処理：message_history がツール呼び出しのペアリングを修正したうえでプロバイダーに対応し、HistoryProcessor がエクスポートされました。また、遅延ツール呼び出しイベントと EnqueuedMessagesEvent が利用できるようになりました（2.10.0 から 2.12.0）。
• 新しいモデル／プロバイダー：Moonshot AI の kimi-k3、OpenAI のバックグラウンドモード、Anthropic の stop_reason=pause_turn 対応。Groq、DeepSeek、Cerebras 間で推論の強度を標準化して処理します。
• 埋め込みとトークン：埋め込み向けの Gemini 2 テキストプレフィックス条件付けと、使用状況追跡における出力音声トークンの累積。
• 修正：ToolReturnPart のシリアライズでフィールドエイリアスを使用するようになりました。Anthropic／Bedrock のネイティブな出力スキーマ処理を修正し、使用量制限とツール再試行のエラーに具体的なヒントを追加しました。

リリースの主な変更点（1.96.1）

• V2 への準備：Agent(..., prepare_tools=..., prepare_output_tools=..., event_stream_handler=...) は現在、非推奨の方法です。機能ベースの移行が新しい方針です。
• 機能への移行：コンストラクターの簡易指定でこれらの動作を設定する代わりに、PrepareTools、PrepareOutputTools、ProcessEventStream 機能を使用してください。
• OpenAI の修正：最新のパッチ系列では、OpenAIResponsesModel のシステムプロンプトのロール処理と、画像生成リクエストの構成も改善されています。

リリースの主な変更点（1.97.0 -> 1.102.0）

• MCP の移行：新しい MCP 統合には MCPToolset を優先してください。FastMCPToolset と従来の MCPServer* クライアントのインターフェースは、非推奨化の対象になりました。
• Google プロバイダーの分割：GoogleProvider と GoogleCloudProvider が別々になり、モデル ID は google-gla: / google-vertex: から google: / google-cloud: に変更されます。
• ストリーミングの移行：stream_responses() から stream_response() に移行してください。新しい API は ModelResponse オブジェクトを直接返します。
• リトライの設定：従来のコンストラクターのリトライ設定より、Agent(retries=...) または AgentRetries(...) を優先してください。
• 新しいランタイムツール：ctx.enqueue() と MCP のバックグラウンドタスクにより、現在の応答ターンに無理に含めることなく、後続の作業を簡単にキューに登録できます。

リリースの主な変更点（1.105.0 -> 1.107.0）

• 新しいモデル：Claude Fable 5 と Claude Mythos 5 に対応しました（1.107.0）。さらに、Grok 4.3 の reasoning_effort と、更新された xAI モデル名にも対応しました（1.105.0）。
• 遅延読み込み：指示、ツール、モデル設定、フックを、エージェントの構築時にすべて読み込むのではなく、必要に応じて読み込めるようになりました（1.105.0）。
• モデルのイントロスペクション：known_model_names() で KnownModelName のメンバーを列挙できます（1.107.0）。
• OpenRouter のキャッシュ：OpenRouter に CachePoint とプロンプトキャッシュを実装しました（1.107.0）。
• xAI の設定：XaiProvider に api_host と timeout が追加され、seed パラメーターのマッピングにも対応しました（1.106.0）。
• セキュリティ：VercelAIAdapter の UploadedFile 処理を強化し、confused-deputy によるファイル読み取りの脆弱性に対処しました（GHSA-h7p7-w5gc-xj3w、1.106.0）。
• 修正：event_stream_handler がストリームを消費しない場合のストリーミング応答の欠落、非 Base64 のデータ URI に対する from_data_uri、Temporal の gateway/ モデル構築、GoogleModelSettings.google_cached_content のリクエスト構成、Anthropic Bedrock の message=None 開始イベント、ネイティブツール使用時の AnthropicModel.count_tokens を修正しました。

リリースの主な変更点（1.103.0 -> 1.104.0）

• MCP プロンプト：メンテナンスされている McpServer 統合で、list_prompts と get_prompt を使ってプロンプトの一覧表示と取得ができるようになりました。従来のラッパーが必要な場合を除き、新しいクライアントコードでは引き続き MCPToolset を優先してください。
• UI アダプター：VercelAIAdapter は UIMessage.metadata を通じてメッセージのタイムスタンプを保持します。また、UIAdapter.sanitize_messages は FileUrl パーツからクライアントが送信した force_download を取り除きます。
• プロバイダー／モデルの更新：Claude Opus 4.8 に対応しました。OpenRouterModel で anthropic_eager_input_streaming を使用できるほか、OpenRouter／xAI／Bedrock のハイブリッドルートで thinking=False が一貫して転送されるようになりました。
• Bedrock／ツールセットの修正：Bedrock は不正なモデル／ツール出力を FinishReason.error にマッピングし、アダプティブ思考を認識します。また、単一ツールの tool_choice のキャッシュ動作を維持し、ツールセットの準備コールバックが誤って None を返した場合に警告するようになりました。

リリースの主な変更点（1.75.0 -> 1.84.1）

• 機能：CapabilityOrdering により、複雑な機能スタックで明示的なラッピング／順序制御（innermost、outermost、wraps、wrapped_by、requires）が可能になりました。
• コンパクション：OpenAI と Anthropic に新しいサーバーサイドのコンパクション機能を追加しました。OpenAI ではステートフルなコンパクションモードにも対応しました。
• モデル：Claude Opus 4.7 に対応し、ネイティブの OllamaModel パスを追加しました。また、構造化出力に関する Ollama の機能フラグを修正しました。
• ツール：単一の BaseModel ツールでは、ツールフックが検証済み引数を一貫して辞書形式で受け取るようになりました。また、内部出力ツールではフックの実行をスキップします。
• 堅牢性の強化：1.83/1.84 系列で Google の FileSearchTool の解析を強化するため、正規表現を改良しました。

リリースの主な変更点（1.71.0 → 1.74.0）

• Capabilities：ツール、ライフサイクルフック、指示、モデル設定を単一のクラスにまとめた、組み合わせ可能で再利用可能なエージェント動作の単位です。任意のエージェントに組み込むことで、最大限に再利用できます。
• AgentSpec：Agent.from_file を使って、YAML/JSON ファイルからエージェントを読み込みます。依存関係を参照するテンプレート化された指示に対応する TemplateStr をサポートします。
• Hooks capability：デコレーター（@hooks.on_model_request など）を使ってフックを定義します。
• Thinking capability：推論に使う、プロバイダーをまたいで利用できる thinking モデル設定です。
• プロバイダーに適応するツール：WebSearch、WebFetch、MCP、ImageGeneration は、組み込みの（プロバイダー）ツールからローカルツールへ自動的にフォールバックします。
• オンライン評価：pydantic-evals の評価基盤です。
• TextContent：metadata を含むユーザープロンプトはモデルに送信されません。
• CaseLifecycle フック：Dataset.evaluate のライフサイクル用フックです。
• フックでのモデル切り替え：before_model_request フックとラップフックでは、ModelRequestContext を使ってモデルを切り替えられます。
• フックからの ModelRetry：フックから ModelRetry を発生させて、再試行の制御フローを実行できます。
• 同期ツール準備関数をサポートしました。MCP capability で url= を明示的に指定する必要はなくなりました。

リリースの主な変更点（1.69.0 → 1.70.0）

• エージェント：計装が有効な場合、Agent(description=...) によって、人が読める説明が gen_ai.agent.description として実行スパンに追加されます。
• モデル：FallbackModel が、非ストリーミング実行におけるセマンティックエラー用の応答ベースのフォールバックハンドラーに対応しました。
• ツール：マルチモーダルなツールの結果は、常に追加のユーザーメッセージ部分に分割されるのではなく、プロバイダー API に直接渡されます。
• Bedrock：推論プロファイル ARN を介してリクエストをルーティングするため、モデル設定と埋め込み設定で bedrock_inference_profile を利用できます。
• 安定性：OpenRouter での Anthropic モデルのマッチング、Cohere の埋め込み、Google の画像サイズ、Bedrock のツール名のサニタイズ、不正なツール呼び出しの再試行処理に関するプロバイダー向け修正が加わりました。

クイックスタート

基本的なエージェント

from pydantic_ai import Agent

agent = Agent(
    'openai:gpt-4o',
    instructions='Be concise, reply with one sentence.'
)

result = agent.run_sync('Where does "hello world" come from?')
print(result.output)

構造化出力を使う

from pydantic import BaseModel
from pydantic_ai import Agent

class CityInfo(BaseModel):
    name: str
    country: str
    population: int

agent = Agent('openai:gpt-4o', output_type=CityInfo)
result = agent.run_sync('Tell me about Paris')
print(result.output)  # CityInfo(name='Paris', country='France', population=2161000)

ツールと依存関係を使う

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    user_id: int

agent = Agent('openai:gpt-4o', deps_type=Deps)

@agent.tool
async def get_user_name(ctx: RunContext[Deps]) -> str:
    """Get the current user's name."""
    return f"User #{ctx.deps.user_id}"

result = agent.run_sync('What is my name?', deps=Deps(user_id=123))

主な機能

機能	説明
型安全	IDE の完全なサポートと型チェック
モデル非依存	30 以上のプロバイダーをサポート
依存性注入	コンテキストをツールに渡す
構造化出力	Pydantic モデルによる検証
埋め込み	複数のプロバイダーに対応したベクトルサポート
Logfire 統合	オブザーバビリティを標準搭載
MCP サポート	外部ツールとデータ
評価	体系的なテスト
グラフ	複雑なワークフローをサポート

サポート対象のモデル

プロバイダー	モデル
OpenAI	GPT-4o、GPT-4、o1、o3
Anthropic	Claude Opus 5、Claude Opus 4.8、Claude 4、Claude 3.5
Google	Gemini 2.0、Gemini 1.5
xAI	Grok-4（ネイティブ SDK）
Groq	Llama、Mixtral
Mistral	Mistral Large、Codestral
Azure	Azure OpenAI
Bedrock	AWS Bedrock + Nova 2.0
SambaNova	SambaNova モデル
Ollama	ローカルモデル

ベストプラクティス

1. 型ヒントを使う — IDE のサポートと検証が有効になります
2. 出力型を定義する — 構造化された応答が保証されます
3. 依存関係を使う — コンテキストをツールに注入します
4. ツールに docstring を追加する — LLM はそれを説明として使用します
5. Logfire を有効にする — 本番環境のオブザーバビリティに役立ちます
6. 簡単なケースでは run_sync を使う — 非同期処理には run を使います
7. テスト時に deps を上書きする — agent.override(deps=...)
8. 使用制限を設定する — UsageLimits で無限ループを防ぎます

禁止事項

• コード内で API キーを公開しないでください
• 本番環境で出力の検証を省略しないでください
• ツールのエラーを無視しないでください
• 部分的な出力を処理せずに run_stream を使用しないでください
• MCP 接続を閉じ忘れないでください（async with agent）
• 複数のラッパーやフックが関係する場合、機能の順序が任意だと思い込まないでください。構成が重要な場合は、順序を明示的に定義してください。

一般的なパターン

ストリーミング応答

async with agent.run_stream('Query') as response:
    async for text in response.stream_text():
        print(text, end='')

フォールバックモデル

from pydantic_ai.models.fallback import FallbackModel

fallback = FallbackModel(openai_model, anthropic_model)
agent = Agent(fallback)

MCP 統合

from pydantic_ai.mcp import MCPToolset

toolset = MCPToolset(command='python', args=['mcp_server.py'])
agent = Agent('openai:gpt-4o', toolsets=[toolset])

TestModel によるテスト

from pydantic_ai.models.test import TestModel

agent = Agent(model=TestModel())
result = agent.run_sync('test')  # Deterministic output

埋め込み

from pydantic_ai import Embedder

embedder = Embedder('openai:text-embedding-3-small')

# Embed search query
result = await embedder.embed_query('What is ML?')

# Embed documents for indexing
docs = ['Doc 1', 'Doc 2', 'Doc 3']
result = await embedder.embed_documents(docs)

プロバイダーと設定については、embeddings.md を参照してください。

xAI プロバイダー

from pydantic_ai import Agent

agent = Agent('xai:grok-4-1-fast-non-reasoning')

設定の詳細については、models.md を参照してください。

Exa ニューラル検索

import os
from pydantic_ai import Agent
from pydantic_ai.common_tools.exa import ExaToolset

api_key = os.getenv('EXA_API_KEY')
toolset = ExaToolset(api_key, num_results=5, include_search=True)
agent = Agent('openai:gpt-4o', toolsets=[toolset])

すべての Exa ツールについては、tools.md を参照してください。

リンク

• ドキュメント
• リリース
• GitHub
• PyPI