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