PydanticAI 详解：类型安全的 Python AI SDK
写 LLM 应用最疼的两件事：模型返回的 JSON 不合预期、换一家模型商要改一串代码。pydantic/pydantic-ai（PydanticAI）用 Pydantic 团队的老本行回答了第一件——输出用 BaseModel 定义、运行前先校验，错误从运行时提前到编码时；第二件则用"模型即字符串"回答：换个厂商只改一个参数。如今它的口径已是"How Python does AI"：Agent、实时语音、图像生成、嵌入一站打包，配上可组合的能力（capability）系统与持久执行。约 19.9k Star、MIT 协议。本文从核心设计、Harness、多接口运行到选型对比，完整拆解。
1、项目概述
PydanticAI 定位为 Python AI SDK：一个类型安全、可扩展的 Agent 循环，几乎全部主流模型一个字符串即可切换；同一个 Agent 定义可以跑在 Web 前端、终端、语音通话、持久后台队列，或作为普通对象直接 run()。由 Pydantic 团队出品——Pydantic 校验层是 OpenAI SDK、Anthropic SDK、Google ADK、LangChain 乃至 FastAPI 的底座，这份工程信誉直接继承了过来。仓库约 19.9k Star、2.7k Fork，MIT 协议，2024 年 6 月创建，测试覆盖率徽章 100%。
基本盘：
- 安装：uv add pydantic-ai 一条命令，另有 pydantic-ai-slim 按需精简安装
- 模型接入：OpenAI、Anthropic、Google、Bedrock、Azure AI Foundry、Groq、Mistral、xAI、Ollama 等数十家，字符串即换
- 生态位：Pydantic Stack 一员，与 Logfire（可观测）、AI Gateway（网关）、Pydantic Evals（评测）、Pydantic Graph（图编排）配套
- 文档：pydantic.dev/docs/ai，完整 API 参考与示例库
- 无密钥起步：内置 test 模型可离线单元测试 Agent 行为
2、核心设计：类型安全与能力组合
两个关键词撑起整个框架：typed（类型贯穿始终）与 capability（能力即积木）。
设计支柱：
- 结构化输出：output_type 传 BaseModel，run() 的返回值经校验且类型确定，IDE、类型检查器与 LLM 对返回类型达成一致
- 类型化工具：@agent.tool 函数的签名与 docstring 自动生成工具 schema，参数先校验再执行
- 依赖注入：RunContext 携带 DB 连接池、HTTP 客户端等依赖进工具函数，类型同样是声明的
- 校验即纠错：输出不合规抛 ModelRetry，校验错误反馈给模型重试，而不是直接崩
- capability 原语：把工具、指令、钩子、模型设置捆成一个可复用单元，像乐高一样拼装
// 数据抽取：output_type + 类型化工具，返回值校验且带类型
uv add pydantic-ai
from typing import Literal
from pydantic import BaseModel, Field
from pydantic_ai import Agent, RunContext
class Sentiment(BaseModel):
label: Literal['positive', 'negative', 'neutral']
score: float = Field(ge=-1, le=1)
agent = Agent('openai:gpt-5.6-sol', output_type=Sentiment)
@agent.tool
def recent_reviews(ctx: RunContext[None], product: str) -> list[str]:
"""Fetch recent review snippets for a product."""
return ['The new release fixed everything I complained about!']
result = agent.run_sync('How are people feeling about the Extract app?')
print(result.output)
// label='positive' score=0.9设计要点：
1. 换模型只改字符串：'openai:gpt-5.6-sol' 换成 'anthropic:claude-fable-5'，其余代码不动
2. 工具的参数校验发生在你的代码执行之前，坏参数在 LLM 侧就被拦下并反馈重试
3. 复杂控制流另有 Pydantic Graph：节点类型化的图编排，与 Agent 同一套类型体系
4. 不写代码也能定义 Agent：YAML / JSON Agent Spec 直接声明，配置即 Agent
3、Harness：给 Agent 一间工作室
核心库只管 Agent 循环与基础能力（MCP、Web 搜索）；长任务需要的文件、规划、记忆、子 Agent，全部放进姊妹包 pydantic-ai-harness，按 capability 拼装。
// 完整编码 Agent：Coder + 网络搜索 + 第二意见顾问，三行拼成
uv add pydantic-ai pydantic-ai-harness
from pydantic_ai import Agent
from pydantic_ai.capabilities import WebSearch
from pydantic_ai_harness import Advisor, Coder
agent = Agent(
'anthropic:claude-fable-5',
capabilities=[
Coder(), # 文件、shell、仓库上下文、规划、子 Agent、上下文管理
WebSearch(), # 联网查文档与报错
Advisor('openai:gpt-5.6-sol'), # 卡住时找另一个模型要第二意见
],
)
agent.to_cli_sync() // 直接在终端与它对话
// Coder 是组合能力而非黑盒，等价于这些积木：
// FileSystem('.') + Shell(cwd='.') + RepoContext() + Planning()
// + SubAgents(...) + ClearToolResults() + WarnNearLimits()
// + ToolOutputLimits()Harness 要点：
1. 工作室四要素：可编辑的工作区（文件 + 白名单 shell）、跟随任务的规划、跨会话记忆、越用越长的上下文管理（压缩与输出限额）
2. 完整 Agent 也是 capability：Coder、Researcher 都是组合出来的，能整体用也能拆开用，"怎么拼上就怎么拆下"
3. 零代码试用：uvx --with pydantic-ai-harness clai -a pydantic_ai_harness.coder:coder_agent 一条命令跑官方 Coder
4. 生产案例：Datalayer 从 LangChain 迁到 PydanticAI 做 Jupyter Agent，Overjoy 跑客服与后台任务，Mixam 用它做打印助手的多模型实验
4、持久执行与实时语音
长任务怕中断，语音要实时——PydanticAI 把这两端都用 capability 的方式接上。
持久执行：
- 引擎：Temporal、DBOS、Prefect、Restate 官方共维护，AWS Lambda 持久函数与 Kitaru、Airflow 亦有接入
- 机制：挂上 TemporalDurability 后，每次模型与工具调用成为持久 activity，进程重启、故障、长等待都能续跑
- 人审内置：工具可声明为需审批，工作流挂起等人决策，进度由持久后端保住
实时语音：
- 通道：OpenAI Realtime、Gemini Live、Azure、xAI Grok Voice 四家
- 同一套资产：语音会话复用 Agent 的工具、依赖、指令与消息历史，工具在对话中边说边调
- 收尾：通话结束把历史交给文本 Agent 产出结构化结果
运行要点：
1. 同一 Agent 定义五处运行：CLI（clai）、内置 Web 聊天、语音、持久队列、普通 run() 调用
2. 前端对接走 UI 事件流（AG-UI、Vercel AI 协议），ACP（实验性）可把它变成编辑器 Agent
3. 图像生成与嵌入同箱：独立 ImageGenerator API，或 output_type=BinaryImage 让 Agent 运行中产图
5、可观测、评测与工程化
README 的口号是"Measured, not vibes"——不靠感觉，靠数据。
工程化配置：
- 原生 OpenTelemetry 埋点：一行 instrument_pydantic_ai()，任意 OTel 后端可接
- Pydantic Logfire：实时调试、追踪与成本统计，价格数据来自开源的 genai-prices 仓库
- Pydantic Evals：像 pytest 测代码一样测 Agent 行为，数据集打分、跨运行对比
- TestModel：本地模型替身，无需 API Key 即可单元测试工具调用与输出校验逻辑
- AI Gateway：统一代理多模型访问，预算与故障转移策略与代码解耦（可选付费产品）
要点：
1. 开源核心与商业可选分层清晰：SDK 与 Harness MIT 免费，Logfire / AI Gateway 是可选服务
2. 校验失败重试、审批挂起、成本追踪都以一等公民出现在 API 里，生产姿态明显
6、定位对比：Python Agent 框架三选一
把 PydanticAI 与 LangChain 系、PocketFlow 放在一张桌上，三种哲学清晰起来。
三者对比：
- PydanticAI：类型安全全家桶，模型字符串切换 + capability 组合 + 持久执行/语音/评测配套，Pydantic 团队出品（19.9k Star，MIT）
- LangChain / LangGraph：生态最大、组件与集成最多，图编排生产特性齐备，代价是抽象层厚、版本演进快
- PocketFlow：100 行零依赖的极简图框架，一切自己写，适合白盒学习与配合 AI 编码代理（11.2k Star，MIT）
选型建议：
1. Python 技术栈、重视类型与校验、要长任务持久化 → PydanticAI
2. 需要海量现成集成、重度 RAG 管线、团队已熟悉链式抽象 → LangChain / LangGraph
3. 想彻底理解每个环节、代码量最小化 → PocketFlow
4. 组合玩法：PydanticAI 做 Agent 层与校验层，重 RAG 场景把 LangChain 检索件挂成工具，教学与原型用 PocketFlow 对照
7、总结
PydanticAI 是 Pydantic 团队出品的 Python AI SDK（约 19.9k Star、MIT 协议）：以类型安全为核——结构化输出、类型化工具、依赖注入、校验即重试，把错误从运行时前移到编码时；模型数十家一个字符串切换，capability 原语把工具与指令组合成积木，官方 Harness 补齐文件、规划、记忆、子 Agent 等长任务要素；同一 Agent 可跑 CLI、Web、实时语音（四家语音通道）与 Temporal / DBOS / Prefect / Restate 持久执行，图像生成与嵌入同箱，配套 Logfire 可观测、Evals 评测与 TestModel 离线测试。
适用与边界：它适合以 Python 为主力、追求生产级可靠性的团队——校验、重试、审批、可观测都是一等公民，Datalayer、Overjoy、Mixam 等案例已跑在生产；相比 LangChain 的海量集成与 PocketFlow 的百行极简，它走的是"类型安全 + 官方全家桶"的中间路线，生态广度尚在扩张期（878 个 open issue 可见其活跃与迭代速度）。语音、ACP 等部分能力标注实验性，选型时按当前文档确认成熟度。
