把能跑的 Agent Demo 變成能長期承受生產(chǎn)壓力的 Agent真正的難點不是模型推理而是邊界控制、失敗兜底、可觀測性和權(quán)限設(shè)計。很多 Agent 項目在本地示例里表現(xiàn)很好一接到真實業(yè)務(wù)就出現(xiàn)“執(zhí)行器不響應(yīng)”“工具調(diào)用結(jié)果沒有被模型采用”“批量任務(wù)跑完后輸出對不上”等問題。這類問題大多不是大模型能力不行而是工程結(jié)構(gòu)一開始就沒有按生產(chǎn)要求去設(shè)計。下面不打算復(fù)述理論而是圍繞生產(chǎn)環(huán)境里最容易踩坑的五個環(huán)節(jié)整理成五條規(guī)則并補充實際排查順序。無論你是直接用代碼編排還是引入 Agent 開發(fā)框架甚至只是給現(xiàn)有業(yè)務(wù)加上一個智能助手這套判斷方式基本都能用上。1. 規(guī)則一一個 Agent 只負責(zé)一條清晰業(yè)務(wù)鏈路很多人把 Agent 等同于“能聊天、能搜索、能調(diào)用工具、能操作很多系統(tǒng)”的通用助手。這種想法在做 Demo 的時候沒問題放到生產(chǎn)環(huán)境就會立刻失控。生產(chǎn)級 Agent 的第一個要求不是能力多而是邊界清楚。1.1 不要一開始就構(gòu)建“全能助手”單實例 Agent 承擔(dān)的職責(zé)越多出問題的概率就越大。每一個新增技能都會往系統(tǒng)提示詞里加描述往工具列表里加接口往上下文里加示例。當(dāng)這些內(nèi)容互相干擾時模型容易在“該調(diào)用哪個工具”“該輸出什么格式”“該不該繼續(xù)追問”之間搖擺。更穩(wěn)妥的做法是把業(yè)務(wù)拆成單一職責(zé)的 Agent。比如訂單售后助手只處理退換貨、物流查詢和異常登記。工單分類助手只負責(zé)把用戶描述映射到預(yù)定義工單類型。代碼檢查助手只讀取代碼倉庫并返回檢查建議不做其他操作。判斷邊界是否合理有一個很實用的標(biāo)準(zhǔn)如果新增一個工具時你需要反復(fù)修改系統(tǒng)提示詞說明職責(zé)已經(jīng)過寬。正常情況應(yīng)該是加一個工具即可提示詞不需要大改。如果不同業(yè)務(wù)之間工具高度重疊就先用一個上層路由 Agent 做分發(fā)再交給各自的執(zhí)行 Agent而不是把全部工具塞進同一個 Agent。1.2 輸入、輸出、失敗標(biāo)準(zhǔn)必須在第一行規(guī)則里寫死開始寫代碼之前先定義清楚三類問題。第一輸入范圍。用戶請求經(jīng)過前置處理之后哪些字段允許進入 Agent哪些字段必填哪些字段要過濾如果不做輸入限制用戶發(fā)一段超長文本、一個惡意指令或者一串不完整 JSONAgent 會在第一步就開始混亂。第二輸出格式。不要允許 Agent 輸出任意自然語言作為最終結(jié)果。生產(chǎn)環(huán)境里最終結(jié)果應(yīng)當(dāng)是結(jié)構(gòu)化數(shù)據(jù)例如 JSON、狀態(tài)碼、消息類型加業(yè)務(wù)字段。模型輸出自然語言可以但下游系統(tǒng)接收前必須完成解析和校驗。第三失敗標(biāo)準(zhǔn)。到底什么算成功不是模型回復(fù)“好的”就算成功而是業(yè)務(wù)系統(tǒng)里的狀態(tài)發(fā)生了變化。比如售后工單確實被創(chuàng)建或者訂單狀態(tài)確實被更新。什么算失敗超時未響應(yīng)、重試后仍然失敗、輸出結(jié)構(gòu)校驗不通過、需要人工介入都要在規(guī)則里寫清楚。這樣后續(xù)所有日志、告警和排查才有依據(jù)。注意很多項目出了問題說不清是模型原因還是鏈路原因就是因為一開始沒有把“成功”定義清楚。先寫死輸入、輸出和失敗標(biāo)準(zhǔn)再談 Agent 能力優(yōu)化。2. 規(guī)則二先跑通最小閉環(huán)再疊加記憶、知識庫和工具編排Agent 項目的技術(shù)棧選擇很容易讓人上頭。MCP、Agent Skill、向量知識庫、長期記憶、多 Agent 編排每個名詞聽起來都值得研究。但生產(chǎn)落地不是搭積木功能疊加得越快定位問題就越難。2.1 最小閉環(huán)至少要包含“接收輸入、調(diào)用一次工具、返回結(jié)果”很多項目上來就做“多輪對話 長期記憶 多個工具編排”結(jié)果第一輪對話就卡在工具調(diào)用上。問題不是模型看不懂工具描述而是整個鏈路里沒有單獨驗證過某一環(huán)。我更建議把第一次測試拆成三層接收一條用戶輸入交給模型。模型輸出一次工具調(diào)用參數(shù)代碼解析并真實調(diào)用接口。工具返回結(jié)果模型生成最終回復(fù)代碼校驗后輸出。這三步跑通說明基礎(chǔ)鏈路是通的。如果這期間出現(xiàn)超時、參數(shù)解析失敗、結(jié)果截斷、響應(yīng)格式不對問題都出在最底層而不是記憶或編排層。先解決底層再往上分層加。2.2 記憶和知識庫不是越早上越好Agent 一旦引入記憶模塊就要回答幾個問題記憶存多久一個會話內(nèi)還是一周、一個月、永久誰可以讀只有當(dāng)前用戶還是所有用戶都共享能不能刪除用戶要求刪除歷史數(shù)據(jù)時系統(tǒng)能不能真正清掉記憶會不會占滿上下文每次攜帶所有歷史會讓模型響應(yīng)變慢、成本升高而且未必提升效果。判斷是否需要長期記憶標(biāo)準(zhǔn)很直接同一個用戶下一輪提問是否必須依賴上一輪結(jié)論。比如售后助手查詢工單用戶問完“工單狀態(tài)”又問“如何處理”確實需要上下文銜接這時做會話級記憶就夠。如果一個任務(wù)每次請求信息完整不依賴歷史就沒必要引入長期記憶。知識庫也是同樣邏輯。先確認業(yè)務(wù)是否需要專業(yè)資料檢索。如果只是普通規(guī)則寫進提示詞或工具參數(shù)里就夠了。真正需要知識庫的場景通常是資料量大、內(nèi)容更新頻繁、用戶提問是開放式的這時才值得引入向量檢索。2.3 Agent Skill 和 MCP 先區(qū)分定位再選型MCP 全稱是 Model Context Protocol屬于工具接入層面的協(xié)議它解決的是“模型如何更規(guī)范地調(diào)用外部工具”。Agent Skill 則更像一組可復(fù)用的提示詞、工具調(diào)用步驟和業(yè)務(wù)操作封裝解決的是“某個復(fù)雜任務(wù)怎么做”。兩者不是誰替代誰的關(guān)系。如果只是接幾個內(nèi)部 API用 MCP 風(fēng)格的工具描述就能搞定讓模型按約定參數(shù)調(diào)用接口。如果要沉淀一套多步驟能力比如“審計日志分析”“多標(biāo)簽工單流轉(zhuǎn)”再把它封裝成 Skill后續(xù)其他 Agent 可以直接復(fù)用。選型時不要先問“哪個更主流”而是先列出業(yè)務(wù)動作需要調(diào)用哪些接口、有哪些判斷步驟、哪些環(huán)節(jié)允許模型自由發(fā)揮、哪些環(huán)節(jié)必須走固定流程。流程固定度越高越適合編排流程開放度越高越需要模型能力。3. 規(guī)則三工具調(diào)用必須可觀測、可重試、可回滾工具調(diào)用是 Agent 生產(chǎn)運行中最容易出問題的部分。模型擅長生成文本但調(diào)用外部系統(tǒng)時網(wǎng)絡(luò)超時、參數(shù)非法、權(quán)限不足、接口返回異常這些情況幾乎每天都會遇到。不能把這些都扔給用戶也不能讓模型自行處理一切。3.1 每次工具調(diào)用都要留結(jié)構(gòu)化日志日志不要只記錄“成功”或“失敗”要記錄完整的調(diào)用上下文。我建議至少包含這些字段request_id一次用戶請求的唯一標(biāo)識。agent_step當(dāng)前屬于哪個執(zhí)行步驟。tool_name調(diào)用的工具名稱。arguments傳給工具的參數(shù)摘要。status成功、失敗、超時、重試中。error_type錯誤分類。latency_ms調(diào)用耗時。retry_count重試次數(shù)。示例{ request_id: req_20250321_001, agent_step: tool_call, tool_name: query_order, arguments: { order_id: A1001 }, status: failed, error_type: timeout, latency_ms: 30500, retry_count: 2 }有了這樣的日志定位問題時會快很多。沒有日志的情況下排查 Agent基本等于靠猜。3.2 重試順序區(qū)分瞬時錯誤和業(yè)務(wù)錯誤工具調(diào)用失敗時不要一律重試。先判斷錯誤類型。瞬時錯誤包括網(wǎng)絡(luò)超時、連接被重置、服務(wù)暫時不可用。這類錯誤可以重試但一般建議限制次數(shù)比如最多重試 3 次重試之間加遞增間隔。不要無限重試否則上游服務(wù)恢復(fù)時會突然積壓大量請求造成二次雪崩。業(yè)務(wù)錯誤包括參數(shù)非法、權(quán)限不足、業(yè)務(wù)規(guī)則不允許操作。這類錯誤重試沒有意義正確做法是返回失敗信息讓 Agent 基于失敗結(jié)果換一種方式或者直接升級到人工處理。判斷標(biāo)準(zhǔn)很簡單如果同樣的參數(shù)調(diào)用 100 次都會失敗那就是業(yè)務(wù)錯誤如果第一次失敗、第二次可能成功那就是瞬時錯誤。把兩種錯誤分開處理整個鏈路會穩(wěn)定很多。3.3 工具返回內(nèi)容過大時先截斷或摘要再交給模型大模型上下文窗口有限工具返回結(jié)果不是越多越好。比如查詢一個訂單詳情可能返回幾百行關(guān)聯(lián)記錄查日志可能返回幾十 KB 文本。如果全部塞給模型容易出現(xiàn)兩個問題一是超出上下文長度導(dǎo)致截斷二是無關(guān)內(nèi)容干擾模型判斷。正確的做法是在工具層做處理。比如查詢列表只返回前 20 條和總條數(shù)。日志內(nèi)容先做關(guān)鍵詞提取或摘要。數(shù)據(jù)庫查詢只返回需要的字段不 SELECT *。這步處理不能交給模型自己決定因為模型無法預(yù)知完整數(shù)據(jù)量。生產(chǎn)環(huán)境里返回內(nèi)容的裁剪、摘要、分頁都應(yīng)該在工具接口內(nèi)部完成。4. 規(guī)則四并發(fā)、隊列和長任務(wù)資源要提前設(shè)計Agent 任務(wù)通常不是一次 HTTP 請求就結(jié)束而是多步推理加多次工具調(diào)用耗時和資源消耗都高于普通接口。如果按照傳統(tǒng) Web 服務(wù)的思維去設(shè)計上線后很容易在并發(fā)上出問題。4.1 并發(fā)數(shù)不是越高越好假設(shè)一次完整 Agent 調(diào)用需要 3 次模型推理和 4 次工具調(diào)用。這個過程中CPU、內(nèi)存、模型服務(wù)、外部 API 都在持續(xù)工作。如果同時開 50 個并發(fā)模型服務(wù)的排隊時間會明顯增加外部接口也可能被限流。建議從很小的并發(fā)開始測試。比如同時 2 到 5 個任務(wù)觀察成功率、平均延遲、P95 延遲和資源占用。確認穩(wěn)定之后再逐步上調(diào)。如果失敗率上升不要急著加服務(wù)器先看是不是并發(fā)數(shù)把上游 API 打滿了或者模型服務(wù)排隊嚴(yán)重。判斷并發(fā)是否合理不要只看“跑沒跑完”要看平均單任務(wù)耗時。任務(wù)在隊列中的等待時間。模型服務(wù)的排隊長度。外部 API 的錯誤率。數(shù)據(jù)庫連接和磁盤讀寫。這些指標(biāo)適合在生產(chǎn)前做一輪壓測不需要太精細但至少能確認系統(tǒng)在峰值流量下不會崩。4.2 長任務(wù)用隊列不用同步阻塞接口Agent 任務(wù)可能耗時幾秒到幾分鐘。如果客戶端一直同步等待體驗會很差也容易觸發(fā)網(wǎng)關(guān)超時。生產(chǎn)環(huán)境里建議把任務(wù)改成異步模式客戶端提交請求服務(wù)立即返回 task_id。Agent 任務(wù)進入隊列后臺消費者執(zhí)行?？蛻舳送ㄟ^輪詢或 Webhook 獲取結(jié)果。這個設(shè)計不需要一開始就引入重型消息中間件。如果團隊已經(jīng)有 RabbitMQ、Redis、Kafka 可以復(fù)用沒有的話用數(shù)據(jù)庫表存任務(wù)狀態(tài)也可以。核心是“任務(wù)狀態(tài)可查詢”。4.3 任務(wù)狀態(tài)至少要區(qū)分“排隊、執(zhí)行中、成功、失敗、需人工”每個任務(wù)狀態(tài)都要有最后更新時間。當(dāng)任務(wù)卡住時運維人員能夠立刻看到問題。排隊任務(wù)已進入隊列等待消費。執(zhí)行中消費者正在處理。成功處理完成結(jié)果可查詢。失敗重試后仍然失敗。需人工業(yè)務(wù)無法自動處理需要人工介入。執(zhí)行中狀態(tài)超過一定時間沒有變化可以視為異常。超時閾值由業(yè)務(wù)自己定比如普通售后任務(wù) 10 分鐘復(fù)雜分析任務(wù) 30 分鐘。一旦超過閾值就觸發(fā)告警并允許運維手動重試或終止。注意任務(wù)狀態(tài)要支持冪等更新。同一任務(wù)被重復(fù)消費時不能重復(fù)創(chuàng)建工單、重復(fù)扣款或重復(fù)寫入數(shù)據(jù)。每次調(diào)度都帶上 task_id 做去重判斷。5. 規(guī)則五安全、權(quán)限和輸出校驗不能放到上線后補Agent 的能力越強安全隱患越明顯。它能調(diào)用工具意味著它能發(fā)起真實操作。如果權(quán)限沒有控制好一條惡意指令就可能造成越權(quán)操作。這個不能等上線后再補救。5.1 Agent 的權(quán)限要按最小范圍授予不要讓 Agent 使用管理員賬號調(diào)用所有接口。生產(chǎn)環(huán)境里應(yīng)該單獨創(chuàng)建服務(wù)賬號只給它開通完成業(yè)務(wù)所必需的權(quán)限。比如查詢訂單狀態(tài)的工具只需要只讀權(quán)限。創(chuàng)建工單的工具只允許寫入工單系統(tǒng)不允許修改其他業(yè)務(wù)數(shù)據(jù)。文件讀取工具只允許讀取指定目錄不允許遍歷磁盤。判斷權(quán)限是否合理的標(biāo)準(zhǔn)如果刪掉 Agent 的賬號核心業(yè)務(wù)還能正常運行說明權(quán)限設(shè)計是合適的。反過來如果 Agent 賬號擁有太多權(quán)限一旦提示詞被注入或者模型被誘導(dǎo)風(fēng)險面會非常大。5.2 模型輸出必須過一道校驗層模型輸出的自然語言不能直接當(dāng)做業(yè)務(wù)結(jié)果使用。尤其當(dāng)結(jié)果要寫入數(shù)據(jù)庫、調(diào)用下游 API 或展示給用戶時必須經(jīng)過校驗。校驗至少包括結(jié)構(gòu)校驗輸出是否包含必需的字段JSON 是否能解析。類型校驗字段值是否在預(yù)期范圍內(nèi)。長度校驗輸出是否過長是否需要截斷。內(nèi)容校驗是否包含不合規(guī)內(nèi)容是否包含敏感信息。業(yè)務(wù)校驗比如金額字段是否大于零訂單號是否存在。如果模型輸出沒有通過校驗需要提前決定是重試、降級還是轉(zhuǎn)人工。不能一直卡在同一處循環(huán)重試。5.3 日志、審計和隱私脫敏一起設(shè)計Agent 在處理任務(wù)時接觸的數(shù)據(jù)可能包含用戶隱私。日志里不要記錄完整手機號、身份證號、密碼、Token 等敏感信息應(yīng)當(dāng)脫敏后再落盤。審計方面要能回答這些問題什么時間發(fā)起了什么請求請求來自哪個用戶或哪個系統(tǒng)Agent 調(diào)用了哪些工具最終執(zhí)行了什么操作結(jié)果是什么這些日志不是為了事后追責(zé)而是生產(chǎn)事故回溯和問題定位的基礎(chǔ)。沒有審計鏈路Agent 一旦出錯你很難知道它在哪個環(huán)節(jié)偏離了預(yù)期。6. 生產(chǎn)環(huán)境最常見的失敗模式與排查順序前面五條規(guī)則能覆蓋大部分生產(chǎn) Agent 的工程結(jié)構(gòu)。但實際運行中總會出現(xiàn)一些看起來很怪的問題。下面列出三種最常見的失敗模式并給出排查重點。6.1 現(xiàn)象一Agent 長時間不響應(yīng)常見原因有三個長任務(wù)使用同步接口客戶端等待超時。外部 API 沒有設(shè)置客戶端超時時間導(dǎo)致請求掛死。模型服務(wù)排隊請求進入隊列后長時間沒有結(jié)果。排查時先看任務(wù)狀態(tài)和最后更新時間。如果狀態(tài)一直在“執(zhí)行中”說明任務(wù)卡在某個環(huán)節(jié)。再看日志里最后一次工具調(diào)用的耗時和環(huán)境信息。如果工具調(diào)用遲遲沒有返回優(yōu)先檢查外部 API 的超時設(shè)置和限流狀態(tài)。不要一上來就重啟服務(wù)。重啟只是掩蓋問題下次還會出現(xiàn)。6.2 現(xiàn)象二工具返回正常但模型沒有執(zhí)行后續(xù)動作工具調(diào)用成功日志顯示工具結(jié)果正常但模型沒有繼續(xù)生成后續(xù)步驟而是直接輸出了一段文本或者停在那里。排查順序先看模型的原始輸出確認它到底有沒有生成工具調(diào)用參數(shù)。如果模型輸出了普通文本說明它對當(dāng)前狀態(tài)的理解出現(xiàn)了偏離可能是提示詞沒有交代清楚“拿到結(jié)果后必須繼續(xù)”。如果工具返回結(jié)果太長可能被截斷模型沒有拿到核心信息需要在工具層做摘要。如果上下文太長模型可能忽略了早期指令需要壓縮歷史消息或重新組織提示詞。這類問題不是簡單的“模型變笨了”而是上下文結(jié)構(gòu)和工具返回內(nèi)容的組織方式需要調(diào)整。6.3 現(xiàn)象三批量任務(wù)跑完后結(jié)果對不上批量任務(wù)最常見的坑是并發(fā)場景下的共享狀態(tài)沖突。比如兩個任務(wù)同時寫同一個文件后寫的覆蓋先寫的或者兩個任務(wù)共用同一個內(nèi)存變量互相污染又或者任務(wù)重復(fù)執(zhí)行數(shù)據(jù)庫里生成了多條重復(fù)記錄。解決思路每個任務(wù)使用唯一 task_id。中間結(jié)果和輸出文件按 task_id 命名。寫入數(shù)據(jù)庫時使用事務(wù)或唯一約束。任務(wù)調(diào)度時先查重判斷任務(wù)是否已經(jīng)處理過。批量任務(wù)的成功率不能只看“最終有沒有輸出”要檢查輸出是否完整、是否一一對應(yīng)、有沒有重復(fù)和遺漏。6.4 排查順序與檢查清單排查層次優(yōu)先檢查項常見誤區(qū)現(xiàn)象報錯信息、超時時間、任務(wù)狀態(tài)直接重啟服務(wù)掩蓋真實問題輸入?yún)?shù)格式、文件編碼、路徑、輸入字段是否完整只改參數(shù)不檢查輸入樣本環(huán)境依賴版本、權(quán)限、資源占用、端口沖突把環(huán)境問題當(dāng)成模型問題參數(shù)并發(fā)數(shù)、重試次數(shù)、模型溫度、上下文長度把參數(shù)拉滿反而更不穩(wěn)定工具本身工具版本、接口變更、已知限制忽略版本變更日志和兼容性排查時按這個順序走能避免很多無效操作。先看現(xiàn)象再確認輸入再檢查環(huán)境然后調(diào)參數(shù)最后才去質(zhì)疑工具本身。很多看起來像 Agent 能力問題的情況最后定位出來都是環(huán)境變量配錯、路徑不對或者依賴版本不一致。生產(chǎn)級 Agent 和 Demo 最大的區(qū)別不在于模型有多強而在于每一層設(shè)計是否留了后路。邊界、日志、重試、隊列、權(quán)限、校驗這些都是聽起來枯燥但真正決定能不能長期運行的環(huán)節(jié)。我個人建議按順序來做先定業(yè)務(wù)邊界和成功標(biāo)準(zhǔn)再跑最小閉環(huán)然后補日志和重試接著設(shè)計隊列和并發(fā)最后把權(quán)限和校驗加上。如果一上來就追求全自動、多工具、強記憶最后往往會在最普通的地方卡住。