building-pydantic-ai-agents

Pydantic AI で AI エージェントを構築する

Pydantic AI は、本番環境で使える生成 AI アプリケーションを構築するための Python エージェントフレームワークです。 このスキルでは、Pydantic AI を使ったアプリケーション構築のパターン、アーキテクチャの指針、テスト済みのコード例を紹介します。

このスキルを使うタイミング

次の場合にこのスキルを呼び出してください：

• ユーザーが AI エージェントの構築や LLM を活用したアプリの作成を依頼した場合、または Pydantic AI に言及した場合
• ユーザーがエージェントにツールや機能（思考、ウェブ検索）、構造化出力を追加したい場合
• ユーザーが YAML／JSON 仕様からエージェントを定義したい場合、またはテンプレート文字列を使いたい場合
• ユーザーがエージェントのイベントをストリーミングしたい場合、エージェント間で委任したい場合、またはエージェントの動作をテストしたい場合
• コードで pydantic_ai をインポートしている場合、または Pydantic AI のクラス（Agent、RunContext、Tool）を参照している場合
• ユーザーがフック、ライフサイクルのインターセプト、Logfire によるエージェントの可観測性について質問した場合
• エージェントの設計に、任意の指示、専門的なワークフロー、使用頻度の低いツール、またはほとんどのターンでモデルが必要としないコンテキストが含まれる場合

次の場合はこのスキルを使用しないでください：

• Pydantic の検証ライブラリだけを使う場合（エージェントを使わない pydantic／BaseModel）
• 他の AI フレームワーク（LangChain、LlamaIndex、CrewAI、AutoGen）
• AI エージェントに関係のない一般的な Python 開発

クイックスタートのパターン

基本的なエージェントを作成する

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)
"""
The first known use of "hello, world" was in a 1974 textbook about the C programming language.
"""

エージェントにツールを追加する

import random

from pydantic_ai import Agent, RunContext

agent = Agent(
    'google:gemini-3-flash-preview',
    deps_type=str,
    instructions=(
        "You're a dice game, you should roll the die and see if the number "
        "you get back matches the user's guess. If so, tell them they're a winner. "
        "Use the player's name in the response."
    ),
)


@agent.tool_plain
def roll_dice() -> str:
    """Roll a six-sided die and return the result."""
    return str(random.randint(1, 6))


@agent.tool
def get_player_name(ctx: RunContext[str]) -> str:
    """Get the player's name."""
    return ctx.deps


dice_result = agent.run_sync('My guess is 4', deps='Anne')
print(dice_result.output)
#> Congratulations Anne, you guessed correctly! You're a winner!

Pydantic モデルによる構造化出力

from pydantic import BaseModel

from pydantic_ai import Agent


class CityLocation(BaseModel):
    city: str
    country: str


agent = Agent('google:gemini-3-flash-preview', output_type=CityLocation)
result = agent.run_sync('Where were the olympics held in 2012?')
print(result.output)
#> city='London' country='United Kingdom'
print(result.usage)
#> RunUsage(input_tokens=57, output_tokens=8, requests=1)

依存性注入

from datetime import date

from pydantic_ai import Agent, RunContext

agent = Agent(
    'openai:gpt-5.2',
    deps_type=str,
    instructions="Use the customer's name while replying to them.",
)


@agent.instructions
def add_the_users_name(ctx: RunContext[str]) -> str:
    return f"The user's name is {ctx.deps}."


@agent.instructions
def add_the_date() -> str:
    return f'The date is {date.today()}.'


result = agent.run_sync('What is the date?', deps='Frank')
print(result.output)
#> Hello Frank, the date today is 2032-01-02.

TestModel を使ったテスト

from pydantic_ai import Agent
from pydantic_ai.models.test import TestModel

my_agent = Agent('openai:gpt-5.2', instructions='...')


async def test_my_agent():
    """Unit test for my_agent, to be run by pytest."""
    m = TestModel()
    with my_agent.override(model=m):
        result = await my_agent.run('Testing my agent...')
        assert result.output == 'success (no tool calls)'
    assert m.last_model_request_parameters.function_tools == []

