第 1.9.1 节：用 Pydantic 统一模型、工具和接口的数据契约
Pydantic 与数据不能只停留在口头约定，还需要落实为字段、校验和失败处理。完成本节后，你应该能够把 Pydantic 与数据落成字段表、校验规则、错误处理和验收样例。
本章要解决什么问题
第 1.4 章讲过 Structured Output（结构化输出），第 1.6 章讲过 Tool Calling（工具调用）。到这一章，读者会遇到一个更隐蔽但更真实的工程问题：字段看起来都有了，但每一层对字段的理解不一样。
在企业客服知识库与工单 Agent（智能体）工作台里，模型可能输出 intent（意图）、risk_level（风险等级）和 next_action（下一步动作）；工具调用需要 tool_name（工具名称）和 tool_args（工具参数）；后端 API（应用程序接口）要返回 validation_status（校验状态）；前端要根据状态显示“等待用户补充信息”“已转人工”“工具不可用”；日志系统要记录 trace_id（追踪编号）和失败原因；测试用例还要验收同一批字段是否稳定。
如果这些字段没有统一契约，系统会出现很多看似小、实际很致命的问题：
- 模型输出
refund，后端期望refund_request，流程无法进入退款工单。 - 前端把
high风险当成黄色提醒，后端却认为必须转人工。 - 工具参数缺少订单编号，系统仍然执行了工具调用。
- 校验失败后模型重新生成了一个看似合理但没有依据的结果。
- 日志里没有追踪编号，线上问题无法复盘。
所以本章的核心观点是：
Pydantic（数据校验库） 在本书里不是语法课，而是数据契约治理工具。它帮助团队统一字段含义，拦住不合格数据，并把失败导向重试、降级、转人工或拒绝执行。
本章不会教 BaseModel（基础数据模型）的写法，不会提供 Python（编程语言）、TypeScript（类型化脚本语言）、JavaScript（脚本语言）或 JSON（结构化数据格式）语法代码。你要学的是：在一个可交付的 Agent 项目里，哪些边界需要契约、字段如何命名和解释、校验失败如何处理、面试时如何把它讲成工程能力。
学习目标
读完本章后，你应该能够：
- 用人话解释数据契约为什么比“字段能跑通”更重要。
- 说明 Pydantic（数据校验库）在 AI Agent 项目中的位置。
- 把模型结构化输出、工具输入、API 请求响应、前端状态、日志字段和验收用例放到同一套字段语义下。
- 为客服工作台设计核心字段契约，包括
schema_version（契约版本）、intent（意图）、risk_level（风险等级）、next_action（下一步动作）、missing_fields（缺失字段）、tool_name（工具名称）、tool_args（工具参数）、validation_status（校验状态）、validation_error（校验错误）、retry_allowed（是否允许重试）、fallback_action（兜底动作）和trace_id（追踪编号）。 - 判断校验失败后应该重试、追问、降级、转人工，还是拒绝工具执行。
- 设计数据契约相关的权限、状态、日志和验收样例。
- 避免把 Pydantic（数据校验库）学成孤立语法，而是把它用在业务边界治理上。
- 在面试中清楚回答“为什么 AI（人工智能）项目不能到处传自由字典”“结构化输出失败怎么办”“字段契约如何支撑前后端协作”。
贯穿业务场景
本章继续使用“企业客服知识库与工单 Agent 工作台”。
用户进入客服窗口后，可能会说：
我上周买的设备用了两天就坏了，订单号我忘了。你们要么给我退钱，要么我就投诉。
这句话对人来说不难理解，但对系统来说，它必须被拆成稳定字段：
| 系统需要理解的内容 | 可能字段 | 为什么重要 |
|---|---|---|
| 用户想做什么 | intent（意图） | 决定是售后咨询、退款申请、投诉，还是普通问答。 |
| 风险高不高 | risk_level（风险等级） | 涉及退款和投诉，不能完全自动处理。 |
| 还缺什么信息 | missing_fields（缺失字段） | 缺订单编号，不能直接查订单或发起退款审批。 |
| 下一步做什么 | next_action（下一步动作） | 可能是追问订单号、让用户选择订单、创建投诉工单或转人工。 |
| 是否要调用工具 | tool_name（工具名称）和 tool_args（工具参数） | 只有字段合格、权限通过后才允许查订单或建工单。 |
| 校验是否通过 | validation_status（校验状态） | 防止不完整或不可信结果进入业务动作。 |
| 出错怎么办 | validation_error（校验错误）、retry_allowed（是否允许重试）、fallback_action（兜底动作） | 决定重试、追问、降级、转人工或拒绝执行。 |
| 如何复盘 | trace_id（追踪编号） | 把用户输入、模型输出、工具调用、前端展示和日志串起来。 |
这个例子说明：Pydantic（数据校验库）的价值不在于“定义一个模型类”，而在于让系统每一层都能围绕同一批字段做判断。
在客服工作台里，数据契约至少穿过 6 个地方：
| 位置 | 需要契约的原因 |
|---|---|
| 模型结构化输出 | 模型必须输出可解析、可校验、可驱动流程的字段。 |
| 工具输入 | 工具执行前必须确认参数、权限和风险。 |
| API 请求响应 | 前后端不能靠口头约定猜字段含义。 |
| 前端状态 | 页面要知道展示草稿、追问、错误、转人工还是工具结果。 |
| 日志字段 | 线上问题要能按追踪编号复盘。 |
| 验收用例 | 测试要验证字段值、状态转移和兜底路径。 |
新手为什么会卡住
很多新手第一次接触 Pydantic（数据校验库）时，会把它当成“Python（编程语言）里的类型工具”。这种理解没有错，但远远不够。AI Agent 项目里的数据问题通常不是“字段有没有类型提示”，而是“字段能不能稳定支撑业务流程”。
| 常见误解 | 项目后果 | 正确理解 |
|---|---|---|
Pydantic（数据校验库）就是写 BaseModel（基础数据模型） | 学了语法，但不知道放在哪些边界 | 本章关注模型输出、工具输入、API、前端状态、日志和测试之间的契约统一。 |
| 模型能返回结构化结果就够了 | 字段值漂移、字段缺失、枚举不一致 | 结构化输出必须经过契约校验，失败要有处理路径。 |
| 字段名差不多就行 | 前后端、工具和日志理解不一致 | 字段名、含义、取值范围和使用场景都要统一。 |
| 校验失败再让模型改一下 | 高风险动作可能被错误重试 | 重试要有限制，写入和高风险工具失败时常常应拒绝执行或转人工。 |
| 日志只记录报错文本 | 出问题无法追踪整条链路 | 日志必须包含 trace_id（追踪编号）、字段校验状态、工具和兜底动作。 |
| 前端状态可以自己判断 | 页面会和后端状态漂移 | 前端展示也应该消费同一套状态契约。 |
| 测试只测接口是否成功 | 无法发现风险误判和兜底缺失 | 验收用例要覆盖正常、缺字段、越权、工具失败和高风险场景。 |
本章的重点就是帮你从“会写校验模型”升级到“会治理数据边界”。