用 Pydantic AI V2 写类型安全的生产级 Agent（FastAPI 风格）

pip install pydantic-ai

# 想用哪家模型就装对应 extra（可选，不装也能跑 OpenAI）
pip install 'pydantic-ai[openai]'
pip install 'pydantic-ai[anthropic]'

# 设置 Key（以 OpenAI 为例）
export OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx

from pydantic_ai import Agent

agent = Agent(
    'openai:gpt-4o',
    system_prompt='你是简洁的中文助手，回答不超过两句话。',
)

# 同步调用（脚本里最方便）
result = agent.run_sync('用一句话解释什么是类型安全。')
print(result.output)

工具就是普通 Python 函数，参数和返回值的类型标注就是给模型的schema。模型要调工具时，Pydantic 会先校验入参：

from pydantic_ai import Agent

agent = Agent('openai:gpt-4o', system_prompt='需要时用工具查汇率。')

@agent.tool
def get_rate(from_cur: str, to_cur: str) -> float:
    """查询两种货币间的汇率。"""
    # 真实场景调用汇率 API；演示返回固定值
    rates = {'USD': 1.0, 'CNY': 7.2, 'EUR': 0.92}
    return rates[to_cur] / rates[from_cur]

result = agent.run_sync('100 美元能换多少人民币？')
print(result.output)

用 output_type 指定一个 Pydantic Model 或 dataclass，模型输出会被自动解析成对象：

from pydantic import BaseModel
from pydantic_ai import Agent

class WeatherReport(BaseModel):
    city: str
    temp_c: float
    advice: str

agent = Agent('openai:gpt-4o', output_type=WeatherReport)
result = agent.run_sync('北京现在天气怎么样，我能穿短袖吗？')

r: WeatherReport = result.output
print(r.city, r.temp_c, r.advice)   # 直接当对象用，不用 json.loads

from dataclasses import dataclass
from pydantic_ai import Agent, RunContext

@dataclass
class Deps:
    user_id: str
    db: dict          # 真实场景是数据库连接

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

@agent.tool
def get_user_name(ctx: RunContext[Deps]) -> str:
    """根据上下文拿到当前用户名。"""
    return ctx.deps.db.get(ctx.deps.user_id, '朋友')

# 多 Agent：把特定任务 handoff 给专家 Agent
support = Agent('openai:gpt-4o', system_prompt='你是售后专家。')
main = Agent('openai:gpt-4o',
             system_prompt='遇到售后问题，交给 support 处理。',
             handoffs=[support])

result = main.run_sync('我的订单还没到', deps=Deps(user_id='u1', db={'u1': '小明'}))
print(result.output)

# test_agent.py
from pydantic_ai import Agent

agent = Agent('openai:gpt-4o', output_type=bool,
              system_prompt='判断一句话是否含负面情绪，只返回 true/false。')

def test_sentiment():
    r = agent.run_sync('这个产品太难用了，想退款')
    assert r.output is True

1) 模型供应商解耦：output_type / tool / deps 都和具体模型无关，
   换 'anthropic:...' 只改 Agent 构造那一行。

2) 可观测：接入 Logfire（Pydantic 官方观测）一行开启
   # pip install logfire && logfire configure
   # export LOGFIRE_TOKEN=xxx

3) 超时与重试：给 Agent 包一层你服务的超时/限流，
   别让单个慢模型拖垮整条请求链路。

4) 成本护栏：用 output_type 收敛输出、用 system_prompt 限范围，
   避免模型乱挥发大 token 消耗。