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

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

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

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

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

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

```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"。沒有這句話，代理可能直接調(diào)用創(chuàng)建訂單然后告訴用戶"已完成支付"。30分鐘后草稿過期，用戶的錢沒扣，貨也沒發(fā)，客服工單爆炸。

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

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

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

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

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

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

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

原文給了一個最小可行實現(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"] # 處理支付，存儲結(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ù)庫替代那個內(nèi)存字典。TTL設(shè)24小時足夠覆蓋大多數(shù)代理的超時窗口。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

凌晨3點的那47次重試，最后怎么解決的？

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

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