# Pydantic AI 把错误的工具调用拦在客户系统之外

> 类型化工具先校验参数再执行代码；换模型只需改一个字符串，证明安全却要靠评测和锁定版本。

原文: https://fdetimes.net/zh/tools/pydantic-ai-typed-tools-evals/

假设你正在一家物流公司驻场。一个读取投诉邮件的智能体，已经顺利跑完两周演示。某天早上，它调用订单查询工具时，把一整句话当作订单号传了进去，后端返回 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 的方式工作。

这个库还会继续变化。它所倡导的工作方式值得保留：用代码定义数据，用评测度量行为，然后才切换模型。

**本周动手试试:**

- 在 Python 3.10 或更高版本上安装 pydantic-ai。构建一个返回三字段 Pydantic 模型的智能体，并配一个模拟查询工具。
- 单独安装 pydantic-evals，用自己编造的数据写一个 20 个 Case 的 Dataset，分别用两个不同的模型字符串运行，比较通过率。
- 打开项目的依赖文件，锁定 pydantic-ai 版本，并记下代码是否使用了 openai: 模型名。

## 信源

- [Pydantic AI](https://pydantic.dev/docs/ai/overview/)

- [Pydantic Evals](https://pydantic.dev/docs/ai/evals/evals/)

- [Pydantic AI v1: A Predictable & Robust GenAI Framework](https://pydantic.dev/articles/pydantic-ai-v1)

- [Pydantic AI v2: capable agentic loops](https://pydantic.dev/articles/pydantic-ai-v2)

- [GitHub - pydantic/pydantic-ai](https://github.com/pydantic/pydantic-ai)

- [pydantic-ai · PyPI](https://pypi.org/project/pydantic-ai/)
