OpenAI把API設(shè)計(jì)逼到墻角：5個(gè)補(bǔ)丁讓系統(tǒng)扛住凌晨3點(diǎn)的A

凌晨3點(diǎn)，你的支付系統(tǒng)突然收到47次相同的扣款請求。不是攻擊，是一個(gè)AI代理（AI Agent，自主執(zhí)行任務(wù)的智能程序）在循環(huán)重試。它沒看明白你的文檔，以為"創(chuàng)建訂單"就是"扣款"。

這不是科幻。LangChain、OpenAI Function Calling這些框架里的代理，正在以每秒20次的速度調(diào)用API。它們不讀你的落地頁，直接解析OpenAPI規(guī)范（一種機(jī)器可讀的API描述格式）。描述寫錯(cuò)一個(gè)字，代理就走錯(cuò)一條路。

你的API是給前端開發(fā)者設(shè)計(jì)的——人類會(huì)猶豫、會(huì)確認(rèn)、會(huì)在報(bào)錯(cuò)時(shí)停下來想。AI不會(huì)。它們把模糊描述當(dāng)真理，把臨時(shí)故障當(dāng)永久失敗，把重試機(jī)制當(dāng)無限循環(huán)的許可證。

補(bǔ)丁1：把"顯然"寫進(jìn)代碼注釋里

人類開發(fā)者看文檔能猜意圖。AI代理只看OpenAPI規(guī)范里的description字段，而且照字面執(zhí)行。

下面這個(gè)例子來自原文，展示了什么叫"差一個(gè)字，錯(cuò)一條路"：

```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, ) ```

注意那個(gè)大寫的"Does NOT charge the customer"。沒有這句話，代理可能直接調(diào)用創(chuàng)建訂單然后告訴用戶"已完成支付"。30分鐘后草稿過期，用戶的錢沒扣，貨也沒發(fā)，客服工單爆炸。

三個(gè)代理需要、但人類自己腦補(bǔ)的東西：

第一，把規(guī)范暴露在標(biāo)準(zhǔn)端點(diǎn)，比如/openapi.json。代理發(fā)現(xiàn)API靠這個(gè)，不是你的營銷頁面。

第二，字段描述要包含格式約束。"cust_xxxxxxxxxxxx"比"customer ID"讓代理少打一次試錯(cuò)電話。

第三，端點(diǎn)summary必須說明副作用。"Create a draft order (does not charge customer)"——括號里的否定句，是防止凌晨3點(diǎn)災(zāi)難的保險(xiǎn)。

補(bǔ)丁2：冪等鍵不是可選項(xiàng)，是生存必需品

每個(gè)代理框架都內(nèi)置重試邏輯。LangChain遇到異常就重試。OpenAI的函數(shù)調(diào)用遇到格式錯(cuò)誤就重試。你自己的代理循環(huán)遇到超時(shí)也重試。

沒有冪等鍵（Idempotency Key，保證同一操作多次執(zhí)行結(jié)果相同的唯一標(biāo)識(shí)），每次重試都是一筆新訂單。一個(gè)"創(chuàng)建訂單"的意圖，變成三個(gè)訂單、三筆扣款、三個(gè)物流包裹。

原文給了一個(gè)最小可行實(shí)現(xiàn)：

```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"] # 處理支付，存儲(chǔ)結(jié)果 result = process_payment(amount_cents, customer_id) idempotency_store[idempotency_key] = { "response": result, "timestamp": time.time() } return result ```

生產(chǎn)環(huán)境用Redis或數(shù)據(jù)庫替代那個(gè)內(nèi)存字典。TTL設(shè)24小時(shí)足夠覆蓋大多數(shù)代理的超時(shí)窗口。

關(guān)鍵細(xì)節(jié)：代理不會(huì)自己生成冪等鍵。你的API要在首次返回時(shí)明確告訴它"下次帶這個(gè)鍵來"，或者在規(guī)范里寫明鍵的生成規(guī)則。否則代理會(huì)傻乎乎地重試，然后被你返回的"重復(fù)鍵錯(cuò)誤"搞懵。

補(bǔ)丁3：把"部分成功"設(shè)計(jì)成一等公民

人類看到"3個(gè)成功，2個(gè)失敗"會(huì)手動(dòng)處理。代理看到200狀態(tài)碼就認(rèn)為全成功了，或者直接崩潰。

