1. 工具運(yùn)行時(shí)的核心設(shè)計(jì)哲學(xué)1.1 為什么“失敗是數(shù)據(jù)”不是一句口號(hào)做 Agent 開發(fā)的人遲早會(huì)撞上一個(gè)繞不過(guò)去的坎工具調(diào)用失敗了然后呢大部分人的第一反應(yīng)是——重試。重試不行就報(bào)錯(cuò)報(bào)錯(cuò)不行就終止。這個(gè)思路在傳統(tǒng)后端開發(fā)里沒(méi)毛病接口掛了就重試重試超限就拋異常天經(jīng)地義。但放到 Agent 場(chǎng)景里這套邏輯會(huì)直接把你的智能體變成一個(gè)“玻璃心”——一次工具調(diào)用失敗整個(gè)任務(wù)鏈斷裂用戶看到的就是一句冷冰冰的“執(zhí)行出錯(cuò)請(qǐng)重試”。我在實(shí)際搭建 Agent 的過(guò)程中踩過(guò)這個(gè)坑。早期版本里我寫了一個(gè)查天氣的工具API 偶爾超時(shí)Agent 拿到超時(shí)錯(cuò)誤后直接放棄了整個(gè)對(duì)話用戶問(wèn)“北京明天天氣怎么樣適合穿什么”它回一句“抱歉我無(wú)法獲取天氣信息”。但用戶真正想要的是穿搭建議天氣只是中間步驟。如果我把“超時(shí)”這個(gè)失敗當(dāng)作一條數(shù)據(jù)喂回給模型模型完全可以決定換個(gè)方式查、用歷史數(shù)據(jù)推斷、或者直接告訴用戶“天氣數(shù)據(jù)暫時(shí)拿不到但根據(jù)季節(jié)和一般規(guī)律建議你……”這就是“失敗是數(shù)據(jù)”的核心含義工具運(yùn)行時(shí)的每一次失敗不是流程的終點(diǎn)而是下一輪推理的輸入。1.2 傳統(tǒng)工具調(diào)用 vs Agent 工具運(yùn)行時(shí)的本質(zhì)差異要理解這個(gè)設(shè)計(jì)得先看清楚 Agent 工具運(yùn)行時(shí)和傳統(tǒng)函數(shù)調(diào)用之間的根本區(qū)別。傳統(tǒng)函數(shù)調(diào)用是這樣的你調(diào)一個(gè)函數(shù)傳參數(shù)拿返回值。返回值要么是成功的結(jié)果要么是異常。異常就是異常它不屬于“結(jié)果”的一部分它是流程控制的一部分。Agent 工具運(yùn)行時(shí)不一樣。Agent 的每一次工具調(diào)用本質(zhì)上是在和模型進(jìn)行一輪“對(duì)話”。模型說(shuō)“我要調(diào)這個(gè)工具參數(shù)是這些”運(yùn)行時(shí)執(zhí)行完把結(jié)果——不管成功還是失敗——作為一條新的消息塞回對(duì)話歷史然后模型基于這條新消息決定下一步做什么。這個(gè)差異帶來(lái)的直接后果是失敗信息必須被結(jié)構(gòu)化必須能被模型理解必須攜帶足夠的上下文讓模型做出下一步?jīng)Q策。我見(jiàn)過(guò)太多 Agent 項(xiàng)目工具報(bào)錯(cuò)就返回一個(gè){error: something went wrong}模型拿到這個(gè)信息完全懵——它不知道是參數(shù)錯(cuò)了、網(wǎng)絡(luò)超時(shí)了、還是權(quán)限不夠了。它唯一能做的就是重試同樣的調(diào)用然后再次失敗陷入死循環(huán)。1.3 失敗分類哪些失敗該吞哪些該吐不是所有失敗都值得喂回給模型。我在實(shí)踐中把工具失敗分成三類失敗類型典型場(chǎng)景處理策略可恢復(fù)失敗網(wǎng)絡(luò)超時(shí)、限流、臨時(shí)不可用結(jié)構(gòu)化返回讓模型決定重試或換路參數(shù)錯(cuò)誤參數(shù)格式不對(duì)、缺少必填項(xiàng)返回具體校驗(yàn)信息模型可自我修正不可恢復(fù)失敗權(quán)限不足、資源不存在、邏輯死鎖返回明確原因引導(dǎo)模型放棄該路徑關(guān)鍵判斷標(biāo)準(zhǔn)是這個(gè)失敗信息能不能幫助模型做出更好的下一步?jīng)Q策能就喂回去不能就吞掉并返回一個(gè)更通用的提示。舉個(gè)例子JSON Schema 校驗(yàn)失敗你返回參數(shù) age 應(yīng)為整數(shù)實(shí)際收到字符串 25模型看到這個(gè)信息下一輪大概率會(huì)把25改成25。但如果你返回參數(shù)校驗(yàn)失敗模型只能瞎猜。2. 工具運(yùn)行時(shí)的核心架構(gòu)拆解2.1 一次工具調(diào)用的完整生命周期要落地“失敗是數(shù)據(jù)”這個(gè)理念得先搞清楚一次工具調(diào)用從發(fā)起到結(jié)束中間到底經(jīng)歷了什么。我把它拆成六個(gè)階段第一階段意圖識(shí)別與工具選擇。模型根據(jù)當(dāng)前對(duì)話上下文決定是否需要調(diào)用工具以及調(diào)用哪個(gè)工具。這個(gè)階段模型輸出的是一個(gè)結(jié)構(gòu)化的調(diào)用請(qǐng)求通常包含工具名和參數(shù)。第二階段參數(shù)校驗(yàn)。運(yùn)行時(shí)拿到調(diào)用請(qǐng)求后第一件事不是執(zhí)行而是校驗(yàn)。用 JSON Schema 對(duì)參數(shù)做類型檢查、必填項(xiàng)檢查、范圍檢查。這一步能攔掉大量低級(jí)錯(cuò)誤。第三階段執(zhí)行前準(zhǔn)備。包括權(quán)限檢查、資源鎖定、超時(shí)設(shè)置、重試策略加載。這一步?jīng)Q定了工具能不能跑、怎么跑。第四階段實(shí)際執(zhí)行。調(diào)用底層函數(shù)或外部服務(wù)拿到原始結(jié)果或原始異常。第五階段結(jié)果歸一化。把成功結(jié)果和失敗異常統(tǒng)一轉(zhuǎn)換成模型能理解的結(jié)構(gòu)化數(shù)據(jù)。這是“失敗是數(shù)據(jù)”落地的關(guān)鍵環(huán)節(jié)。第六階段回填對(duì)話歷史。把歸一化后的結(jié)果作為一條新消息追加到對(duì)話歷史中觸發(fā)模型的下一輪推理。這六個(gè)階段里第二和第五階段是最容易被忽視的。很多人只關(guān)注“怎么調(diào)”不關(guān)注“怎么校驗(yàn)”和“怎么返回”。2.2 JSON Schema不只是參數(shù)校驗(yàn)更是契約JSON Schema 在工具運(yùn)行時(shí)里的角色遠(yuǎn)不止“校驗(yàn)參數(shù)”這么簡(jiǎn)單。它實(shí)際上是模型和工具之間的契約。我剛開始寫工具定義的時(shí)候Schema 寫得很隨意type: object加幾個(gè)properties就完事了。結(jié)果模型經(jīng)常傳一些莫名其妙的參數(shù)進(jìn)來(lái)比如該傳數(shù)組的傳了字符串該傳枚舉值的傳了自由文本。后來(lái)我把 Schema 寫嚴(yán)格了情況立刻好轉(zhuǎn)。一個(gè)完整的工具 Schema 應(yīng)該包含這些信息{ name: query_weather, description: 查詢指定城市的天氣信息返回當(dāng)前天氣和未來(lái)三天預(yù)報(bào), parameters: { type: object, properties: { city: { type: string, description: 城市名稱如北京、上海 }, date: { type: string, format: date, description: 查詢?nèi)掌诟袷?YYYY-MM-DD默認(rèn)為今天 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius, description: 溫度單位 } }, required: [city] } }這里有幾個(gè)細(xì)節(jié)值得說(shuō)description不是寫給人看的是寫給模型看的。模型靠它來(lái)判斷什么時(shí)候該調(diào)這個(gè)工具、參數(shù)該怎么填。描述寫得越清楚模型調(diào)用越準(zhǔn)確。enum是約束模型輸出的利器。能用枚舉就別用自由文本能限定格式就別放任。required明確告訴模型哪些參數(shù)必須提供減少“缺參數(shù)”類失敗。實(shí)操心得Schema 的 description 字段我一般會(huì)寫兩遍——一遍給模型看說(shuō)明用途一遍給自己看說(shuō)明邊界條件。模型看不懂邊界條件但你自己維護(hù)的時(shí)候需要。2.3 運(yùn)行時(shí)狀態(tài)機(jī)從 pending 到 resolved 的完整流轉(zhuǎn)工具運(yùn)行時(shí)的內(nèi)部狀態(tài)管理我建議用一個(gè)顯式的狀態(tài)機(jī)來(lái)做。每個(gè)工具調(diào)用實(shí)例在任意時(shí)刻處于以下狀態(tài)之一pending已創(chuàng)建等待執(zhí)行validating參數(shù)校驗(yàn)中executing執(zhí)行中succeeded執(zhí)行成功failed執(zhí)行失敗可恢復(fù)aborted執(zhí)行中止不可恢復(fù)timeout執(zhí)行超時(shí)狀態(tài)流轉(zhuǎn)的規(guī)則是pending → validating → executing → succeeded/failed/timeout。failed 狀態(tài)可以重新進(jìn)入 pending重試aborted 是終態(tài)。為什么要用狀態(tài)機(jī)因?yàn)椤笆∈菙?shù)據(jù)”要求你能區(qū)分“這次失敗是暫時(shí)的還是永久的”。狀態(tài)機(jī)讓這個(gè)判斷變得明確——failed 可以重試aborted 不行。我在一個(gè)多工具協(xié)作的 Agent 項(xiàng)目里就是因?yàn)闆](méi)有狀態(tài)機(jī)導(dǎo)致一個(gè)已經(jīng)權(quán)限不足的工具被反復(fù)重試了七次白白燒了一堆 token。后來(lái)加了狀態(tài)機(jī)aborted 狀態(tài)直接阻斷重試路徑問(wèn)題解決。3. 失敗數(shù)據(jù)的結(jié)構(gòu)化設(shè)計(jì)與實(shí)操3.1 失敗返回體的標(biāo)準(zhǔn)結(jié)構(gòu)失敗返回體長(zhǎng)什么樣直接決定了模型能不能用好這個(gè)信息。我經(jīng)過(guò)多次迭代最終固定下來(lái)一個(gè)結(jié)構(gòu){ status: failed, error_type: timeout, error_code: TOOL_TIMEOUT_001, message: 查詢天氣服務(wù)在 5000ms 內(nèi)未響應(yīng), retryable: true, suggestion: 可以嘗試縮短查詢范圍或稍后重試, context: { tool_name: query_weather, attempt: 1, max_attempts: 3, elapsed_ms: 5000 } }這個(gè)結(jié)構(gòu)里每個(gè)字段都有明確用途status讓模型一眼知道這次調(diào)用沒(méi)成功error_type失敗的大類模型可以據(jù)此選擇策略error_code精確的錯(cuò)誤碼方便排查和日志分析message人類可讀的描述模型也會(huì)讀retryable明確告訴模型能不能重試避免瞎試suggestion給模型的建議這是提升 Agent 智能感的關(guān)鍵context執(zhí)行上下文幫助模型理解失敗發(fā)生的場(chǎng)景注意suggestion字段不要寫得太具體否則模型會(huì)機(jī)械照搬。寫方向性的建議讓模型自己決定具體怎么做。3.2 錯(cuò)誤碼體系的設(shè)計(jì)原則錯(cuò)誤碼不是隨便編的。我建議按“領(lǐng)域 類型 序號(hào)”三段式來(lái)設(shè)計(jì)領(lǐng)域TOOL工具層、PARAM參數(shù)層、AUTH權(quán)限層、NET網(wǎng)絡(luò)層類型TIMEOUT、INVALID、MISSING、DENIED、CONFLICT序號(hào)三位數(shù)字從 001 開始比如PARAM_INVALID_003表示參數(shù)層第三個(gè)無(wú)效參數(shù)錯(cuò)誤。這套體系的好處是模型可以通過(guò)錯(cuò)誤碼前綴快速判斷失敗性質(zhì)?？吹絇ARAM_開頭它知道要改參數(shù)看到NET_開頭它知道要等或換路看到AUTH_開頭它知道這條路走不通了。我在實(shí)際項(xiàng)目里維護(hù)了一張錯(cuò)誤碼對(duì)照表每次新增工具時(shí)同步更新。這張表后來(lái)成了排查線上問(wèn)題的第一手資料——用戶反饋 Agent 行為異常我先看錯(cuò)誤碼分布基本能定位到是哪類失敗導(dǎo)致的。3.3 把失敗信息喂回模型的三種方式失敗信息怎么喂回給模型有講究。我試過(guò)三種方式各有適用場(chǎng)景方式一直接追加到對(duì)話歷史。把失敗返回體作為一條tool角色的消息追加進(jìn)去。這是最標(biāo)準(zhǔn)的方式適用于大多數(shù)場(chǎng)景。模型在下一輪推理時(shí)能看到完整的失敗信息。方式二包裝成系統(tǒng)提示。把失敗信息包裝成一條system消息強(qiáng)調(diào)其重要性。適用于需要模型特別關(guān)注某類失敗的場(chǎng)景比如連續(xù)失敗三次后用系統(tǒng)提示告訴模型“該工具已連續(xù)失敗請(qǐng)考慮替代方案”。方式三摘要后注入。當(dāng)失敗信息很長(zhǎng)時(shí)先做摘要再注入。適用于失敗返回體包含大量堆棧信息的場(chǎng)景避免占用過(guò)多上下文窗口。我一般默認(rèn)用方式一只有在需要強(qiáng)調(diào)或信息過(guò)長(zhǎng)時(shí)才用方式二和方式三。方式二用多了會(huì)讓模型對(duì)系統(tǒng)提示脫敏反而降低效果。4. 重試策略與降級(jí)路徑的工程實(shí)現(xiàn)4.1 指數(shù)退避重試的正確打開方式重試不是簡(jiǎn)單地“再來(lái)一次”。我見(jiàn)過(guò)最粗暴的重試是for i in range(3): try: call() except: pass這種重試在 Agent 場(chǎng)景里是災(zāi)難——它不考慮失敗原因不考慮時(shí)間成本不考慮模型是否還在等。正確的重試策略應(yīng)該包含這些要素退避算法指數(shù)退避基礎(chǔ)延遲 500ms每次翻倍加隨機(jī)抖動(dòng)最大重試次數(shù)默認(rèn) 3 次可配置可重試錯(cuò)誤白名單只有特定錯(cuò)誤碼才重試總超時(shí)預(yù)算整個(gè)重試過(guò)程不能超過(guò)某個(gè)總時(shí)長(zhǎng)import time import random def retry_with_backoff(func, max_attempts3, base_delay0.5, max_total10.0): start time.time() for attempt in range(max_attempts): try: return func() except RetryableError as e: elapsed time.time() - start if elapsed max_total: raise if attempt max_attempts - 1: raise delay base_delay * (2 ** attempt) random.uniform(0, 0.1) time.sleep(delay) raise MaxRetriesExceeded()這段代碼的關(guān)鍵在于max_total參數(shù)。沒(méi)有總超時(shí)預(yù)算的重試在 Agent 場(chǎng)景里會(huì)讓模型等太久用戶體驗(yàn)極差。4.2 降級(jí)路徑當(dāng)重試也救不了的時(shí)候重試失敗之后怎么辦直接報(bào)錯(cuò)那“失敗是數(shù)據(jù)”就白做了。正確的做法是走降級(jí)路徑。降級(jí)路徑分三種工具級(jí)降級(jí)換一個(gè)功能相似的工具。比如查天氣的主工具掛了切到備用數(shù)據(jù)源。這需要你在工具注冊(cè)時(shí)就維護(hù)好“等價(jià)工具”的映射關(guān)系。參數(shù)級(jí)降級(jí)放寬參數(shù)限制。比如精確查詢失敗改成模糊查詢實(shí)時(shí)數(shù)據(jù)拿不到改用緩存數(shù)據(jù)。策略級(jí)降級(jí)改變整體策略。比如從“必須拿到數(shù)據(jù)才能回答”降級(jí)為“基于已有信息給出建議”。我在一個(gè)電商客服 Agent 里用過(guò)策略級(jí)降級(jí)。用戶問(wèn)“我的訂單到哪了”物流查詢工具掛了Agent 沒(méi)有直接說(shuō)“查不到”而是回復(fù)“物流系統(tǒng)暫時(shí)繁忙根據(jù)你的下單時(shí)間預(yù)計(jì)明天送達(dá)你可以稍后再查”。用戶滿意度反而比直接報(bào)錯(cuò)高。4.3 重試與降級(jí)的決策樹什么時(shí)候重試什么時(shí)候降級(jí)什么時(shí)候放棄我畫了一棵決策樹實(shí)際跑下來(lái)效果不錯(cuò)失敗發(fā)生 → 檢查retryable字段retryabletrue→ 檢查重試次數(shù)是否超限未超限 → 退避后重試已超限 → 檢查是否有降級(jí)路徑有降級(jí)路徑 → 執(zhí)行降級(jí)無(wú)降級(jí)路徑 → 返回最終失敗引導(dǎo)模型放棄該路徑這棵樹的關(guān)鍵在于第 4 步。降級(jí)路徑不是自動(dòng)執(zhí)行的而是作為“建議”喂回給模型讓模型決定是否走。因?yàn)榻导?jí)本身可能帶來(lái)副作用模型需要綜合判斷。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 模型陷入重試死循環(huán)怎么辦這是最常見(jiàn)的問(wèn)題。模型拿到失敗信息后反復(fù)重試同一個(gè)調(diào)用燒光 token 也沒(méi)解決問(wèn)題。排查思路先看失敗返回體里的retryable字段是不是一直是true。如果是說(shuō)明你的重試策略沒(méi)有正確標(biāo)記“不可重試”的失敗。再看suggestion字段如果建議太模糊模型會(huì)傾向于重試而不是換路。解決方法在運(yùn)行時(shí)層面加一個(gè)“同一工具連續(xù)失敗計(jì)數(shù)器”。連續(xù)失敗超過(guò)閾值我一般設(shè) 3 次強(qiáng)制把retryable置為false并在返回體里加一條action_required: switch_strategy明確告訴模型必須換路。5.2 失敗信息太長(zhǎng)導(dǎo)致上下文爆炸有些工具的失敗返回體包含完整堆棧動(dòng)輒幾千 token。喂回給模型后上下文窗口迅速被占滿。解決方法在歸一化階段做截?cái)嗪驼?。堆棧信息只保留最頂層的三行其余?.. (truncated)代替。同時(shí)把詳細(xì)堆棧寫到日志里需要時(shí)再查。我一般會(huì)設(shè)一個(gè)閾值失敗返回體超過(guò) 500 token 就觸發(fā)摘要。摘要用規(guī)則做不用模型做——模型做摘要太慢而且可能引入新的不確定性。5.3 參數(shù)校驗(yàn)失敗但模型不改參數(shù)模型拿到“參數(shù) age 應(yīng)為整數(shù)”的提示后下一輪還是傳字符串。這種情況通常是因?yàn)?Schema 的 description 寫得不夠清楚或者模型對(duì)參數(shù)格式的理解有偏差。解決方法在失敗返回體里直接給出正確格式的示例。比如message: 參數(shù) age 應(yīng)為整數(shù)正確示例25。模型看到具體示例修正概率大幅提升。5.4 工具執(zhí)行成功但結(jié)果為空這不是失敗但比失敗更麻煩。工具返回了空結(jié)果模型不知道是“真的沒(méi)有數(shù)據(jù)”還是“查詢出了問(wèn)題”。解決方法在結(jié)果歸一化階段對(duì)空結(jié)果做特殊標(biāo)記。返回{status: succeeded, data: null, empty_reason: no_match}讓模型知道這是正常的空結(jié)果不是異常。5.5 常見(jiàn)問(wèn)題速查表問(wèn)題現(xiàn)象可能原因排查方向解決手段模型反復(fù)重試同一工具retryable 標(biāo)記錯(cuò)誤檢查失敗返回體加連續(xù)失敗計(jì)數(shù)器上下文窗口被占滿失敗信息過(guò)長(zhǎng)檢查返回體大小截?cái)嗾Ｐ筒桓膮?shù)提示不具體檢查 message 字段加正確示例空結(jié)果被當(dāng)異常缺少空結(jié)果標(biāo)記檢查歸一化邏輯加 empty_reason重試耗時(shí)過(guò)長(zhǎng)缺少總超時(shí)預(yù)算檢查重試配置加 max_total降級(jí)路徑不生效降級(jí)建議太模糊檢查 suggestion寫方向性建議6. 從失敗數(shù)據(jù)到 Agent 能力提升6.1 失敗日志的二次利用失敗數(shù)據(jù)不只是喂給模型的也是喂給你自己的。我習(xí)慣把每次工具失敗都記一條結(jié)構(gòu)化日志包含工具名、錯(cuò)誤碼、參數(shù)、耗時(shí)、重試次數(shù)。攢一段時(shí)間后這些日志能告訴你很多事哪個(gè)工具最不穩(wěn)定需要優(yōu)化哪類參數(shù)最容易出錯(cuò)Schema 需要調(diào)整哪個(gè)時(shí)間段失敗率最高可能是外部服務(wù)的問(wèn)題我在一個(gè)項(xiàng)目里通過(guò)日志發(fā)現(xiàn)某個(gè)查詢工具在每天上午 9 點(diǎn)到 10 點(diǎn)失敗率飆升排查后發(fā)現(xiàn)是外部服務(wù)在這個(gè)時(shí)間段做批量任務(wù)導(dǎo)致響應(yīng)變慢。后來(lái)我把這個(gè)時(shí)間段的調(diào)用改成了異步問(wèn)題解決。6.2 用失敗數(shù)據(jù)訓(xùn)練模型的工具使用能力如果你在做模型微調(diào)失敗數(shù)據(jù)是極好的訓(xùn)練素材。把“失敗返回體 模型的正確修正”作為一對(duì)訓(xùn)練樣本能讓模型學(xué)會(huì)更好地處理工具失敗。我試過(guò)用這種方式微調(diào)一個(gè)小模型專門處理工具調(diào)用場(chǎng)景。微調(diào)后模型在遇到參數(shù)錯(cuò)誤時(shí)主動(dòng)修正的概率從 40% 提升到了 75%。這個(gè)提升在 Agent 場(chǎng)景里非?？捎^因?yàn)閰?shù)錯(cuò)誤是最常見(jiàn)的失敗類型。6.3 失敗數(shù)據(jù)的監(jiān)控與告警生產(chǎn)環(huán)境的 Agent必須有失敗監(jiān)控。我一般設(shè)三個(gè)告警閾值單工具失敗率超過(guò) 10%告警單次對(duì)話內(nèi)失敗次數(shù)超過(guò) 5 次告警不可恢復(fù)失敗aborted出現(xiàn)立即告警告警不是目的快速定位和修復(fù)才是。所以告警信息里要帶足夠的上下文——工具名、錯(cuò)誤碼、最近幾次的失敗詳情。7. 一個(gè)完整的工具運(yùn)行時(shí)實(shí)現(xiàn)示例7.1 核心代碼結(jié)構(gòu)把前面講的東西串起來(lái)一個(gè)最小可用的工具運(yùn)行時(shí)大概長(zhǎng)這樣class ToolRuntime: def __init__(self, tools, max_retries3, total_timeout10.0): self.tools tools self.max_retries max_retries self.total_timeout total_timeout self.failure_counter {} def execute(self, tool_name, params): tool self.tools.get(tool_name) if not tool: return self._build_failure(TOOL_MISSING_001, 工具不存在, False) validation self._validate(tool.schema, params) if not validation[valid]: return self._build_failure( PARAM_INVALID_001, validation[message], True, suggestion請(qǐng)根據(jù)提示修正參數(shù)后重試 ) start time.time() for attempt in range(self.max_retries): try: result tool.call(params) self.failure_counter[tool_name] 0 return self._build_success(result) except RetryableError as e: if time.time() - start self.total_timeout: return self._build_failure(TOOL_TIMEOUT_001, str(e), False) self._record_failure(tool_name) if self.failure_counter.get(tool_name, 0) 3: return self._build_failure( TOOL_LOOP_001, 該工具連續(xù)失敗建議切換策略, False, suggestion請(qǐng)考慮使用其他工具或改變查詢方式 ) time.sleep(0.5 * (2 ** attempt)) except FatalError as e: return self._build_failure(TOOL_ABORT_001, str(e), False) return self._build_failure(TOOL_MAXRETRY_001, 重試次數(shù)超限, False)7.2 關(guān)鍵設(shè)計(jì)點(diǎn)說(shuō)明這段代碼里有幾個(gè)設(shè)計(jì)點(diǎn)值得展開失敗計(jì)數(shù)器是全局的不是單次調(diào)用的。這樣能跨調(diào)用追蹤同一工具的連續(xù)失敗情況避免模型在多次調(diào)用之間“鉆空子”。總超時(shí)預(yù)算是硬約束。不管重試多少次總耗時(shí)不能超過(guò)total_timeout。這是保護(hù)用戶體驗(yàn)的底線。失敗返回體統(tǒng)一由_build_failure構(gòu)造。保證所有失敗返回體的結(jié)構(gòu)一致模型不需要處理多種格式。成功返回體也走歸一化。_build_success把原始結(jié)果包裝成標(biāo)準(zhǔn)結(jié)構(gòu)和失敗返回體保持對(duì)稱。7.3 和 Agent 主循環(huán)的對(duì)接工具運(yùn)行時(shí)不是孤立的它要和 Agent 的主循環(huán)對(duì)接。對(duì)接方式很簡(jiǎn)單主循環(huán)拿到模型輸出的工具調(diào)用請(qǐng)求交給運(yùn)行時(shí)執(zhí)行運(yùn)行時(shí)返回結(jié)構(gòu)化結(jié)果主循環(huán)把結(jié)果追加到對(duì)話歷史觸發(fā)下一輪推理。def agent_loop(messages, tools, model): while True: response model.chat(messages, toolstools) if response.tool_calls: for call in response.tool_calls: result runtime.execute(call.name, call.params) messages.append({ role: tool, tool_call_id: call.id, content: json.dumps(result) }) else: return response.content這個(gè)循環(huán)里result不管是成功還是失敗都會(huì)被追加到messages里。這就是“失敗是數(shù)據(jù)”在代碼層面的體現(xiàn)——失敗和成功走的是同一條路沒(méi)有特殊分支。8. 幾個(gè)容易踩的坑和我的應(yīng)對(duì)8.1 不要把異常直接序列化Python 的異常對(duì)象不能直接 JSON 序列化。我見(jiàn)過(guò)有人寫json.dumps({error: str(e)})結(jié)果str(e)里包含換行和特殊字符模型讀起來(lái)很費(fèi)勁。正確做法是提取異常的關(guān)鍵信息重新組織成結(jié)構(gòu)化數(shù)據(jù)。異常類型、異常消息、發(fā)生位置這三樣就夠了其余的都寫日志。8.2 不要忽略“部分成功”有些工具調(diào)用會(huì)返回部分成功的結(jié)果。比如批量查詢十個(gè)城市八個(gè)成功兩個(gè)失敗。這種情況不要簡(jiǎn)單標(biāo)記為失敗而是返回一個(gè)包含成功和失敗明細(xì)的結(jié)構(gòu)讓模型自己決定怎么處理。我一般用{status: partial, succeeded: [...], failed: [...]}這種結(jié)構(gòu)。模型看到 partial會(huì)知道不是全盤失敗可以基于成功部分繼續(xù)推理。8.3 不要讓重試阻塞主循環(huán)同步重試會(huì)阻塞 Agent 的主循環(huán)導(dǎo)致模型等待。如果重試耗時(shí)較長(zhǎng)考慮改成異步重試——先把失敗返回給模型讓模型繼續(xù)做其他事重試結(jié)果出來(lái)后再注入。這個(gè)改動(dòng)比較大適合對(duì)響應(yīng)速度要求高的場(chǎng)景。一般場(chǎng)景下同步重試加總超時(shí)預(yù)算就夠了。8.4 不要忘記清理失敗計(jì)數(shù)器失敗計(jì)數(shù)器是全局的如果不清理一個(gè)工具偶爾失敗一次計(jì)數(shù)器累加最終觸發(fā)“連續(xù)失敗”誤判。我的做法是成功一次就清零同時(shí)設(shè)一個(gè)時(shí)間窗口超過(guò)窗口的失敗記錄自動(dòng)過(guò)期。這個(gè)細(xì)節(jié)很小但不注意會(huì)帶來(lái)很詭異的 bug——明明工具已經(jīng)恢復(fù)正常了Agent 卻還在說(shuō)“該工具連續(xù)失敗”。9. 工具運(yùn)行時(shí)的測(cè)試策略9.1 失敗路徑必須單獨(dú)測(cè)大部分人的測(cè)試只覆蓋成功路徑失敗路徑靠“線上碰”。這在 Agent 場(chǎng)景里很危險(xiǎn)因?yàn)槭√幚磉壿嫳瘸晒μ幚韽?fù)雜得多。我的做法是給每個(gè)工具寫三組測(cè)試全成功、部分失敗、全失敗。全失敗那組要覆蓋各種錯(cuò)誤類型——超時(shí)、參數(shù)錯(cuò)誤、權(quán)限不足、資源不存在。9.2 用 mock 模擬各種失敗真實(shí)的外部服務(wù)很難穩(wěn)定復(fù)現(xiàn)特定失敗。所以測(cè)試時(shí)用 mock人為制造各種失敗場(chǎng)景。def test_timeout_returns_retryable(): mock_tool MockTool(side_effectTimeoutError()) runtime ToolRuntime({mock: mock_tool}) result runtime.execute(mock, {}) assert result[status] failed assert result[error_type] timeout assert result[retryable] is True這種測(cè)試跑起來(lái)快覆蓋全是保證失敗處理邏輯正確的關(guān)鍵。9.3 端到端測(cè)試要包含失敗注入單元測(cè)試之外還要做端到端測(cè)試。端到端測(cè)試?yán)镆鲃?dòng)注入失敗——比如讓某個(gè)工具在第三次調(diào)用時(shí)必定失敗看 Agent 能不能正確降級(jí)。我一般用環(huán)境變量控制失敗注入測(cè)試環(huán)境開啟生產(chǎn)環(huán)境關(guān)閉。這樣同一套代碼既能測(cè)失敗路徑又不影響生產(chǎn)。10. 我對(duì)“失敗是數(shù)據(jù)”的幾點(diǎn)個(gè)人體會(huì)做 Agent 開發(fā)這兩年我越來(lái)越覺(jué)得“失敗是數(shù)據(jù)”不只是一個(gè)技術(shù)方案更是一種設(shè)計(jì)思維。它要求你在設(shè)計(jì)工具的時(shí)候就把失敗當(dāng)成一等公民來(lái)對(duì)待而不是事后補(bǔ)一個(gè) try-catch。我早期做 Agent 的時(shí)候工具定義寫得很隨意失敗處理基本靠“報(bào)錯(cuò)就重試”。結(jié)果就是 Agent 看起來(lái)很笨——遇到一點(diǎn)挫折就放棄或者陷入無(wú)意義的重復(fù)。后來(lái)把失敗數(shù)據(jù)結(jié)構(gòu)化、把重試策略精細(xì)化、把降級(jí)路徑顯式化Agent 的“韌性”明顯上來(lái)了。有一個(gè)細(xì)節(jié)我印象很深。之前有個(gè)用戶問(wèn)“幫我找一下附近評(píng)分最高的川菜館”地圖工具返回了空結(jié)果。舊版本 Agent 直接說(shuō)“沒(méi)找到”。新版本里空結(jié)果被標(biāo)記為empty_reason: no_match模型看到這個(gè)標(biāo)記后主動(dòng)改問(wèn)“要不要擴(kuò)大搜索范圍到整個(gè)城市”用戶說(shuō)好第二次查詢就成功了。這個(gè)體驗(yàn)的提升就來(lái)自于把“空結(jié)果”也當(dāng)成一種數(shù)據(jù)來(lái)處理。還有一點(diǎn)體會(huì)是失敗數(shù)據(jù)的價(jià)值會(huì)隨時(shí)間累積。剛開始你可能只是為了解決當(dāng)下的失敗但攢了幾個(gè)月日志后你會(huì)發(fā)現(xiàn)這些數(shù)據(jù)能告訴你很多關(guān)于工具設(shè)計(jì)、模型行為、用戶需求的信息。我現(xiàn)在每次優(yōu)化 Agent第一件事就是翻最近的失敗日志比看成功日志有用得多。最后分享一個(gè)小技巧如果你不確定某個(gè)失敗該不該喂回給模型就問(wèn)自己一個(gè)問(wèn)題——“如果我是模型看到這條信息能不能做出比‘重試’更好的決策”能就喂不能就吞掉返回一個(gè)更通用的提示。這個(gè)判斷標(biāo)準(zhǔn)我用了很久基本沒(méi)出過(guò)錯(cuò)。