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-gla: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-gla: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')

タスク ルーティング テーブル

最初に最も関連性の高いリファレンスのみを読み込みます。タスクが複数の領域にまたがっている場合にのみ、追加のリファレンスを読みます。

実行したいこと	リファレンス
エージェントを作成・設定、出力タイプを選択、deps を使用、仕様を定義、実行メソッドを選択	Agents Core
再利用可能な動作をバンドルするか、ライフサイクル イベントをインターセプト	Capabilities and Hooks
関数ツール、ツールセット、MCP サーバー、または明示的な検索ツールを追加	Tools Core
プロバイダー ネイティブ ウェブ検索、ウェブ フェッチ、またはコード実行を使用	Built-in Tools
承認、再試行、ToolReturn、バリデーター、タイムアウト、ツール検索などの高度なツール機能を使用	Tools Advanced
マルチモーダル入力、メッセージ履歴、またはコンテキスト トリミングを処理	Input and History
エージェント動作をテストまたはデバッグ	Testing and Debugging
複数のエージェントを調整するか、グラフ ワークフローを構築	Orchestration and Integrations
モデルを直接呼び出す、A2A を公開、永続的な実行、埋め込み、evals、または第三者統合を使用	Orchestration and Integrations
抽象化、出力モード、デコレーター、またはモデル文字列パターンを比較	Architecture and Decision Guide
古いリンクで COMMON-TASKS.md をフォロー	Task Reference Map

アーキテクチャと決定

ユーザーが抽象化を選択している場合、または比較表と決定ツリーが必要な場合にのみ、Architecture and Decision Guide を読み込みます：

トピック	カバーする内容
決定ツリー	ツール登録、出力モード、マルチエージェント パターン、キャパビリティ、テスト アプローチ、拡張性
比較表	出力モード、モデル プロバイダー プレフィックス、ツール デコレーター、ビルトイン キャパビリティ、エージェント メソッド
アーキテクチャ概要	実行フロー、ジェネリック型、構築パターン、ライフサイクル フック、モデル文字列フォーマット

クイック リファレンス — モデル文字列フォーマット： "provider:model-name" (例："openai:gpt-5.2"、"anthropic:claude-sonnet-4-6"、"google-gla:gemini-3-pro-preview")

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

キー プラクティス

• Python 3.10+ 互換性が必須
• 可観測性: Pydantic AI は Logfire との第一級統合を備えており、エージェント実行、ツール呼び出し、モデル リクエストをトレースします。logfire.instrument_pydantic_ai() で追加します。より深い HTTP レベルの可視性については、logfire.instrument_httpx(capture_all=True) がモデル プロバイダーに送信される正確なペイロードをキャプチャします。
• テスト: 確定的なテスト用に TestModel を使用、カスタム ロジック用に FunctionModel を使用

よくある落とし穴

これらは Pydantic AI でエージェントが一般的に犯す間違いです。これらを間違うと、サイレント フェーラーまたは混乱するエラーが発生します。

• @agent.tool は最初のパラメーターとして RunContext を必須にします。@agent.tool_plain はそれを持つことはできません。これらを混同するとランタイム エラーが発生します。deps、usage、またはメッセージが不要な場合は tool_plain を使用します。
• モデル文字列にはプロバイダー プレフィックスが必要：'gpt-5.2' ではなく 'openai:gpt-5.2'。プレフィックスがないと、Pydantic AI はプロバイダーを解決できません。
• TestModel は agent.override() を必須にします：agent.model を直接設定しないでください。常にコンテキスト マネージャーを使用します：with agent.override(model=TestModel()):。
• output_type の str により、プレーン テキストが実行を終了できる：ユニオンに str が含まれている場合 (または output_type が設定されていない場合)、モデルは構造化出力の代わりにプレーン テキストを返す可能性があります。構造化出力を強制するには、ユニオンから str を省略します。
• フック デコレーター名は .on にあり on_ を繰り返さない：hooks.on.on_run_error ではなく hooks.on.run_error と hooks.on.model_request_error を使用します。
• history_processors は複数形：Agent パラメーターは history_processor= ではなく history_processors=[...] です。

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

タスクが複数のファミリーに明確にまたがっている場合を除き、これらの 1 つだけを読み込みます：

タスク ファミリー	リファレンス
コア エージェント セットアップ、出力、deps、仕様、モデル、実行メソッド	Agents Core
キャパビリティ、フック、再利用可能な動作	Capabilities and Hooks
関数ツール、ツールセット、MCP、明示的な検索ツール	Tools Core
プロバイダー ネイティブ ビルトイン ツール	Built-in Tools
承認、再試行、バリデーター、タイムアウト、リッチ ツール リターン、遅延読み込み	Tools Advanced
マルチモーダル入力、メッセージ履歴、履歴プロセッサー	Input and History
テスト、リクエスト検査、Logfire デバッグ	Testing and Debugging
マルチエージェント パターン、グラフ、直接 API、A2A、永続的な実行、埋め込み、evals、第三者統合	Orchestration and Integrations

古いリンクとの互換性が必要な場合、または古いセクション名から新しいファイルへのポインターが必要な場合にのみ、Task Reference Map を使用します。