首页
学习
活动
专区
圈层
工具
发布
社区首页 >专栏 >第三方接口返回200,Agent却在CRM写入前失败:运行时契约治理实战

第三方接口返回200,Agent却在CRM写入前失败:运行时契约治理实战

原创
作者头像
用户12114629
发布于 2026-11-22 17:00:40
发布于 2026-11-22 17:00:40
240
举报

一、问题现象

售后 Agent 在发货确认节点调用第三方物流接口。监控里没有 5xx,没有超时,接口一直返回 HTTP 200,但 12 个在途工单卡在发货确认环节,后续 CRM 写入没有执行。

一开始我们怀疑是网络抖动或限流,排查后发现不是。第三方把 tracking_no 重命名成 trackingNumber,同时把配送状态枚举从 DELIVERED 调整为 SIGNED。本地 Mock 仍按旧契约返回,CI 全绿;真实流量进来后,Agent 读取不到 tracking_no,工作流在 CRM 写入节点失败。

二、为什么 Mock 没拦住

Mock 只能证明我们的代码能处理“自己以为的响应”,不能证明第三方还在按这个响应提供数据。这个问题也不是工作流 Schema 门禁能完全覆盖的:工作流门禁关注发布前节点参数是否兼容,而外部 HTTP 接口的响应结构可能在运行时变化。

响应契约至少要覆盖四类内容:

  • 字段类:必填字段是否存在,字段类型是否变化;
  • 枚举类:状态值是否新增、删除或改名;
  • 结构类:嵌套对象、分页结构、错误响应是否调整;
  • 语义类:字段还在,但业务含义是否发生变化。

三、运行时校验怎么加

我们在工具适配层增加 JSON Schema 校验。第三方响应先经过契约校验,再进入 Agent 的业务解析。校验失败时不直接重试写操作,而是记录事件 ID、接口名、契约版本和失败原因,把工单放入隔离队列。

代码语言:python
复制
# 顶层工具适配层:先校验响应,再交给业务流程
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 写入等写操作不能靠缓存补执行。

降级路径也要明确:

  • 物流查询失败:返回最近一次安全缓存,并标记数据时间;
  • 发货确认失败:进入隔离队列,不自动推进工单;
  • 回调重复到达:用事件 ID 和幂等键拦截;
  • 接口恢复后:基于原始事件回放,再重新执行 CRM 写入。

五、上线后的观察指标

这次改造后,我们重点看工具成功率、契约违约率、熔断次数、缓存降级率、隔离队列积压、平均恢复时间、P95 延迟和重复回调拦截数。

契约测试负责发布前发现不一致,运行时校验负责拦截真实响应漂移,熔断和隔离队列负责控制故障影响范围。三者不能互相替代。对于需要调用外部 HTTP 接口的企业级 Agent,只校验请求参数还不够,响应契约同样要进入工程治理。

原创声明:本文系作者授权腾讯云开发者社区发表,未经许可,不得转载。

如有侵权,请联系 cloudcommunity@tencent.com 删除。

目录
  • 一、问题现象
  • 二、为什么 Mock 没拦住
  • 三、运行时校验怎么加
  • 四、熔断和降级边界
  • 五、上线后的观察指标
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档