售后 Agent 在发货确认节点调用第三方物流接口。监控里没有 5xx,没有超时,接口一直返回 HTTP 200,但 12 个在途工单卡在发货确认环节,后续 CRM 写入没有执行。
一开始我们怀疑是网络抖动或限流,排查后发现不是。第三方把 tracking_no 重命名成 trackingNumber,同时把配送状态枚举从 DELIVERED 调整为 SIGNED。本地 Mock 仍按旧契约返回,CI 全绿;真实流量进来后,Agent 读取不到 tracking_no,工作流在 CRM 写入节点失败。
Mock 只能证明我们的代码能处理“自己以为的响应”,不能证明第三方还在按这个响应提供数据。这个问题也不是工作流 Schema 门禁能完全覆盖的:工作流门禁关注发布前节点参数是否兼容,而外部 HTTP 接口的响应结构可能在运行时变化。
响应契约至少要覆盖四类内容:
我们在工具适配层增加 JSON Schema 校验。第三方响应先经过契约校验,再进入 Agent 的业务解析。校验失败时不直接重试写操作,而是记录事件 ID、接口名、契约版本和失败原因,把工单放入隔离队列。
# 顶层工具适配层:先校验响应,再交给业务流程
def handle_logistics_response(resp):
payload = resp.json()
errors = logistics_schema.validate(payload)
if errors:
# 不盲目重试,先保留原始响应并进入隔离队列
event_id = save_raw_event("logistics", payload, errors)
push_to_repair_queue(event_id)
return {"status": "contract_violation", "event_id": event_id}
tracking_no = payload["trackingNumber"]
status = normalize_status(payload["status"])
return {"tracking_no": tracking_no, "status": status}这里没有把校验放在大模型提示词里,因为提示词约束不稳定,也无法形成可审计的发布门禁。Schema 校验必须是确定性代码,才能和 CI、监控、告警串起来。
第三方接口连续出现契约违约时,断路器达到阈值后快速失败,避免 Agent 持续调用一个已知不兼容的接口。读操作可以使用带 TTL 的安全缓存,但只允许用于查询类节点;发货确认、CRM 写入等写操作不能靠缓存补执行。
降级路径也要明确:
这次改造后,我们重点看工具成功率、契约违约率、熔断次数、缓存降级率、隔离队列积压、平均恢复时间、P95 延迟和重复回调拦截数。
契约测试负责发布前发现不一致,运行时校验负责拦截真实响应漂移,熔断和隔离队列负责控制故障影响范围。三者不能互相替代。对于需要调用外部 HTTP 接口的企业级 Agent,只校验请求参数还不够,响应契约同样要进入工程治理。
原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。
如有侵权,请联系 cloudcommunity@tencent.com 删除。