機能を使う

機能とは、ツール、フック、指示、モデル設定をまとめた、再利用可能で組み合わせ可能なエージェントの動作単位です。

from pydantic_ai import Agent
from pydantic_ai.capabilities import Thinking, WebSearch

agent = Agent(
    'anthropic:claude-opus-4-6',
    instructions='You are a research assistant. Be thorough and cite sources.',
    capabilities=[
        Thinking(effort='high'),
        WebSearch(),
    ],
)

ライフサイクルフックを追加する

Hooks を使うと、サブクラス化せずにデコレーターでモデルリクエスト、ツール呼び出し、実行をインターセプトできます。

from pydantic_ai import Agent, RunContext
from pydantic_ai.capabilities.hooks import Hooks
from pydantic_ai.models import ModelRequestContext

hooks = Hooks()


@hooks.on.before_model_request
async def log_request(ctx: RunContext[None], request_context: ModelRequestContext) -> ModelRequestContext:
    print(f'Sending {len(request_context.messages)} messages')
    return request_context


agent = Agent('openai:gpt-5.2', capabilities=[hooks])

YAML 仕様からエージェントを定義する

Agent.from_file を使うと、YAML または JSON からエージェントを読み込めます。Python でエージェントを構築するコードは不要です。

from pydantic_ai import Agent

# agent.yaml:
# model: anthropic:claude-opus-4-6
# instructions: You are a helpful research assistant.
# capabilities:
#   - WebSearch
#   - Thinking:
#       effort: high

agent = Agent.from_file('agent.yaml')

タスク振り分け表

最初に最も関連性の高いリファレンスだけを読み込んでください。タスクが複数の領域にまたがる場合に限り、追加のリファレンスを読んでください。

やりたいこと	リファレンス
エージェントの作成／設定、出力タイプの選択、依存関係の使用、仕様の定義、実行メソッドの選択	エージェントの基本
再利用可能な動作をまとめる、またはライフサイクルイベントをインターセプトする	機能とフック
即時ロードとオンデマンドロードを使い分ける、段階的な開示を適用する、機能の読み込みを遅らせる、または load_capability を説明する	オンデマンドの機能
関数ツール、ツールセット、MCP サーバー、または明示的な検索ツールを追加する	ツールの基本
プロバイダー標準のウェブ検索、ウェブ取得、コード実行を使う	標準ツール
承認、再試行、ToolReturn、バリデーター、タイムアウト、ツール検索などの高度なツール機能を使う	ツールの応用
マルチモーダル入力、メッセージ履歴、コンテキストのトリミングを扱う	入力と履歴
エージェントの動作をテストまたはデバッグする	テストとデバッグ
複数のエージェントを調整する、またはグラフワークフローを構築する	オーケストレーションと統合
モデルを直接呼び出す、A2A を公開する、永続実行、埋め込み、評価、サードパーティ統合を利用する	オーケストレーションと統合
抽象化、出力モード、デコレーター、モデル文字列のパターンを比較する	アーキテクチャと選択ガイド
古いリンクから COMMON-TASKS.md にアクセスする	タスクリファレンスマップ

アーキテクチャと設計判断

抽象化の選択に迷っている場合や、比較表や判断ツリーが必要な場合にのみ、アーキテクチャと設計判断ガイドを読み込んでください。

トピック	内容
判断ツリー	ツールの登録、出力モード、マルチエージェントのパターン、機能、テスト方法、拡張性
比較表	出力モード、モデルプロバイダーのプレフィックス、ツールデコレーター、組み込み機能、エージェントのメソッド
アーキテクチャの概要	実行フロー、ジェネリック型、構築パターン、ライフサイクルフック、モデル文字列の形式

クイックリファレンス — モデル文字列の形式： "provider:model-name"（例："openai:gpt-5.2"、"anthropic:claude-sonnet-4-6"、"google:gemini-3-pro-preview"）

