Pydantic AI 把错误的工具调用拦在客户系统之外
类型化工具先校验参数再执行代码;换模型只需改一个字符串,证明安全却要靠评测和锁定版本。
要点速览
- Pydantic AI 在代码运行前按 schema 校验工具参数,切换模型只需修改一个字符串。
- Pydantic Evals 是独立的包,不依赖 pydantic-ai。它测试智能体行为的方式,与 pytest 测试代码的方式类似。
- v2 改变了 openai: 模型名的含义,并把大版本之间不做破坏性变更的窗口期从 6 个月缩短到 3 个月,所以要锁定版本。
假设你正在一家物流公司驻场。一个读取投诉邮件的智能体,已经顺利跑完两周演示。某天早上,它调用订单查询工具时,把一整句话当作订单号传了进去,后端返回 500 错误。Pydantic AI 正是为了尽早拦住这类错误而生。
Pydantic AI 的自我定位是一个面向 AI 的 Python SDK,核心是类型化、可扩展的智能体循环,切换模型只需修改一个字符串。它由 Pydantic 背后的团队开发,采用 MIT 许可证发布。其 GitHub 仓库用一句话概括:每个模型、每个接口都是端到端类型化的。
对前线部署工程师(FDE)来说,价值就在“类型化”这个词上。在客户现场,难点很少是写出更好的提示词,而是把智能体接入客户的真实系统,而这些系统会拒收格式不对的数据。
类型在哪里拦住错误?
Pydantic AI 在三处强制类型:结构化输出、类型化依赖注入和类型化工具。工具是最关键的一处。模型生成的参数会在代码运行前按 schema 校验。
回到物流的例子。你声明一个工具 tra_don_hang(查询订单),接收固定格式的订单号。当模型传入“我的订单晚了”这整句话时,校验会在请求到达客户 API 之前把它拦下。错误发生在智能体内部,你还有机会处理,而不是出现在客户的运维日志里。
输出也是同样的道理。你可以要求智能体返回一张包含三个字段的工单:问题类型、订单号和优先级。接收端是客户的工单系统,它需要的恰好是这三个字段,而不是一段文字。数据契约用 Python 写成,客户的工程师可以直接读懂,不必从提示词里去猜。
换模型只需一个字符串,验证这次切换需要一套评测
当客户问“能不能用更便宜的模型?”时,一个字符串就能切换模型,确实方便。但方便不等于安全。要认真回答这个问题,你需要一个可度量的数字,而 Pydantic Evals 就是用来度量的工具。
Pydantic Evals 是一个独立的包,可以用 pip 或 uv 单独安装,不依赖 pydantic-ai。这意味着它也能用于不是基于 Pydantic AI 构建的 AI 系统。如果想观察结果,可以选装 Logfire 依赖。
Evals 组织测试的方式很简单。一个 Dataset 包含多个 Case,每个 Case 是一个测试场景。Task 是要运行的对象,这里就是智能体。Evaluator 对 Task 在每个 Case 上的输出进行分析和打分。Pydantic 团队把它类比为 pytest 测试代码的方式,实际使用时也应如此。
一个小型评测集长什么样?
设想你拿到 30 封客户已脱敏的真实邮件。每封邮件构成一个 Case,配上客服人员为它分配的正确工单。Evaluator 检查两点:提取出的订单号是否一致,优先级是否正确。下面的数字是用于说明的假设数据。
| 配置 | 通过的 Case 数 / 30 | 通过率 |
|---|---|---|
| 当前模型 | 27 | 90% |
| 客户提议的更便宜模型 | 24 | 80% |
更便宜的模型多失败 3 个 Case,也就是每 30 封邮件多出 3 张错误工单。现在,客户可以自己判断,省下的钱是否值得多出这 3 张错误工单。没有这张表,你只能凭感觉;有了它,会议就从争论印象变成讨论取舍。
到客户那里,第一件事是要数据来建 Dataset,甚至要在写智能体之前。30 个标注正确的 Case,比任何演示都更有价值。
局限:API 变化比你想的更快
v1 于 2025 年 9 月 4 日发布,承诺至少 6 个月内不做破坏性变更。它引入了持久化执行:在复杂工作流中途崩溃的智能体,可以从停下的地方准确恢复。对于长时间运行的企业流程,这项功能值得一试。
但版本发布节奏很快。Douwe Maan 在 2026 年 6 月 23 日介绍 v2 的文章中,引入了 capability 的概念,把指令、工具、hook 和模型设置打包成一个可组合的单元。
v2 还带来一个可能悄无声息失败的破坏性变更:openai: 模型名现在使用 Responses API,如果要继续用 Chat Completions,必须改成 openai-chat:。大版本之间不做破坏性变更的窗口期,也从 6 个月缩短到了 3 个月。
PyPI 上的最新版本是 2.54.0,发布于 2026 年 10 月 3 日,要求 Python 3.10 或更高版本。给 FDE 的教训是:客户项目中始终锁定版本,每次升级都重跑评测集。同一套评测集,既用来比较模型,也是升级时的安全网。
先学什么,简历上写什么
如果你已经通过 FastAPI 熟悉 Pydantic,基础就有了一半。学习顺序是:先结构化输出,再类型化工具,然后是依赖注入,最后才是 v2 的 capability。同时,在第一周就写出第一套评测集,而不是等到项目尾声。
阅读 FDE 或 AI 工程师岗位的职位描述时,留意“evaluation”“structured output”“production agent”这类说法。简历上写“用过 Pydantic AI”说明不了什么。写“构建了一个 30 个 Case 的 Dataset,在替代模型上线生产环境前发现它让通过率下降了 10 个百分点”,才能让招聘方看出你按 FDE 的方式工作。
这个库还会继续变化。它所倡导的工作方式值得保留:用代码定义数据,用评测度量行为,然后才切换模型。
这篇文章对你有帮助吗?
感谢你的反馈!