OpenAI把API设计翻了个底朝天：5个改动让AI代理不再发疯

去年冬天，某电商平台凌晨3点被AI代理灌了12000笔重复订单。不是黑客攻击——是某个企业客户的自动化脚本在疯狂重试。API返回超时，代理以为没成功，于是再试一次。再试一次。再试一次。

人类开发者会看错误码，会读文档里的"注意事项"，会停下来想"是不是服务器卡了"。AI代理不会。它们读的是OpenAPI规范（开放API规范，一种机器可读的接口描述格式），逐字执行，循环调用，20个请求链在一起不带喘气。

你的API设计还在服务前端程序员点按钮，但新用户已经是7×24小时运行的自主代理。

从"大概懂"到"必须懂"：文档的颗粒度革命

人类看描述能猜意图。看到"创建订单"，程序员会脑补"这应该是草稿状态吧？得确认后才扣款吧？"AI代理不脑补，它只信规范里写了什么。

选错端口的代价，往往只差一句话。FastAPI（一个Python Web框架）的Field描述字段，现在成了产品决策现场。

「Create a new order. Does NOT charge the customer. Use POST /orders/{order_id}/confirm to finalize and charge.」

这段描述在代码里看着啰嗦，但对代理是生死线。没有它，代理可能在测试环境直接调用生产支付接口。没有格式说明"cust_xxxxxxxxxxxx"，代理会发明自己的ID格式然后报错。

三个以前可以模糊、现在必须精确的东西：货币单位（USD cents还是dollars？）、状态流转（草稿→确认→完成）、字段格式（正则表达式写进description）。

还有暴露规范本身。人类开发者从落地页找API入口，代理从/openapi.json（标准规范端点）发现能力。没这个端点，代理连你有哪些接口都不知道。

幂等性：给重试机制上保险

每个代理框架都内置重试。LangChain（一个AI应用开发框架）遇到异常就重试，OpenAI的函数调用（function calling，让模型能调用外部工具的能力）遇到格式错误就重试，你自己的代理循环遇到超时就重试。

没有幂等性键（Idempotency Key，保证同一请求多次执行结果相同的唯一标识），每次重试都是新订单。一个"创建订单"的意图，变成三个订单、三笔扣款、三个物流单号。

实现不复杂：客户端生成唯一键，服务端24小时内遇到相同键直接返回缓存结果。Redis（一个内存数据库）或数据库都能做。关键是这个键必须从客户端来——代理才知道"我刚才那个请求"和"我现在这个请求"是同一个意图。

HTTP头里的Idempotency-Key字段，现在和Authorization（授权令牌）一样基础。

错误信息：从"给人看"到"给机器修"

人类喜欢"操作失败，请联系管理员"。代理需要"amount_cents字段超出范围，最大值99999999，当前值150000000"。

结构化错误响应是新的刚需。JSON Schema（一种数据格式验证标准）描述错误结构，让代理能程序化地解析：是参数错了？权限不够？还是资源不存在？每种情况对应不同的修复策略。

状态码也得诚实。200 OK但body里藏错误，是人类UI的坏习惯，对代理是灾难。代理看到200就以为成功，继续下一步，把错误数据传进下游。

更隐蔽的是部分成功。批量接口里5个item成功了3个，人类扫一眼列表能发现，代理需要明确的子状态码和可索引的错误对应关系。

限流与配额：从"防滥用"到"防误伤"

传统限流按IP或用户，代理场景下同一个"用户"可能是100个并发实例。更麻烦的是代理的调用模式：不是人类式的"点一下等结果"，而是"发20个请求然后处理响应"。

新的限流维度在涌现：按会话（session，一次连续交互的上下文）、按意图链（intent chain，完成一个目标所需的请求序列）、按计算成本预估。429状态码（Too Many Requests，请求过多）的响应头里，Retry-After（建议重试时间）和X-RateLimit-Reset（配额重置时间）成了代理的导航信号。

配额信息要主动暴露。代理需要知道"我还剩多少额度"来决定是继续还是暂停，而不是盲打到403（Forbidden，禁止访问）才知道超限。

可观测性：在代理黑箱里开灯

代理的调试是连锁反应。第一步请求失败，第二步用错误数据继续，第三步把错误放大，第四步触发了补偿机制——等你看到日志，已经是一团乱麻。

请求ID要贯穿整个链。从代理的第一次调用，到后端服务的所有下游，同一个X-Request-ID（请求追踪标识）把分布式日志串成故事线。

更激进的是代理意图标注。让调用方在头里声明"这批请求属于订单创建流程"，后端就能按业务语义聚合监控，而不是只看HTTP路径的散点。

OpenTelemetry（一种可观测性标准）的trace上下文（追踪上下文，传递调用链信息的机制）现在该进API网关的强制头了。

某云厂商的API团队在内部复盘里写：「我们花了三个月把错误信息改完，代理客户的支持工单下降了70%。不是代理变聪明了，是API终于说清楚了。」

你的API准备好被机器"阅读"了吗？还是说，你还在等下一个凌晨3点的电话？