批量操作要返回詳細(xì)結(jié)果數(shù)組，每個(gè)元素有自己的狀態(tài)碼和錯(cuò)誤信息。不要用一個(gè)總狀態(tài)碼掩蓋局部失敗。

錯(cuò)誤信息要機(jī)器可讀。"Invalid SKU"對代理沒用。"SKU 'ABC-123' not found in catalog. Valid format: XXX-NNNN. Did you mean 'ABC-124'?"——這種錯(cuò)誤代理能自己修，不用叫醒你。

原文沒提但值得補(bǔ)充：考慮給代理專用的" dry-run"端點(diǎn)。讓它們在真正執(zhí)行前先模擬一遍，返回"我會(huì)調(diào)用A、B、C三個(gè)端點(diǎn)，預(yù)計(jì)產(chǎn)生X、Y、Z副作用"。人類不看這個(gè)，但代理能用它做自我檢查。

補(bǔ)丁4：速率限制要分人類和代理兩本賬

你的API可能已經(jīng)有速率限制。但那是給人類點(diǎn)的按鈕設(shè)計(jì)的——每秒5次夠用了。

代理的循環(huán)可能在一秒內(nèi)觸發(fā)20次調(diào)用。不是惡意，是它們在鏈?zhǔn)酵评恚翰閹齑妗銉r(jià)格→應(yīng)用優(yōu)惠→創(chuàng)建草稿→確認(rèn)支付→通知倉庫。六步流程，人類要6分鐘，代理要6秒。

分桶限速：人類令牌桶寬松，代理令牌桶更寬松但要求強(qiáng)制身份標(biāo)識(shí)。讓代理在Header里聲明"我是Claude-3-Sonnet-20240229-v1"，你就能區(qū)分是用戶在測試還是代理在暴走。

更激進(jìn)的方案：給代理專用端點(diǎn)。/v1/agent/orders 和 /v1/orders 共享業(yè)務(wù)邏輯，但前者接受更復(fù)雜的查詢參數(shù)，返回更結(jié)構(gòu)化的錯(cuò)誤，允許更高的并發(fā)。人類開發(fā)者不會(huì)用這些端點(diǎn)——太啰嗦。代理不會(huì)用普通端點(diǎn)——太慢太脆。

補(bǔ)丁5：把"不確定"設(shè)計(jì)成可恢復(fù)的狀態(tài)

代理遇到未預(yù)期響應(yīng)時(shí)的默認(rèn)行為是重試。如果你的API返回500，它會(huì)等兩秒再試。再500，等四秒。再500，等八秒。指數(shù)退避，直到成功或超時(shí)。

但有些失敗不該重試。信用卡余額不足，重試100次也是不足。庫存為零，重試100次也是零。這些要返回明確的4xx狀態(tài)碼，讓代理知道"這不是臨時(shí)故障，是業(yè)務(wù)規(guī)則阻止"。

更微妙的是"我不確定"狀態(tài)。支付網(wǎng)關(guān)超時(shí)，你不知道錢扣了沒。對人類，你顯示"處理中，請稍后查詢"。對代理，你要返回一個(gè)"pending"狀態(tài)和一個(gè)查詢端點(diǎn)，讓它能輪詢而不是重試創(chuàng)建。

原文強(qiáng)調(diào)的最后一個(gè)細(xì)節(jié)：代理會(huì)記住你的錯(cuò)誤模式。如果一個(gè)端點(diǎn)經(jīng)常500，代理框架的日志里會(huì)積累失敗記錄。下次規(guī)劃任務(wù)時(shí)，它可能繞開你——不是惡意，是優(yōu)化。你的API從"不太好用"變成"盡量不用"，只需要三次超時(shí)。

凌晨3點(diǎn)的那47次重試，最后怎么解決的？

原文沒講。但你可以檢查自己的日志：有沒有代理在循環(huán)調(diào)用同一個(gè)端點(diǎn)？有沒有創(chuàng)建后從未確認(rèn)的草稿訂單？有沒有支付網(wǎng)關(guān)超時(shí)后代理直接放棄，留下懸而未決的交易？

這些問題現(xiàn)在不解決，等代理用戶占比從1%漲到50%時(shí)，你的 on-call 工程師會(huì)先崩潰。