AI Agent 接口返回校验：字段缺失、空值和版本变化怎么处理
接口返回 200，不代表结果可以直接交给智能体。围绕 ERP 查询中的字段缺失、空值、单位和版本变化，建立响应校验与异常处理边界。
用户问“这项物料还有多少可用库存”，ERP 接口返回了 200，聊天窗口也很快给出数字。但如果接口升级后改了字段名，适配代码又把取不到的值填成零，智能体就可能把“没有拿到有效数量”回答成“库存为零”。这不是换一个提示词就能可靠解决的问题。AI Agent 接口返回校验，需要在业务数据进入回答之前，确认结果是否符合双方约定。
先区分调用成功与结果可用
HTTP 状态码、响应格式和业务结果是不同层面的信息。一个响应即使状态码为 200、内容也能解析成 JSON，仍可能缺少本次查询必需的字段，或携带接口自行约定的业务错误。不能只要请求没有抛异常，就让智能体宣布查到了结果。
建议先明确本次任务需要什么：查询对象是否正确，数据对应哪个组织与仓库，数量采用什么单位，以及它代表当前值还是某个时点的快照。只有与问题相关的这些条件得到满足，结果才适合被用于回答。
这里的“接口契约”，不只是文档中的字段清单，还包括缺失和异常时怎样处理。OpenAPI 3.1.0 的响应描述可表达不同状态码对应的响应约定，但写好描述文件不意味着运行中的返回值已经被自动验证。执行检查仍要落实到实际调用链路。
缺失、null 和零值不能混用
字段没有出现、字段值为 null、字段值为数字 0，是三种不同的数据状态。它们在具体业务中是否有特殊含义，应由接口约定解释，不能让模型或兜底代码自行统一。
JSON Schema 官方文档说明，写在 properties 中的属性并不默认必填；需要出现的属性应列入 required。属性存在但值为 null，也不等于属性缺失；是否允许该值，要看它的类型约束。
以一个假设库存查询为例：如果双方约定 null 表示源系统暂时无法确认数量，就不能把它展示成零库存。若约定数量字段必须出现，字段缺失应被识别为不符合约定，而不是当作“查询对象不存在”。数字零则只有在查询范围、单位和数据状态都有效时，才支持对应的零值结论。
类似 value ?? 0 的默认处理虽然让页面不再报错，却可能把未知状态改成确定数字。JSON Schema 的 default 注解也不会在标准校验过程中自动补齐缺失值。若某个库或适配层另有填充行为，应明确配置与业务依据，不能把“有默认值”当成“得到真实数据”。
把接口约定变成运行时检查
响应检查适合放在受控的工具服务或项目适配层中，在结果进入模型上下文之前执行。仅约束模型生成的调用参数，并不能验证远端系统实际返回了什么；仅在提示词中写“检查字段完整”，也不能替代确定性的程序检查。
不必一开始就搭建庞大的契约管理平台。先围绕当前任务真正使用的字段，记录以下四类约定，并用现有校验组件执行能机器判断的部分。
- 出现条件：哪些字段必须返回，哪些只在成功或失败分支出现，空值分别表示什么。
- 数据形态：字段类型、允许的状态值、列表元素结构，以及是否允许空字符串或小数。
- 业务语义：对象标识、组织和仓库范围、数量单位、数据时点，以及可接受的数据新鲜度。
- 异常路径：字段缺失、类型变化、业务拒绝或范围不符时，是否停止回答、返回信息不足或交由指定人员处理。
结构正确不代表语义正确。数量字段仍然是数字，但单位从“件”变成“箱”，简单类型校验未必能发现问题。应把任务依赖的单位、范围等条件写进可执行规则；仍需人工判断的业务口径则明确留出确认入口，不声称 Schema 能证明所有事实。
校验后只向模型提供本次任务允许使用的字段和清晰状态，而不是把整个原始响应直接交过去。错误记录可以保存关联标识、字段路径、预期类型与实际类型；不应为了排障，把完整客户资料、令牌或不必要的业务明细写入普通日志。
库存查询的一个失败反例
以下是原创假设，不是客户故障复盘，也不是任何 ERP 的实际字段定义。旧版响应使用 availableQty 表示可用数量；新版本改用 availableQuantity，演示值为 12。旧适配器仍读取原字段，并在没有读到时填入零，随后让智能体回答“没有可用库存”。
这条链路里，HTTP 请求完成了，JSON 也合法，错误发生在字段映射与默认处理之间。真正缺少的是一条边界：当前响应没有提供已约定的关键字段，不能继续产生依赖该字段的结论。
- 识别不匹配：在进入回答前发现必需字段缺失，保留原查询的可追踪标识。
- 停止错误推断：不要把缺失值转换成零，也不要直接把新字段名猜成旧字段的同义词。
- 核实版本与含义：确认新字段是否确实代表同一业务量，是否同时改变单位、范围或计算口径。
- 显式适配并复测：更新经确认的映射，用原始失败样本与正常样本验证，再恢复该类回答。
面向用户，可以准确说明“接口已返回，但库存数量字段不符合当前约定，暂时无法确认数量”。不要把内部结构错误包装成“物料不存在”“权限不足”或“库存为零”，这些都是需要独立证据的业务判断。
字段变更如何兼容，而不是静默猜测
版本变化不能简单分成“全部接受”或“全部拒绝”。若上游增加一个当前任务不用的说明字段，调用方可能可以继续工作；若删除正在使用的字段、改变空值语义，或扩大状态枚举的含义，就需要重新判断消费逻辑。
一个可操作的办法，是把上游原始响应和模型实际消费的结果分开：适配层接收接口数据，校验依赖项，再映射成少量稳定字段。对于允许的可选扩展，可以按约定忽略；未经评估的新字段不要自动加入模型可见内容。对于关键字段变化，则明确报出契约不匹配。
兼容策略应由接口双方与消费方共同确认。不要因为字段看起来相似，就长期同时尝试多个名称；尤其不能把“可用库存”“账面库存”“预计到货量”等不同口径当成可互换字段。如果确实需要支持两个版本，应明确版本识别方式、各自映射及停止支持旧版的条件。
校验失败也不必然适合重试。稳定存在的字段变更不会因为重复调用而消失。应按错误性质处理，避免一边持续发送相同请求，一边不断生成貌似正常的答案。涉及写操作结果未知时，则应按独立的ERP 写入与重试边界处理，不能用重新提交来“修复”坏响应。
上线前重放这些异常响应
在隔离环境中保存脱敏的响应样本，或构造不含真实业务资料的假数据，让同一套适配逻辑反复处理。下面是建议用例，不是本站已经完成的客户测试，也没有统一的准确率承诺。
- 必需字段缺失：检查是否停止依赖该字段的回答，而不是补零或使用上一次结果。
- 允许与不允许的空值：分别验证约定允许的未知状态，以及本应拒绝的
null。 - 真实零值：检查零没有被当成“没拿到”，也没有触发未经约定的备用值。
- 类型与状态变化：用数字字符串、陌生状态或不同列表结构，检查是否被明确识别。
- 结构正确但语义不符：改变单位、仓库标识或数据时点，检查任务约束是否真正生效。
- 版本与可选扩展：区分允许新增的可选字段与关键字段改名，检查兼容规则是否符合约定。
- 错误分支：让接口返回约定的业务错误，确认不会因 HTTP 状态码为 200 就报告业务成功。
每个样本同时记录预期状态、允许进入模型的数据，以及不应出现的最终表述。修复后重放原失败样本，检查适配层输出和用户看到的回答，而不是只观察校验函数有没有报错。
关键目标不是让所有响应都“通过”，而是让无法确认的数据保持无法确认。能区分有效结果与信息不足，才有条件谈后续的回答质量。整体接入顺序可继续阅读AI Agent 对接 ERP 的实施步骤。
参考资料与适用边界
- JSON Schema：对象属性、必需属性与类型约束。
- JSON Schema：Annotations 与 default 的含义。
- OpenAPI Specification 3.1.0。本文使用这一明确版本作参考，不表示它是最新规范，也不混用其他版本的空值写法。
资料查阅日期：2026 年 9 月 14 日。本文围绕本站系统集成页面已公开的 ERP 查询、企业 API 与项目适配方向，提出通用实现建议；具体字段含义、校验规则和兼容策略仍取决于目标系统的接口约定，不代表本站默认具备文中每一项机制。
