智能体的工具接口一旦上线,调用方就散出去了:不同的智能体、不同的版本、不同的团队都在调同一个工具。这时候工具的 schema 每改一次,都可能让一批旧调用方翻车。最常见的翻车有三种:字段改名,旧调用方传的字段没人认了;必填项新增,旧调用方没传就被拒绝;字段含义悄悄变了,调用方按老理解传值,结果跑出错误动作。
演化规则的第一条是只加不改。新增字段只能是可选的,并且要有明确的默认值,让旧调用方不传也能跑出和原来一致的行为;已有的字段不改名、不改类型、不改含义,实在要改就新增一个字段,老字段进入废弃流程,而不是直接替换。含义变更是最危险的一类:表面上字段名没变,语义却变了,调用方毫无察觉,测试也很难覆盖,所以要当作破坏性变更来对待。
第二条是给废弃留出窗口。字段标记废弃后不要立刻删除,先在文档和返回值里提示,留出足够长的过渡期,让调用方有时间迁移;过渡期结束再删除,删除前还要确认线上流量里已经没有旧字段的使用。废弃清单要集中维护,而不是散落在各处注释里。
第三条是把 schema 当作正式资产来管:集中注册、统一版本、变更走评审。每次变更都记录在案:改了什么、影响谁、是否破坏兼容、过渡期到什么时候;发布前跑一遍兼容检查,用旧版本的调用样本验证新 schema 是否还能正常工作;重大变更先双版本并行跑一段时间,确认旧流量平稳迁移后再下线老版本。
落地时可以先从三件事做起:冻结一次破坏性变更的清单,把已经存在的兼容问题先修掉;给每个工具建一份 schema 变更记录,新人接手先读记录再改接口;发布流程里加一道兼容检查关口,不通过不上线。接口演化拼的不是改得有多快,而是旧调用方能不能在不知不觉中继续工作。