OpenAI把API设计逼到墙角：5个补丁让系统扛住凌晨3点的A|key|openai|凌晨3点|系统|调用|重试

凌晨3点，你的支付系统突然收到47次相同的扣款请求。不是攻击，是一个AI代理（AI Agent，自主执行任务的智能程序）在循环重试。它没看明白你的文档，以为"创建订单"就是"扣款"。

这不是科幻。LangChain、OpenAI Function Calling这些框架里的代理，正在以每秒20次的速度调用API。它们不读你的落地页，直接解析OpenAPI规范（一种机器可读的API描述格式）。描述写错一个字，代理就走错一条路。

你的API是给前端开发者设计的——人类会犹豫、会确认、会在报错时停下来想。AI不会。它们把模糊描述当真理，把临时故障当永久失败，把重试机制当无限循环的许可证。

补丁1：把"显然"写进代码注释里

人类开发者看文档能猜意图。AI代理只看OpenAPI规范里的description字段，而且照字面执行。

下面这个例子来自原文，展示了什么叫"差一个字，错一条路"：

```python class OrderCreate(BaseModel): """Create a new order. Does NOT charge the customer. Use POST /orders/{order_id}/confirm to finalize and charge.""" customer_id: str = Field( description="Unique customer identifier. Format: cust_xxxxxxxxxxxx" ) items: list[str] = Field( description="List of SKU strings. Each SKU must exist in the product catalog." ) amount_cents: int = Field( description="Total order amount in USD cents. Must match sum of item prices.", ge=1, ) ```

注意那个大写的"Does NOT charge the customer"。没有这句话，代理可能直接调用创建订单然后告诉用户"已完成支付"。30分钟后草稿过期，用户的钱没扣，货也没发，客服工单爆炸。

三个代理需要、但人类自己脑补的东西：

第一，把规范暴露在标准端点，比如/openapi.json。代理发现API靠这个，不是你的营销页面。

第二，字段描述要包含格式约束。"cust_xxxxxxxxxxxx"比"customer ID"让代理少打一次试错电话。

第三，端点summary必须说明副作用。"Create a draft order (does not charge customer)"——括号里的否定句，是防止凌晨3点灾难的保险。

补丁2：幂等键不是可选项，是生存必需品

每个代理框架都内置重试逻辑。LangChain遇到异常就重试。OpenAI的函数调用遇到格式错误就重试。你自己的代理循环遇到超时也重试。

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

原文给了一个最小可行实现：

```python @app.post("/payments") async def create_payment( amount_cents: int, customer_id: str, response: Response, idempotency_key: Optional[str] = Header(None, alias="Idempotency-Key"), ): if idempotency_key is None: raise HTTPException(status_code=400, detail="Idempotency-Key required") # 检查是否处理过 if idempotency_key in idempotency_store: return idempotency_store[idempotency_key]["response"] # 处理支付，存储结果 result = process_payment(amount_cents, customer_id) idempotency_store[idempotency_key] = { "response": result, "timestamp": time.time() } return result ```

生产环境用Redis或数据库替代那个内存字典。TTL设24小时足够覆盖大多数代理的超时窗口。