AI Agent 工具調用不能只靠 Mock:一次第三方介面欄位漂移後的契約治理
AI Agent工具调用不能只靠Mock:一次第三方接口字段漂移后的契约治理
團隊在第三方物流介面欄位和配送狀態值漂移、令售後 Agent 無法將物流單號及配送狀態寫入 CRM 後,採用 API 閘道做通用契約校驗,並由 SDK 負責業務適配和版本化映射。方案亦涵蓋發布前契約測試、運行時 JSON Schema 校驗、熔斷降級與隔離佇列;第三方修復後可回放原始事件,並以冪等鍵避免重複寫單。
2026-11-22 8
版权
版权声明:
本文内容由阿里云实名注册用户自发贡献,版权归原作者所有,阿里云开发者社区不拥有其著作权,亦不承担相应法律责任。具体规则请查看《 阿里云开发者社区用户服务协议》和 《阿里云开发者社区知识产权保护指引》。如果您发现本社区中有涉嫌抄袭的内容,填写 侵权投诉表单进行举报,一经查实,本社区将立刻删除涉嫌侵权内容。
简介: 第三方物流接口返回200却发生字段和枚举漂移,旧Mock与CI无法发现。本文复盘Agent工具调用的契约校验、SDK与网关分工、熔断隔离、事件回放及可验证指标。
业务背景
售后 Agent 有一个看起来很普通的节点:调用第三方物流接口,确认发货结果,再把物流单号和配送状态写入 CRM。上线前测试全部通过,CI 也是绿色,但真实工单跑到这个节点时连续失败。
第三方接口没有宕机,HTTP 状态码仍然是 200。变化发生在响应体里:tracking_no 被改成 trackingNumber,配送状态从 DELIVERED 改成 SIGNED。旧 Mock 继续返回旧字段,Agent 在真实环境里取不到 tracking_no,后续 CRM 写入无法执行。
为什么这不是简单的空指针问题
如果只把它当成一次字段改名,补个字段就结束,后面还会遇到同类问题。外部接口的响应漂移至少包括字段缺失、类型变化、嵌套对象重命名、枚举值收窄、分页结构变化和错误响应结构变化。它们共同的特点是:服务进程还活着,但消费者和提供者之间的契约已经断了。
Mock 测试表达的是消费者当前假设,不代表提供者持续满足这个假设。因此我们把治理拆成两层:发布前通过消费者驱动契约和 OpenAPI 响应校验发现不一致;运行时在工具适配层或 API 网关做 JSON Schema 校验,拦截真实流量中的漂移。
架构选择:SDK 校验还是网关校验
团队当时讨论了两个位置。
放在工具 SDK 里,优点是离业务语义最近,能针对不同工具定义不同的错误处理和字段映射;缺点是多语言、多服务接入时容易出现规则不一致。放在统一 API 网关里,优点是契约版本、告警、熔断和日志可以统一管理;缺点是难以理解所有业务语义,复杂降级仍需业务服务配合。
最终采用“网关做通用契约校验,SDK 做业务适配和版本化映射”的组合。网关负责必填字段、枚举、Content-Type、错误响应结构等通用规则;SDK 负责字段兼容、状态归一化和写操作幂等。
故障隔离与恢复
校验失败后,系统不会立即重试。字段缺失不是瞬时网络故障,盲目重试只会放大调用量。我们先保存原始响应,生成事件 ID,再把工单放入隔离队列。断路器连续观察到契约违约后进入打开状态,快速失败并触发降级。
读操作可以使用带时间标记的安全缓存;写操作不能使用缓存自动补执行。第三方修复后,通过原始事件回放重新触发适配和 CRM 写入,并用幂等键避免重复回调造成重复写单。
可验证指标
这次改造关注的不是一句“稳定性提升”,而是任务级指标:工具成功率、契约违约率、熔断次数、缓存降级率、隔离队列积压、平均恢复时间、P95 延迟、重复回调拦截数。每个指标都要能按工具、接口版本和工单节点拆分。
工程结论
Agent 的工具调用不能只验证请求参数,也不能把响应可靠性寄托在第三方永远不变更上。发布前契约测试、运行时 Schema 校验、熔断降级、隔离队列和可回放事件,构成了完整的外部工具响应治理链路。
也留一个讨论问题:你们更倾向于在工具 SDK 里做契约校验,还是放在统一 API 网关里?
來源:阿里雲開發者社區 AI · developer.aliyun.com