クイックリファレンス — 主なエージェントメソッド： run()、run_sync()、run_stream()、run_stream_sync()、run_stream_events()、iter()

主なプラクティス

• Python 3.10 以降との互換性が必要です
• デフォルトでは段階的に開示します：各機能について、先行読み込みを選ぶ前に、defer_loading=True がエージェントに役立つかを明示的に検討してください。モデルがほとんどのターンで必要としない限り、専門的な指示、めったに使わないツールのスキーマ、ドメインコンテキストを先行読み込みしないでください。名前付きの指示とツールのバンドルには必要に応じた機能の提供を、大規模でフラットなツールカタログにはツール検索を優先してください。
• 可観測性：Pydantic AI は、エージェントの実行、ツール呼び出し、モデルリクエストをトレースするための Logfire とファーストクラスの統合機能を備えています。logfire.instrument_pydantic_ai() を使って追加してください。HTTP レベルでより詳細に可視化するには、logfire.instrument_httpx(capture_all=True) によって、モデルプロバイダーに送信される正確なペイロードを記録できます。
• テスト：決定性のあるテストには TestModel を、カスタムロジックには FunctionModel を使います

よくある落とし穴

以下は、エージェントが Pydantic AI でよく起こす間違いです。これらを誤ると、気づきにくい失敗や分かりにくいエラーが発生します。

• @agent.tool の最初のパラメーターには RunContext が必要です。一方、@agent.tool_plain に指定してはいけません。取り違えると実行時エラーになります。依存関係、使用状況、メッセージが不要な場合は tool_plain を使ってください。
• モデル文字列にはプロバイダーのプレフィックスが必要です：'gpt-5.2' ではなく 'openai:gpt-5.2' を指定してください。プレフィックスがないと、Pydantic AI はプロバイダーを解決できません。
• TestModel には agent.override() が必要です：agent.model を直接設定しないでください。必ずコンテキストマネージャーを使って、with agent.override(model=TestModel()): と記述してください。
• 出力型に str が含まれると、プレーンテキストで実行を終了できます：ユニオンに str が含まれる場合（または output_type が設定されていない場合）、モデルは構造化出力ではなくプレーンテキストを返せます。ツールベースの出力を強制するには、ユニオンから str を除いてください。
• .on のフックデコレーター名には on_ を重ねて付けません：hooks.on.run_error と hooks.on.model_request_error を使い、hooks.on.on_run_error は使わないでください。
• history_processors は非推奨です。代わりに capabilities=[ProcessHistory(p), ...] を使うか、capabilities=[Hooks(before_model_request=fn)] を通じて before_model_request フックを直接使ってください。ProcessHistory はこのフックを薄くラップしたもので、基礎となるプリミティブはフック自体です。1.x ではこのキーワード引数も引き続き使えますが、PydanticAIDeprecationWarning が出力され、v2 で削除されます。

タスクファミリーのリファレンス

タスクが明らかに複数のファミリーにまたがる場合を除き、次のうち1つだけを読み込んでください。

タスクファミリー	リファレンス
コアエージェントのセットアップ、出力、依存関係、仕様、モデル、実行方法	Agents Core
機能、フック、再利用可能な動作	Capabilities and Hooks
段階的な開示、遅延機能、必要に応じた機能、load_capability のセマンティクス	Capabilities on Demand
関数ツール、ツールセット、MCP、明示的な検索ツール	Tools Core
プロバイダー固有のツール	Native Tools
承認、再試行、バリデーター、タイムアウト、リッチなツールの戻り値、ツール検索、ツールレベルの遅延読み込み	Tools Advanced
マルチモーダル入力、メッセージ履歴、履歴プロセッサー	Input and History
テスト、リクエストの検査、Logfire によるデバッグ	Testing and Debugging
マルチエージェントのパターン、グラフ、直接 API、A2A、永続的な実行、埋め込み、評価、サードパーティーとの統合	Orchestration and Integrations

古いリンクとの互換性を保つ場合、または古いセクション名から新しいファイルへの参照が必要な場合にのみ、Task Reference Map を使用してください。