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點的電話？