一家制造企业的采购智能体接入供应商报价接口接口持续返回JSON格式的报价数据智能体据此自动生成比价单。某天供应商升级接口返回字段从unit_price改成price还多嵌套了一层data对象。智能体没有察觉仍按原字段名解析拿到空值却在比价单里填上0元。采购员看到某供应商报价为零以为对方免费供货险些据此下单。这类问题在智能体接入外部系统时并不少见。接口返回格式变化、字段增减、数据类型改变任何一项都可能让智能体拿到错误数据。不少团队认为做好接口文档管理就行。但外部接口往往不在己方控制范围内供应商升级未必提前告知文档更新和解析逻辑调整之间也存在时间差。问题根源是智能体缺少对返回数据的契约校验和异常隔离。一类原因是系统对返回数据不做结构校验接口结果直接进入上下文不检查字段是否存在、类型是否匹配字段缺失时静默使用空值。另一类原因是接口契约没被固化成可执行的校验规则预期返回结构只存在于文档里。还有一类原因是系统把字段缺失、值为null、类型错误和合法的0这四种状态混为一谈统一当空值处理——合法的0被当作异常丢弃真正的缺失被当作0填入比价单。本文基于青山不语AI工作室在部分项目中的实践将接口返回数据校验归入工具返回内容校验与异常隔离框架以“接口契约校验与响应降级”作为该框架在接口场景下的子机制展开讨论。校验链路分为三个阶段HTTP/语法解析、Schema契约校验、业务字段提取。第一阶段处理传输层和语法层问题检查HTTP状态码是否正常、响应体是否为合法JSON或XML语法解析失败时不进入后续阶段直接标记该接口本次调用不可用。第二阶段按Schema契约逐项校验返回结构契约在接入阶段固化为结构化规则记录每个字段的完整路径、数据类型、是否nullable、是否必填以及嵌套层级。Schema校验覆盖嵌套路径——data对象下的price字段与顶层的price字段是不同路径契约按完整路径匹配不因字段名相同就误判。nullable字段允许值为null非nullable字段出现null视为校验失败必填字段缺失视为校验失败可选字段缺失不阻断。第三阶段从通过Schema校验的结构中提取业务字段提取时严格区分四种状态字段在返回结构中不存在为missing字段存在但值为null为null状态字段存在但类型与契约不符为type error字段存在且类型正确值为0为合法0。四种状态不能混missing不等于nullnull不等于0type error不等于missing。系统对四种状态采取不同处理——missing和type error属于结构异常高风险字段如金额、数量、日期出现这两种状态时智能体不继续生成涉及该字段的回复改为告知用户该数据当前不可用null状态按业务规则判断该字段是否允许为空不允许则为异常合法0是正常的业务值正常进入下游流程不能因为“看起来像空”就丢弃。接口无显式版本号时系统在己方维护契约版本或计算Schema指纹。契约版本是己方对接入接口当前返回结构的内部编号Schema指纹是按字段路径、字段类型和嵌套层级计算的结构特征值。每次接口返回后系统比对实际Schema指纹与己方记录的指纹指纹一致说明结构未变指纹变化说明接口结构发生了变更判定为契约漂移。契约漂移触发告警系统不自行用旧契约解析新结构而是标注该接口当前结构未知进入降级路径。降级路径中系统不拿缓存旧值冒充当前值而是明确标注该字段不可用等待契约更新或人工介入。接口返回格式变化导致解析失败的核心矛盾是外部接口不在己方控制范围内而智能体又依赖其返回数据。把校验拆成三阶段链路把missing/null/type error/合法0四种状态分开处理在无显式版本号时用Schema指纹检测契约漂移是降低这类风险的方向。在我看来企业选型时不能只看智能体能不能调通接口更要看它在接口返回异常时有没有校验和降级。一个拿到空值就填零的智能体比一个报错停下来的智能体危险得多。
