PydanticAI エージェントの作成

クイックスタート

from pydantic_ai import Agent

# 最小限のエージェント（テキスト出力）
agent = Agent('openai:gpt-4o')
result = agent.run_sync('Hello!')
print(result.output)  # str

モデルの選択

モデル文字列は provider:model-name 形式に従います：

# OpenAI
agent = Agent('openai:gpt-4o')
agent = Agent('openai:gpt-4o-mini')

# Anthropic
agent = Agent('anthropic:claude-sonnet-4-5')
agent = Agent('anthropic:claude-haiku-4-5')

# Google
agent = Agent('google-gla:gemini-2.0-flash')
agent = Agent('google-vertex:gemini-2.0-flash')

# その他: groq:, mistral:, cohere:, bedrock: など

構造化出力

検証済みの型付きレスポンスに Pydantic モデルを使用します：

from pydantic import BaseModel
from pydantic_ai import Agent

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

agent = Agent('openai:gpt-4o', output_type=CityInfo)
result = agent.run_sync('Tell me about Paris')
print(result.output.city)  # "Paris"
print(result.output.population)  # int, 検証済み

エージェント設定

agent = Agent(
    'openai:gpt-4o',
    output_type=MyOutput,           # 構造化出力型
    deps_type=MyDeps,               # 依存性注入型
    instructions='You are helpful.',  # 静的な指示
    retries=2,                      # 検証再試行回数
    name='my-agent',                # ログ/トレース用
    model_settings=ModelSettings(   # プロバイダー設定
        temperature=0.7,
        max_tokens=1000
    ),
    end_strategy='early',           # ツール呼び出しで結果が得られた場合の処理方法
)

エージェントの実行

3つの実行方法があります：

# 非同期（推奨）
result = await agent.run('prompt', deps=my_deps)

# 同期（利便性重視）
result = agent.run_sync('prompt', deps=my_deps)

# ストリーミング
async with agent.run_stream('prompt') as response:
    async for chunk in response.stream_output():
        print(chunk, end='')

指示 vs システムプロンプト

# 指示: 連結され、エージェント動作用
agent = Agent(
    'openai:gpt-4o',
    instructions='You are a helpful assistant. Be concise.'
)

# デコレーターによる動的な指示
@agent.instructions
def add_context(ctx: RunContext[MyDeps]) -> str:
    return f"User ID: {ctx.deps.user_id}"

# システムプロンプト: 静的、モデルコンテキスト用
agent = Agent(
    'openai:gpt-4o',
    system_prompt=['You are an expert.', 'Always cite sources.']
)

一般的なパターン

パラメーター化エージェント（型安全）

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    api_key: str
    user_id: int

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

# deps は必須となり型チェックされます
result = agent.run_sync('Hello', deps=Deps(api_key='...', user_id=123))

依存性なし（型チェッカーを満たすため）

# オプション 1: 明示的な型アノテーション
agent: Agent[None, str] = Agent('openai:gpt-4o')

# オプション 2: deps=None を渡す
result = agent.run_sync('Hello', deps=None)

判断フレームワーク

シナリオ	設定
シンプルなテキスト応答	Agent(model)
構造化されたデータ抽出	Agent(model, output_type=MyModel)
外部サービスが必要	deps_type=MyDeps を追加
検証再試行が必要	retries=3 を増加
デバッグ/監視	instrument=True を設定