去年冬天，某電商平臺(tái)凌晨3點(diǎn)被AI代理灌了12000筆重復(fù)訂單。不是黑客攻擊——是某個(gè)企業(yè)客戶的自動(dòng)化腳本在瘋狂重試。API返回超時(shí)，代理以為沒成功，于是再試一次。再試一次。再試一次。

人類開發(fā)者會(huì)看錯(cuò)誤碼，會(huì)讀文檔里的"注意事項(xiàng)"，會(huì)停下來想"是不是服務(wù)器卡了"。AI代理不會(huì)。它們讀的是OpenAPI規(guī)范（開放API規(guī)范，一種機(jī)器可讀的接口描述格式），逐字執(zhí)行，循環(huán)調(diào)用，20個(gè)請(qǐng)求鏈在一起不帶喘氣。

你的API設(shè)計(jì)還在服務(wù)前端程序員點(diǎn)按鈕，但新用戶已經(jīng)是7×24小時(shí)運(yùn)行的自主代理。

從"大概懂"到"必須懂"：文檔的顆粒度革命

人類看描述能猜意圖?？吹?創(chuàng)建訂單"，程序員會(huì)腦補(bǔ)"這應(yīng)該是草稿狀態(tài)吧？得確認(rèn)后才扣款吧？"AI代理不腦補(bǔ)，它只信規(guī)范里寫了什么。

選錯(cuò)端口的代價(jià)，往往只差一句話。FastAPI（一個(gè)Python Web框架）的Field描述字段，現(xiàn)在成了產(chǎn)品決策現(xiàn)場(chǎng)。

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

這段描述在代碼里看著啰嗦，但對(duì)代理是生死線。沒有它，代理可能在測(cè)試環(huán)境直接調(diào)用生產(chǎn)支付接口。沒有格式說明"cust_xxxxxxxxxxxx"，代理會(huì)發(fā)明自己的ID格式然后報(bào)錯(cuò)。

三個(gè)以前可以模糊、現(xiàn)在必須精確的東西：貨幣單位（USD cents還是dollars？）、狀態(tài)流轉(zhuǎn)（草稿→確認(rèn)→完成）、字段格式（正則表達(dá)式寫進(jìn)description）。

還有暴露規(guī)范本身。人類開發(fā)者從落地頁找API入口，代理從/openapi.json（標(biāo)準(zhǔn)規(guī)范端點(diǎn)）發(fā)現(xiàn)能力。沒這個(gè)端點(diǎn)，代理連你有哪些接口都不知道。

冪等性：給重試機(jī)制上保險(xiǎn)

每個(gè)代理框架都內(nèi)置重試。LangChain（一個(gè)AI應(yīng)用開發(fā)框架）遇到異常就重試，OpenAI的函數(shù)調(diào)用（function calling，讓模型能調(diào)用外部工具的能力）遇到格式錯(cuò)誤就重試，你自己的代理循環(huán)遇到超時(shí)就重試。

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

實(shí)現(xiàn)不復(fù)雜：客戶端生成唯一鍵，服務(wù)端24小時(shí)內(nèi)遇到相同鍵直接返回緩存結(jié)果。Redis（一個(gè)內(nèi)存數(shù)據(jù)庫）或數(shù)據(jù)庫都能做。關(guān)鍵是這個(gè)鍵必須從客戶端來——代理才知道"我剛才那個(gè)請(qǐng)求"和"我現(xiàn)在這個(gè)請(qǐng)求"是同一個(gè)意圖。

HTTP頭里的Idempotency-Key字段，現(xiàn)在和Authorization（授權(quán)令牌）一樣基礎(chǔ)。

錯(cuò)誤信息：從"給人看"到"給機(jī)器修"

人類喜歡"操作失敗，請(qǐng)聯(lián)系管理員"。代理需要"amount_cents字段超出范圍，最大值99999999，當(dāng)前值150000000"。

結(jié)構(gòu)化錯(cuò)誤響應(yīng)是新的剛需。JSON Schema（一種數(shù)據(jù)格式驗(yàn)證標(biāo)準(zhǔn)）描述錯(cuò)誤結(jié)構(gòu)，讓代理能程序化地解析：是參數(shù)錯(cuò)了？權(quán)限不夠？還是資源不存在？每種情況對(duì)應(yīng)不同的修復(fù)策略。

狀態(tài)碼也得誠實(shí)。200 OK但body里藏錯(cuò)誤，是人類UI的壞習(xí)慣，對(duì)代理是災(zāi)難。代理看到200就以為成功，繼續(xù)下一步，把錯(cuò)誤數(shù)據(jù)傳進(jìn)下游。

更隱蔽的是部分成功。批量接口里5個(gè)item成功了3個(gè)，人類掃一眼列表能發(fā)現(xiàn)，代理需要明確的子狀態(tài)碼和可索引的錯(cuò)誤對(duì)應(yīng)關(guān)系。

限流與配額：從"防濫用"到"防誤傷"

傳統(tǒng)限流按IP或用戶，代理場(chǎng)景下同一個(gè)"用戶"可能是100個(gè)并發(fā)實(shí)例。更麻煩的是代理的調(diào)用模式：不是人類式的"點(diǎn)一下等結(jié)果"，而是"發(fā)20個(gè)請(qǐng)求然后處理響應(yīng)"。

新的限流維度在涌現(xiàn)：按會(huì)話（session，一次連續(xù)交互的上下文）、按意圖鏈（intent chain，完成一個(gè)目標(biāo)所需的請(qǐng)求序列）、按計(jì)算成本預(yù)估。429狀態(tài)碼（Too Many Requests，請(qǐng)求過多）的響應(yīng)頭里，Retry-After（建議重試時(shí)間）和X-RateLimit-Reset（配額重置時(shí)間）成了代理的導(dǎo)航信號(hào)。

配額信息要主動(dòng)暴露。代理需要知道"我還剩多少額度"來決定是繼續(xù)還是暫停，而不是盲打到403（Forbidden，禁止訪問）才知道超限。

可觀測(cè)性：在代理黑箱里開燈

代理的調(diào)試是連鎖反應(yīng)。第一步請(qǐng)求失敗，第二步用錯(cuò)誤數(shù)據(jù)繼續(xù)，第三步把錯(cuò)誤放大，第四步觸發(fā)了補(bǔ)償機(jī)制——等你看到日志，已經(jīng)是一團(tuán)亂麻。

請(qǐng)求ID要貫穿整個(gè)鏈。從代理的第一次調(diào)用，到后端服務(wù)的所有下游，同一個(gè)X-Request-ID（請(qǐng)求追蹤標(biāo)識(shí)）把分布式日志串成故事線。

更激進(jìn)的是代理意圖標(biāo)注。讓調(diào)用方在頭里聲明"這批請(qǐng)求屬于訂單創(chuàng)建流程"，后端就能按業(yè)務(wù)語義聚合監(jiān)控，而不是只看HTTP路徑的散點(diǎn)。

OpenTelemetry（一種可觀測(cè)性標(biāo)準(zhǔn)）的trace上下文（追蹤上下文，傳遞調(diào)用鏈信息的機(jī)制）現(xiàn)在該進(jìn)API網(wǎng)關(guān)的強(qiáng)制頭了。

某云廠商的API團(tuán)隊(duì)在內(nèi)部復(fù)盤里寫：「我們花了三個(gè)月把錯(cuò)誤信息改完，代理客戶的支持工單下降了70%。不是代理變聰明了，是API終于說清楚了?！?/p>

你的API準(zhǔn)備好被機(jī)器"閱讀"了嗎？還是說，你還在等下一個(gè)凌晨3點(diǎn)的電話？