1. 為什么“七要素”和“七個決策點”才是 Agent 工程的骨架很多人第一次接觸 AI Agent腦子里蹦出來的畫面是科幻電影里那種能自己思考、自己行動的智能體。但真到了動手寫代碼的階段你會發(fā)現(xiàn)事情完全不是那么回事。你寫了一個循環(huán)讓大模型反復(fù)調(diào)用工具結(jié)果它要么陷入死循環(huán)要么在第三步就忘了第一步的目標要么調(diào)用了一個根本不存在的函數(shù)還理直氣壯地編造結(jié)果。這些問題不是模型不夠聰明而是工程實現(xiàn)上缺了骨架。我做了幾個 Agent 項目之后踩了一圈坑回過頭來發(fā)現(xiàn)一個規(guī)律所有能穩(wěn)定跑起來的 Agent底層都逃不開七個核心要素和七個關(guān)鍵決策點。七要素是“一個 Agent 由哪些零件組成”七個決策點是“這些零件在運行時怎么做選擇”。前者是靜態(tài)結(jié)構(gòu)后者是動態(tài)邏輯。把這兩件事想清楚了不管你用 LangChain、CrewAI、Dify 還是自己從零手寫都不會迷路。這篇文章適合誰看如果你已經(jīng)用過大模型 API知道什么是 prompt、什么是 function calling但一提到“搭一個 Agent”就覺得無從下手那這篇就是寫給你的。如果你已經(jīng)在做 Agent 開發(fā)但系統(tǒng)總是不穩(wěn)定、行為不可預(yù)測那這篇也能幫你找到結(jié)構(gòu)性的原因。我會盡量用大白話把每個要素和決策點講透配上可以直接參考的實現(xiàn)思路和參數(shù)選擇邏輯讓你看完就能動手改自己的項目。核心關(guān)鍵詞先擺出來AI Agent、LLM、工具調(diào)用、循環(huán)機制、Agent 架構(gòu)。這幾個詞貫穿全文后面每個章節(jié)都會圍繞它們展開。2. 七要素拆解一個 Agent 到底由什么組成2.1 要素一LLM 作為推理內(nèi)核但不是全部很多人把 Agent 等同于“大模型加個循環(huán)”這個理解只對了三分之一。LLM 在 Agent 里的角色是推理內(nèi)核負責理解目標、拆解任務(wù)、決定下一步動作。但它不是 Agent 的全部甚至不是最脆弱的部分。選 LLM 做 Agent 內(nèi)核時有幾個參數(shù)必須關(guān)注。第一是上下文窗口因為它決定了 Agent 能“記住”多少歷史信息。一個多輪工具調(diào)用的 Agent每輪都會往上下文里塞工具返回結(jié)果窗口太小的話跑到第五輪就開始丟前面的信息。第二是函數(shù)調(diào)用能力不是所有模型都支持結(jié)構(gòu)化的 tool use有些模型只能輸出文本你得自己解析這就多了一層不確定性。第三是推理延遲Agent 是循環(huán)執(zhí)行的單次延遲乘以循環(huán)次數(shù)就是總耗時一個每次調(diào)用要 8 秒的模型跑五輪就是 40 秒用戶體驗直接崩掉。我個人的經(jīng)驗是Agent 場景下模型的選擇優(yōu)先級是“函數(shù)調(diào)用穩(wěn)定性 上下文窗口 推理能力 延遲”。原因很簡單Agent 的每一步都依賴上一步的輸出格式正確如果模型經(jīng)常輸出不合法的工具調(diào)用格式后面全盤皆輸。推理能力弱一點可以靠 prompt 補格式不穩(wěn)定是補不回來的。2.2 要素二工具集Agent 的手和腳工具就是 Agent 能調(diào)用的外部函數(shù)。查天氣、搜網(wǎng)頁、讀數(shù)據(jù)庫、發(fā)郵件、執(zhí)行代碼這些都是工具。工具集的設(shè)計直接決定了 Agent 的能力邊界。這里有個常見的誤區(qū)新手總想給 Agent 塞盡可能多的工具覺得工具越多越強大。實際情況恰恰相反。工具數(shù)量超過一定閾值后模型的工具選擇準確率會明顯下降。我實測下來單次暴露給模型的工具控制在 5 到 15 個之間比較穩(wěn)妥超過 20 個之后選錯工具的概率大幅上升。那工具多了怎么辦兩個辦法。一是分組暴露根據(jù)當前任務(wù)階段只暴露相關(guān)工具比如“信息收集階段”只給搜索類工具“執(zhí)行階段”只給操作類工具。二是工具路由先用一次輕量調(diào)用判斷該用哪類工具再在子集里做精確選擇。這兩種方式本質(zhì)上都是在降低單次決策的復(fù)雜度。每個工具的定義也有講究。工具描述要寫清楚三件事什么時候用、參數(shù)是什么意思、返回什么格式。我見過太多工具描述只寫了一句“搜索信息”模型根本不知道什么時候該用它、什么時候不該用。好的工具描述應(yīng)該像一份迷你說明書讓模型看完就知道該不該調(diào)用。2.3 要素三記憶系統(tǒng)不只是存聊天記錄Agent 的記憶分三層短期記憶、長期記憶、工作記憶。短期記憶就是當前對話的上下文長期記憶是跨會話持久化的信息工作記憶是當前任務(wù)執(zhí)行過程中的中間狀態(tài)。大部分人對記憶的理解停留在“把歷史消息拼進 prompt”這只是短期記憶。真正讓 Agent 表現(xiàn)得像“記得住事”的是工作記憶的設(shè)計。舉個例子一個幫你訂機票的 Agent它需要記住用戶出發(fā)城市、目的城市、日期、預(yù)算、已查到的航班列表、用戶偏好的航空公司。這些信息不應(yīng)該散落在對話歷史里而應(yīng)該有一個結(jié)構(gòu)化的任務(wù)狀態(tài)對象每輪循環(huán)開始時注入 prompt循環(huán)結(jié)束后更新。實操心得工作記憶用 JSON 結(jié)構(gòu)維護比純文本歷史可靠得多。模型對結(jié)構(gòu)化字段的讀取準確率明顯高于從大段對話里“回憶”信息。長期記憶則涉及存儲和檢索。簡單場景可以用文件或數(shù)據(jù)庫存關(guān)鍵事實復(fù)雜場景需要向量檢索。但要注意長期記憶的寫入時機很關(guān)鍵不能每輪都寫否則會存進去大量噪音。我的做法是任務(wù)結(jié)束時做一次總結(jié)性寫入只存“用戶偏好”和“任務(wù)結(jié)論”這兩類信息。2.4 要素四規(guī)劃模塊把大目標拆成小步驟規(guī)劃模塊負責把用戶的模糊需求拆解成可執(zhí)行的步驟序列。比如用戶說“幫我調(diào)研一下競品”規(guī)劃模塊要把它拆成確定競品范圍、逐個搜索信息、整理對比維度、生成報告。規(guī)劃有兩種模式靜態(tài)規(guī)劃和動態(tài)規(guī)劃。靜態(tài)規(guī)劃是一次性生成完整步驟列表然后按順序執(zhí)行。動態(tài)規(guī)劃是每執(zhí)行一步根據(jù)結(jié)果決定下一步做什么。靜態(tài)規(guī)劃適合流程固定的任務(wù)動態(tài)規(guī)劃適合探索性任務(wù)。我傾向于混合模式先做一次粗粒度的靜態(tài)規(guī)劃生成 3 到 5 個高層步驟然后每個步驟內(nèi)部用動態(tài)規(guī)劃。這樣既有全局方向感又有局部靈活性。純靜態(tài)規(guī)劃遇到意外情況就卡死了純動態(tài)規(guī)劃容易跑偏或者繞圈子。規(guī)劃模塊的輸出格式也很重要。我一般要求模型輸出一個步驟列表每個步驟包含步驟描述、預(yù)期輸入、預(yù)期輸出、完成條件。完成條件這一項特別關(guān)鍵它讓 Agent 知道什么時候該進入下一步而不是無限循環(huán)。2.5 要素五執(zhí)行器真正干活的那一層執(zhí)行器負責實際調(diào)用工具、解析返回結(jié)果、處理異常。這一層看起來簡單其實是最容易出 bug 的地方。工具調(diào)用的返回結(jié)果格式五花八門有的是 JSON有的是純文本有的是 HTML。執(zhí)行器需要做結(jié)果歸一化把不同格式的返回統(tǒng)一成模型能理解的格式。同時要處理超時和重試一個搜索工具超時了不能直接讓整個 Agent 崩掉要有降級策略。還有一個容易被忽略的點工具返回結(jié)果的長度控制。有些工具返回的內(nèi)容特別長直接塞進上下文會擠占空間。執(zhí)行器需要做截斷或摘要只保留和當前任務(wù)相關(guān)的部分。我一般會設(shè)置一個閾值超過 2000 字符的返回結(jié)果先做一次摘要再注入。2.6 要素六循環(huán)控制器Agent 的心跳循環(huán)控制器決定了 Agent 什么時候繼續(xù)、什么時候停止。這是 Agent 工程里最核心也最容易出問題的部分。一個基本的循環(huán)是這樣的觀察當前狀態(tài)、決定下一步動作、執(zhí)行動作、更新狀態(tài)、判斷是否完成。聽起來簡單但實際運行時會遇到各種邊界情況。比如模型一直調(diào)用同一個工具、模型輸出格式錯誤導(dǎo)致無法解析、任務(wù)已經(jīng)完成了但模型還在繼續(xù)。循環(huán)控制器需要設(shè)置多重終止條件任務(wù)完成標志、最大循環(huán)次數(shù)、連續(xù)無進展檢測、超時限制。這幾個條件缺一不可。我見過只設(shè)最大循環(huán)次數(shù)的實現(xiàn)結(jié)果 Agent 在達到上限之前一直在做無用功白白消耗 token。2.7 要素七輸出格式化讓結(jié)果可用最后一個要素是輸出格式化。Agent 跑完一圈最終要產(chǎn)出一個用戶能用的結(jié)果。這個結(jié)果可能是自然語言回答、結(jié)構(gòu)化數(shù)據(jù)、文件、或者一個操作確認。輸出格式化模塊要做的事情是把 Agent 執(zhí)行過程中的中間狀態(tài)和最終結(jié)果轉(zhuǎn)換成符合預(yù)期的輸出格式。如果用戶要的是 JSON就不能返回一段散文如果用戶要的是報告就要有清晰的結(jié)構(gòu)。這里有個技巧在 Agent 循環(huán)的最后一步專門用一次模型調(diào)用來做格式化而不是讓模型在循環(huán)過程中順便輸出。這樣格式化的質(zhì)量更穩(wěn)定因為模型只需要專注做一件事。3. 七個決策點Agent 運行時到底在做什么選擇3.1 決策點一下一步做什么——繼續(xù)、調(diào)用工具還是結(jié)束這是 Agent 每一輪循環(huán)都要做的第一個決策。模型需要判斷當前狀態(tài)信息夠不夠需不需要調(diào)用工具任務(wù)是不是已經(jīng)完成了這個決策的質(zhì)量直接決定了 Agent 的效率。如果模型過于保守明明信息夠了還要繼續(xù)搜索就會浪費輪次如果過于激進信息不足就急著給答案結(jié)果質(zhì)量就差。我的做法是在 prompt 里明確定義三種狀態(tài)的判斷標準。比如“如果已有信息能完整回答用戶問題輸出 FINISH如果需要外部信息輸出 TOOL_CALL如果當前信息部分足夠但需要補充輸出 TOOL_CALL 并說明缺什么”。把判斷標準寫清楚模型的決策準確率會高很多。3.2 決策點二選哪個工具——工具選擇的優(yōu)先級邏輯當決定要調(diào)用工具后下一個決策是選哪個。前面說過工具數(shù)量要控制但即使只有 5 個工具模型也可能選錯。工具選擇的核心邏輯是匹配度排序。模型需要根據(jù)當前任務(wù)需求評估每個工具的適用程度。這里有個實用技巧在工具描述里加入使用場景標簽比如“適用于實時信息查詢”“不適用于歷史數(shù)據(jù)”。這些標簽?zāi)茱@著提升選擇準確率。另一個技巧是工具調(diào)用示例。在 prompt 里給每個工具配一兩個調(diào)用示例模型看到示例后更容易理解什么時候該用。這比純文字描述有效得多。3.3 決策點三參數(shù)怎么填——從自然語言到結(jié)構(gòu)化參數(shù)選好工具后要填參數(shù)。這是從自然語言到結(jié)構(gòu)化數(shù)據(jù)的轉(zhuǎn)換過程也是容易出錯的地方。比如用戶說“幫我查一下明天北京的天氣”模型需要把它轉(zhuǎn)換成{city: 北京, date: 2024-01-16}。日期格式、城市名稱的規(guī)范化、可選參數(shù)的省略這些都需要模型做判斷。提高參數(shù)填寫準確率的方法有幾個。一是參數(shù)描述要具體不要只寫“日期”要寫“日期格式 YYYY-MM-DD默認為今天”。二是提供參數(shù)示例讓模型有參照。三是做參數(shù)校驗執(zhí)行器在調(diào)用工具前檢查參數(shù)合法性不合法就返回錯誤讓模型重新填。3.4 決策點四結(jié)果怎么解讀——工具返回信息的理解與篩選工具返回結(jié)果后模型需要解讀這些結(jié)果判斷是否滿足當前需求。這一步的難點在于信息篩選返回結(jié)果里可能有很多無關(guān)信息模型需要提取有用的部分。比如搜索工具返回了 10 條結(jié)果模型需要判斷哪幾條和當前任務(wù)相關(guān)。這里容易出現(xiàn)的問題是模型被無關(guān)信息帶偏或者遺漏了關(guān)鍵信息。我的經(jīng)驗是在 prompt 里明確要求模型先總結(jié)工具返回結(jié)果再判斷是否滿足需求。這個“先總結(jié)再判斷”的順序很重要它強迫模型先理解再決策而不是直接跳到結(jié)論。3.5 決策點五狀態(tài)怎么更新——任務(wù)進度的追蹤與調(diào)整每輪循環(huán)結(jié)束后Agent 需要更新自己的狀態(tài)已經(jīng)完成了什么、還缺什么、下一步該做什么。這個決策點決定了 Agent 是否有“全局感”。狀態(tài)更新最容易出的問題是信息丟失。比如第一輪查到了用戶的城市第三輪需要用到這個信息時模型忘了。解決辦法就是前面提到的結(jié)構(gòu)化工作記憶每輪都顯式地把關(guān)鍵狀態(tài)注入 prompt。另一個問題是狀態(tài)更新不及時。比如工具調(diào)用失敗了但狀態(tài)里還標記為“已完成”導(dǎo)致后續(xù)步驟基于錯誤假設(shè)執(zhí)行。所以狀態(tài)更新要和執(zhí)行結(jié)果嚴格綁定成功才標記完成失敗要記錄失敗原因。3.6 決策點六異常怎么處理——工具失敗、格式錯誤、超時的應(yīng)對異常處理是 Agent 工程里最容易被低估的部分。實際運行中工具調(diào)用失敗、模型輸出格式錯誤、網(wǎng)絡(luò)超時這些都是常態(tài)。異常處理的核心原則是優(yōu)雅降級不要崩潰。工具調(diào)用失敗時Agent 應(yīng)該能感知到失敗并決定是重試、換工具、還是跳過這一步。模型輸出格式錯誤時應(yīng)該有一次重新格式化的機會而不是直接報錯退出。我一般會設(shè)置三級異常處理第一級是自動重試適用于網(wǎng)絡(luò)抖動等臨時問題第二級是降級替代比如搜索工具失敗就用緩存結(jié)果第三級是上報給模型讓模型決定怎么處理。三級都處理不了才終止任務(wù)。3.7 決策點七何時停止——完成判斷與終止條件最后一個決策點是判斷任務(wù)是否完成。這個看似簡單實際上很容易出問題。模型有時候會“過度完成”明明任務(wù)已經(jīng)結(jié)束了還在繼續(xù)調(diào)用工具有時候會“提前完成”信息還不夠就給出答案。終止條件要設(shè)計成多條件與邏輯任務(wù)完成標志為真且沒有待處理的子任務(wù)且輸出格式符合要求才終止。任何一個條件不滿足就繼續(xù)循環(huán)。同時要有硬性上限比如最大 15 輪超過就強制終止并返回當前最佳結(jié)果。注意最大循環(huán)次數(shù)不要設(shè)得太高。我見過設(shè) 50 輪的結(jié)果 Agent 在死循環(huán)里燒掉大量 token。一般任務(wù) 10 到 15 輪足夠復(fù)雜任務(wù) 20 輪也到頂了。4. 從零搭建一個最小可用 Agent 的完整實操4.1 環(huán)境準備與技術(shù)選型先說技術(shù)棧。如果你只是想理解 Agent 的原理用 Python 加任意一個支持函數(shù)調(diào)用的 LLM API 就夠了。如果你想快速搭一個能用的系統(tǒng)LangChain 或 CrewAI 是不錯的起點。如果你想要更細粒度的控制建議自己手寫循環(huán)不依賴框架。我個人的選擇是手寫核心循環(huán)加輕量工具庫。原因是我發(fā)現(xiàn)框架的抽象層在調(diào)試時反而增加難度出了問題不知道是框架的鍋還是自己的鍋。手寫循環(huán)雖然代碼多一些但每一行都在自己掌控中。環(huán)境依賴很簡單Python 3.10 以上、一個 LLM API 的 SDK、requests 庫用于調(diào)用外部工具。不需要數(shù)據(jù)庫不需要向量庫最小可用版本用內(nèi)存和文件就夠了。4.2 定義工具集與工具描述先定義三到五個基礎(chǔ)工具。我一般從這幾個開始搜索工具、計算工具、文件讀寫工具、HTTP 請求工具。每個工具用統(tǒng)一的格式定義tools [ { name: search, description: 搜索互聯(lián)網(wǎng)獲取實時信息。適用于查詢新聞、天氣、實時數(shù)據(jù)。不適用于數(shù)學(xué)計算、文件操作。, parameters: { query: {type: string, description: 搜索關(guān)鍵詞盡量具體} } }, { name: calculate, description: 執(zhí)行數(shù)學(xué)計算。適用于加減乘除、百分比、冪運算。不適用于需要外部數(shù)據(jù)的計算。, parameters: { expression: {type: string, description: 數(shù)學(xué)表達式如 2 3 * 4} } } ]工具描述里的“適用于”和“不適用于”是我強烈建議加的。實測下來加了這兩項之后工具選擇準確率能提升不少。4.3 構(gòu)建主循環(huán)與狀態(tài)管理主循環(huán)的結(jié)構(gòu)大概是這樣的def run_agent(user_input, max_turns15): state { goal: user_input, history: [], working_memory: {}, turn: 0, done: False } while not state[done] and state[turn] max_turns: state[turn] 1 # 構(gòu)建 prompt prompt build_prompt(state, tools) # 調(diào)用 LLM response call_llm(prompt) # 解析輸出 action parse_action(response) if action[type] FINISH: state[done] True state[result] action[content] elif action[type] TOOL_CALL: result execute_tool(action[name], action[params]) state[history].append({action: action, result: result}) update_working_memory(state, action, result) else: # 格式錯誤重試一次 state[history].append({error: invalid format}) return state.get(result, 任務(wù)未完成)這個結(jié)構(gòu)看起來簡單但每一部分都有細節(jié)。build_prompt要把工具描述、工作記憶、歷史記錄都拼進去同時控制總長度。parse_action要處理模型輸出的各種格式變體。update_working_memory要判斷哪些信息值得記住。4.4 參數(shù)計算與關(guān)鍵閾值選擇幾個關(guān)鍵參數(shù)需要根據(jù)實際情況調(diào)整。最大循環(huán)次數(shù)我一般設(shè) 15簡單任務(wù) 5 到 8 輪就結(jié)束了復(fù)雜任務(wù) 12 到 15 輪。上下文長度上限根據(jù)模型窗口來定一般留 20% 的余量給輸出。工具返回結(jié)果截斷閾值設(shè) 2000 字符超過就摘要。重試次數(shù)設(shè) 2 次第一次失敗后重試第二次失敗就降級。超時時間單個工具調(diào)用設(shè) 30 秒整個任務(wù)設(shè) 5 分鐘。這些數(shù)值不是固定的要根據(jù)你的具體場景調(diào)整。比如做實時對話的 Agent超時要設(shè)得更短做后臺批處理的可以放寬。4.5 實操現(xiàn)場一個完整任務(wù)的執(zhí)行記錄假設(shè)用戶輸入是“幫我查一下今天北京的天氣然后換算成華氏度”。第一輪模型判斷需要調(diào)用搜索工具參數(shù){query: 北京今天天氣}。工具返回“北京今天晴氣溫 25 攝氏度”。工作記憶更新{weather_celsius: 25}。第二輪模型判斷需要調(diào)用計算工具參數(shù){expression: 25 * 9/5 32}。工具返回 77。工作記憶更新{weather_fahrenheit: 77}。第三輪模型判斷信息足夠輸出 FINISH內(nèi)容為“北京今天晴氣溫 25 攝氏度約合 77 華氏度”。整個過程三輪循環(huán)兩次工具調(diào)用狀態(tài)更新兩次。這個流程跑通之后你就可以往里面加更多工具、更復(fù)雜的規(guī)劃邏輯、更完善的異常處理。5. 常見問題與排查技巧實錄5.1 工具調(diào)用死循環(huán)怎么破這是最常見的問題。Agent 反復(fù)調(diào)用同一個工具每次都得到相似結(jié)果但就是不結(jié)束。原因通常是模型沒有正確判斷“信息已經(jīng)夠了”。排查思路先看工作記憶里是否記錄了已獲取的信息。如果記錄了但模型還是繼續(xù)調(diào)用說明 prompt 里沒有明確告訴模型“這些信息已經(jīng)夠了”。解決辦法是在 prompt 里加一條規(guī)則“如果工作記憶中已包含回答用戶問題所需的所有信息必須輸出 FINISH”。另一個原因是工具返回結(jié)果沒有變化模型以為沒查到。這時候要在工具返回結(jié)果里加一個標記比如“已查詢過結(jié)果同上”讓模型知道這是重復(fù)查詢。5.2 模型輸出格式錯誤頻發(fā)怎么辦模型有時候不按你要求的 JSON 格式輸出而是輸出一段自然語言。這種情況在模型能力較弱時尤其常見。解決辦法有三層。第一層是prompt 里給格式示例讓模型照著抄。第二層是輸出解析器做容錯比如用正則提取 JSON 部分或者嘗試修復(fù)常見的格式錯誤。第三層是格式錯誤時自動重試把錯誤信息返回給模型讓它重新輸出。我一般三層都上。實測下來加了格式示例之后錯誤率能降一半加上容錯解析再降一半最后重試兜底基本不會因為格式問題卡死。5.3 上下文爆炸與信息丟失的平衡Agent 跑多輪之后上下文會越來越長。如果不控制很快就會超出模型窗口。但如果粗暴截斷又會丟失關(guān)鍵信息。我的做法是分層管理上下文。工作記憶始終保留因為它是最關(guān)鍵的狀態(tài)信息。歷史記錄只保留最近 5 輪更早的做摘要。工具返回結(jié)果只保留和當前任務(wù)相關(guān)的部分無關(guān)的丟棄。具體操作上每輪循環(huán)開始時先計算當前上下文長度如果超過閾值就對最早的歷史記錄做摘要壓縮。摘要用一次輕量模型調(diào)用完成成本很低。5.4 常見問題速查表問題現(xiàn)象可能原因排查方法解決方案Agent 不調(diào)用工具工具描述不清晰檢查工具描述是否說明使用場景補充“適用于/不適用于”標簽反復(fù)調(diào)用同一工具未判斷信息已足夠查看工作記憶是否記錄結(jié)果prompt 加完成判斷規(guī)則輸出格式錯誤模型能力不足檢查是否有格式示例加示例容錯解析重試上下文超限歷史記錄太長統(tǒng)計每輪 token 消耗分層管理摘要壓縮任務(wù)提前結(jié)束完成條件太寬松檢查終止條件邏輯改為多條件與邏輯工具調(diào)用超時外部服務(wù)不穩(wěn)定查看工具調(diào)用日志設(shè)超時重試降級5.5 獨家避坑技巧第一個技巧在工具返回結(jié)果里加“置信度”標記。比如搜索結(jié)果標注“高相關(guān)/低相關(guān)”讓模型知道哪些結(jié)果更可信。這個簡單的標記能顯著提升模型的信息篩選質(zhì)量。第二個技巧給 Agent 設(shè)一個“思考預(yù)算”。在 prompt 里告訴模型“你最多有 15 輪機會請高效使用”。模型知道有預(yù)算限制后會更傾向于在信息足夠時及時結(jié)束而不是無限探索。第三個技巧用“反向驗證”提升完成判斷準確率。在 Agent 準備輸出 FINISH 之前加一步驗證“請檢查你的答案是否完整回答了用戶的原始問題”。這一步能攔住不少提前完成的情況。第四個技巧日志要記錄每一輪的完整輸入輸出。Agent 出問題時光看最終結(jié)果根本不知道哪一步錯了。把每輪的 prompt、模型輸出、工具返回都記下來排查效率能提升好幾倍。6. 進階方向從能跑到好用還差什么6.1 多 Agent 協(xié)作的適用場景單 Agent 能解決大部分任務(wù)但有些場景適合多 Agent。比如一個負責調(diào)研、一個負責寫作、一個負責審核。多 Agent 的優(yōu)勢是每個 Agent 的職責更聚焦prompt 可以更精簡工具集可以更小。但多 Agent 也帶來新的問題Agent 之間怎么通信、怎么協(xié)調(diào)、怎么避免互相等待。我的建議是不要過早引入多 Agent。先把單 Agent 跑穩(wěn)確認瓶頸確實在“職責太多”而不是其他原因再考慮拆分。6.2 工具調(diào)用的安全邊界Agent 能調(diào)用工具意味著它能對外部世界產(chǎn)生影響。發(fā)郵件、改數(shù)據(jù)庫、執(zhí)行代碼這些操作一旦出錯后果可能很嚴重。安全邊界的設(shè)計原則是最小權(quán)限加人工確認。Agent 只應(yīng)該擁有完成當前任務(wù)所需的最小工具集。對于有副作用的操作比如發(fā)送、刪除、修改應(yīng)該加一道人工確認或者至少加一個“預(yù)覽”步驟。注意永遠不要給 Agent 無限制的代碼執(zhí)行權(quán)限。如果確實需要執(zhí)行代碼用沙箱環(huán)境限制可訪問的資源。6.3 性能優(yōu)化的幾個方向Agent 的性能瓶頸通常在兩個地方LLM 調(diào)用延遲和工具調(diào)用延遲。優(yōu)化 LLM 延遲可以用更小的模型做簡單決策只在關(guān)鍵步驟用大模型。優(yōu)化工具延遲可以并行調(diào)用無依賴的工具或者做結(jié)果緩存。還有一個容易被忽略的優(yōu)化點減少不必要的循環(huán)輪次。很多 Agent 之所以慢是因為做了太多無用功。通過優(yōu)化 prompt 讓模型更果斷地做決策比優(yōu)化單次調(diào)用速度效果更明顯。6.4 評估與迭代怎么知道 Agent 變好了Agent 的評估比傳統(tǒng)軟件難因為它的輸出不是確定性的。我的做法是建一個測試用例集包含 20 到 30 個典型任務(wù)每個任務(wù)有明確的成功標準。每次修改 prompt 或工具后跑一遍測試集看成功率的變化。除了成功率還要關(guān)注平均循環(huán)輪次和平均 token 消耗。一個 Agent 成功率提升了但輪次翻倍未必是好事。好的優(yōu)化應(yīng)該是成功率和效率同時改善。我在實際項目中的體會是Agent 的迭代很像調(diào)參但比調(diào)參更依賴對任務(wù)本身的理解。你得知道這個任務(wù)“合理的執(zhí)行路徑”是什么樣的才能判斷 Agent 的行為是否正常。如果自己都不清楚一個任務(wù)應(yīng)該幾步完成那就沒法評估 Agent 做得好不好。所以做 Agent 開發(fā)先把手動執(zhí)行這個任務(wù)的流程走一遍記錄下來這個記錄就是你評估 Agent 的基準線。 AI Agent 工程骨架：七要素與七個決策點全解析
1. 為什么“七要素”和“七個決策點”才是 Agent 工程的骨架很多人第一次接觸 AI Agent腦子里蹦出來的畫面是科幻電影里那種能自己思考、自己行動的智能體。但真到了動手寫代碼的階段你會發(fā)現(xiàn)事情完全不是那么回事。你寫了一個循環(huán)讓大模型反復(fù)調(diào)用工具結(jié)果它要么陷入死循環(huán)要么在第三步就忘了第一步的目標要么調(diào)用了一個根本不存在的函數(shù)還理直氣壯地編造結(jié)果。這些問題不是模型不夠聰明而是工程實現(xiàn)上缺了骨架。我做了幾個 Agent 項目之后踩了一圈坑回過頭來發(fā)現(xiàn)一個規(guī)律所有能穩(wěn)定跑起來的 Agent底層都逃不開七個核心要素和七個關(guān)鍵決策點。七要素是“一個 Agent 由哪些零件組成”七個決策點是“這些零件在運行時怎么做選擇”。前者是靜態(tài)結(jié)構(gòu)后者是動態(tài)邏輯。把這兩件事想清楚了不管你用 LangChain、CrewAI、Dify 還是自己從零手寫都不會迷路。這篇文章適合誰看如果你已經(jīng)用過大模型 API知道什么是 prompt、什么是 function calling但一提到“搭一個 Agent”就覺得無從下手那這篇就是寫給你的。如果你已經(jīng)在做 Agent 開發(fā)但系統(tǒng)總是不穩(wěn)定、行為不可預(yù)測那這篇也能幫你找到結(jié)構(gòu)性的原因。我會盡量用大白話把每個要素和決策點講透配上可以直接參考的實現(xiàn)思路和參數(shù)選擇邏輯讓你看完就能動手改自己的項目。核心關(guān)鍵詞先擺出來AI Agent、LLM、工具調(diào)用、循環(huán)機制、Agent 架構(gòu)。這幾個詞貫穿全文后面每個章節(jié)都會圍繞它們展開。2. 七要素拆解一個 Agent 到底由什么組成2.1 要素一LLM 作為推理內(nèi)核但不是全部很多人把 Agent 等同于“大模型加個循環(huán)”這個理解只對了三分之一。LLM 在 Agent 里的角色是推理內(nèi)核負責理解目標、拆解任務(wù)、決定下一步動作。但它不是 Agent 的全部甚至不是最脆弱的部分。選 LLM 做 Agent 內(nèi)核時有幾個參數(shù)必須關(guān)注。第一是上下文窗口因為它決定了 Agent 能“記住”多少歷史信息。一個多輪工具調(diào)用的 Agent每輪都會往上下文里塞工具返回結(jié)果窗口太小的話跑到第五輪就開始丟前面的信息。第二是函數(shù)調(diào)用能力不是所有模型都支持結(jié)構(gòu)化的 tool use有些模型只能輸出文本你得自己解析這就多了一層不確定性。第三是推理延遲Agent 是循環(huán)執(zhí)行的單次延遲乘以循環(huán)次數(shù)就是總耗時一個每次調(diào)用要 8 秒的模型跑五輪就是 40 秒用戶體驗直接崩掉。我個人的經(jīng)驗是Agent 場景下模型的選擇優(yōu)先級是“函數(shù)調(diào)用穩(wěn)定性 上下文窗口 推理能力 延遲”。原因很簡單Agent 的每一步都依賴上一步的輸出格式正確如果模型經(jīng)常輸出不合法的工具調(diào)用格式后面全盤皆輸。推理能力弱一點可以靠 prompt 補格式不穩(wěn)定是補不回來的。2.2 要素二工具集Agent 的手和腳工具就是 Agent 能調(diào)用的外部函數(shù)。查天氣、搜網(wǎng)頁、讀數(shù)據(jù)庫、發(fā)郵件、執(zhí)行代碼這些都是工具。工具集的設(shè)計直接決定了 Agent 的能力邊界。這里有個常見的誤區(qū)新手總想給 Agent 塞盡可能多的工具覺得工具越多越強大。實際情況恰恰相反。工具數(shù)量超過一定閾值后模型的工具選擇準確率會明顯下降。我實測下來單次暴露給模型的工具控制在 5 到 15 個之間比較穩(wěn)妥超過 20 個之后選錯工具的概率大幅上升。那工具多了怎么辦兩個辦法。一是分組暴露根據(jù)當前任務(wù)階段只暴露相關(guān)工具比如“信息收集階段”只給搜索類工具“執(zhí)行階段”只給操作類工具。二是工具路由先用一次輕量調(diào)用判斷該用哪類工具再在子集里做精確選擇。這兩種方式本質(zhì)上都是在降低單次決策的復(fù)雜度。每個工具的定義也有講究。工具描述要寫清楚三件事什么時候用、參數(shù)是什么意思、返回什么格式。我見過太多工具描述只寫了一句“搜索信息”模型根本不知道什么時候該用它、什么時候不該用。好的工具描述應(yīng)該像一份迷你說明書讓模型看完就知道該不該調(diào)用。2.3 要素三記憶系統(tǒng)不只是存聊天記錄Agent 的記憶分三層短期記憶、長期記憶、工作記憶。短期記憶就是當前對話的上下文長期記憶是跨會話持久化的信息工作記憶是當前任務(wù)執(zhí)行過程中的中間狀態(tài)。大部分人對記憶的理解停留在“把歷史消息拼進 prompt”這只是短期記憶。真正讓 Agent 表現(xiàn)得像“記得住事”的是工作記憶的設(shè)計。舉個例子一個幫你訂機票的 Agent它需要記住用戶出發(fā)城市、目的城市、日期、預(yù)算、已查到的航班列表、用戶偏好的航空公司。這些信息不應(yīng)該散落在對話歷史里而應(yīng)該有一個結(jié)構(gòu)化的任務(wù)狀態(tài)對象每輪循環(huán)開始時注入 prompt循環(huán)結(jié)束后更新。實操心得工作記憶用 JSON 結(jié)構(gòu)維護比純文本歷史可靠得多。模型對結(jié)構(gòu)化字段的讀取準確率明顯高于從大段對話里“回憶”信息。長期記憶則涉及存儲和檢索。簡單場景可以用文件或數(shù)據(jù)庫存關(guān)鍵事實復(fù)雜場景需要向量檢索。但要注意長期記憶的寫入時機很關(guān)鍵不能每輪都寫否則會存進去大量噪音。我的做法是任務(wù)結(jié)束時做一次總結(jié)性寫入只存“用戶偏好”和“任務(wù)結(jié)論”這兩類信息。2.4 要素四規(guī)劃模塊把大目標拆成小步驟規(guī)劃模塊負責把用戶的模糊需求拆解成可執(zhí)行的步驟序列。比如用戶說“幫我調(diào)研一下競品”規(guī)劃模塊要把它拆成確定競品范圍、逐個搜索信息、整理對比維度、生成報告。規(guī)劃有兩種模式靜態(tài)規(guī)劃和動態(tài)規(guī)劃。靜態(tài)規(guī)劃是一次性生成完整步驟列表然后按順序執(zhí)行。動態(tài)規(guī)劃是每執(zhí)行一步根據(jù)結(jié)果決定下一步做什么。靜態(tài)規(guī)劃適合流程固定的任務(wù)動態(tài)規(guī)劃適合探索性任務(wù)。我傾向于混合模式先做一次粗粒度的靜態(tài)規(guī)劃生成 3 到 5 個高層步驟然后每個步驟內(nèi)部用動態(tài)規(guī)劃。這樣既有全局方向感又有局部靈活性。純靜態(tài)規(guī)劃遇到意外情況就卡死了純動態(tài)規(guī)劃容易跑偏或者繞圈子。規(guī)劃模塊的輸出格式也很重要。我一般要求模型輸出一個步驟列表每個步驟包含步驟描述、預(yù)期輸入、預(yù)期輸出、完成條件。完成條件這一項特別關(guān)鍵它讓 Agent 知道什么時候該進入下一步而不是無限循環(huán)。2.5 要素五執(zhí)行器真正干活的那一層執(zhí)行器負責實際調(diào)用工具、解析返回結(jié)果、處理異常。這一層看起來簡單其實是最容易出 bug 的地方。工具調(diào)用的返回結(jié)果格式五花八門有的是 JSON有的是純文本有的是 HTML。執(zhí)行器需要做結(jié)果歸一化把不同格式的返回統(tǒng)一成模型能理解的格式。同時要處理超時和重試一個搜索工具超時了不能直接讓整個 Agent 崩掉要有降級策略。還有一個容易被忽略的點工具返回結(jié)果的長度控制。有些工具返回的內(nèi)容特別長直接塞進上下文會擠占空間。執(zhí)行器需要做截斷或摘要只保留和當前任務(wù)相關(guān)的部分。我一般會設(shè)置一個閾值超過 2000 字符的返回結(jié)果先做一次摘要再注入。2.6 要素六循環(huán)控制器Agent 的心跳循環(huán)控制器決定了 Agent 什么時候繼續(xù)、什么時候停止。這是 Agent 工程里最核心也最容易出問題的部分。一個基本的循環(huán)是這樣的觀察當前狀態(tài)、決定下一步動作、執(zhí)行動作、更新狀態(tài)、判斷是否完成。聽起來簡單但實際運行時會遇到各種邊界情況。比如模型一直調(diào)用同一個工具、模型輸出格式錯誤導(dǎo)致無法解析、任務(wù)已經(jīng)完成了但模型還在繼續(xù)。循環(huán)控制器需要設(shè)置多重終止條件任務(wù)完成標志、最大循環(huán)次數(shù)、連續(xù)無進展檢測、超時限制。這幾個條件缺一不可。我見過只設(shè)最大循環(huán)次數(shù)的實現(xiàn)結(jié)果 Agent 在達到上限之前一直在做無用功白白消耗 token。2.7 要素七輸出格式化讓結(jié)果可用最后一個要素是輸出格式化。Agent 跑完一圈最終要產(chǎn)出一個用戶能用的結(jié)果。這個結(jié)果可能是自然語言回答、結(jié)構(gòu)化數(shù)據(jù)、文件、或者一個操作確認。輸出格式化模塊要做的事情是把 Agent 執(zhí)行過程中的中間狀態(tài)和最終結(jié)果轉(zhuǎn)換成符合預(yù)期的輸出格式。如果用戶要的是 JSON就不能返回一段散文如果用戶要的是報告就要有清晰的結(jié)構(gòu)。這里有個技巧在 Agent 循環(huán)的最后一步專門用一次模型調(diào)用來做格式化而不是讓模型在循環(huán)過程中順便輸出。這樣格式化的質(zhì)量更穩(wěn)定因為模型只需要專注做一件事。3. 七個決策點Agent 運行時到底在做什么選擇3.1 決策點一下一步做什么——繼續(xù)、調(diào)用工具還是結(jié)束這是 Agent 每一輪循環(huán)都要做的第一個決策。模型需要判斷當前狀態(tài)信息夠不夠需不需要調(diào)用工具任務(wù)是不是已經(jīng)完成了這個決策的質(zhì)量直接決定了 Agent 的效率。如果模型過于保守明明信息夠了還要繼續(xù)搜索就會浪費輪次如果過于激進信息不足就急著給答案結(jié)果質(zhì)量就差。我的做法是在 prompt 里明確定義三種狀態(tài)的判斷標準。比如“如果已有信息能完整回答用戶問題輸出 FINISH如果需要外部信息輸出 TOOL_CALL如果當前信息部分足夠但需要補充輸出 TOOL_CALL 并說明缺什么”。把判斷標準寫清楚模型的決策準確率會高很多。3.2 決策點二選哪個工具——工具選擇的優(yōu)先級邏輯當決定要調(diào)用工具后下一個決策是選哪個。前面說過工具數(shù)量要控制但即使只有 5 個工具模型也可能選錯。工具選擇的核心邏輯是匹配度排序。模型需要根據(jù)當前任務(wù)需求評估每個工具的適用程度。這里有個實用技巧在工具描述里加入使用場景標簽比如“適用于實時信息查詢”“不適用于歷史數(shù)據(jù)”。這些標簽?zāi)茱@著提升選擇準確率。另一個技巧是工具調(diào)用示例。在 prompt 里給每個工具配一兩個調(diào)用示例模型看到示例后更容易理解什么時候該用。這比純文字描述有效得多。3.3 決策點三參數(shù)怎么填——從自然語言到結(jié)構(gòu)化參數(shù)選好工具后要填參數(shù)。這是從自然語言到結(jié)構(gòu)化數(shù)據(jù)的轉(zhuǎn)換過程也是容易出錯的地方。比如用戶說“幫我查一下明天北京的天氣”模型需要把它轉(zhuǎn)換成{city: 北京, date: 2024-01-16}。日期格式、城市名稱的規(guī)范化、可選參數(shù)的省略這些都需要模型做判斷。提高參數(shù)填寫準確率的方法有幾個。一是參數(shù)描述要具體不要只寫“日期”要寫“日期格式 YYYY-MM-DD默認為今天”。二是提供參數(shù)示例讓模型有參照。三是做參數(shù)校驗執(zhí)行器在調(diào)用工具前檢查參數(shù)合法性不合法就返回錯誤讓模型重新填。3.4 決策點四結(jié)果怎么解讀——工具返回信息的理解與篩選工具返回結(jié)果后模型需要解讀這些結(jié)果判斷是否滿足當前需求。這一步的難點在于信息篩選返回結(jié)果里可能有很多無關(guān)信息模型需要提取有用的部分。比如搜索工具返回了 10 條結(jié)果模型需要判斷哪幾條和當前任務(wù)相關(guān)。這里容易出現(xiàn)的問題是模型被無關(guān)信息帶偏或者遺漏了關(guān)鍵信息。我的經(jīng)驗是在 prompt 里明確要求模型先總結(jié)工具返回結(jié)果再判斷是否滿足需求。這個“先總結(jié)再判斷”的順序很重要它強迫模型先理解再決策而不是直接跳到結(jié)論。3.5 決策點五狀態(tài)怎么更新——任務(wù)進度的追蹤與調(diào)整每輪循環(huán)結(jié)束后Agent 需要更新自己的狀態(tài)已經(jīng)完成了什么、還缺什么、下一步該做什么。這個決策點決定了 Agent 是否有“全局感”。狀態(tài)更新最容易出的問題是信息丟失。比如第一輪查到了用戶的城市第三輪需要用到這個信息時模型忘了。解決辦法就是前面提到的結(jié)構(gòu)化工作記憶每輪都顯式地把關(guān)鍵狀態(tài)注入 prompt。另一個問題是狀態(tài)更新不及時。比如工具調(diào)用失敗了但狀態(tài)里還標記為“已完成”導(dǎo)致后續(xù)步驟基于錯誤假設(shè)執(zhí)行。所以狀態(tài)更新要和執(zhí)行結(jié)果嚴格綁定成功才標記完成失敗要記錄失敗原因。3.6 決策點六異常怎么處理——工具失敗、格式錯誤、超時的應(yīng)對異常處理是 Agent 工程里最容易被低估的部分。實際運行中工具調(diào)用失敗、模型輸出格式錯誤、網(wǎng)絡(luò)超時這些都是常態(tài)。異常處理的核心原則是優(yōu)雅降級不要崩潰。工具調(diào)用失敗時Agent 應(yīng)該能感知到失敗并決定是重試、換工具、還是跳過這一步。模型輸出格式錯誤時應(yīng)該有一次重新格式化的機會而不是直接報錯退出。我一般會設(shè)置三級異常處理第一級是自動重試適用于網(wǎng)絡(luò)抖動等臨時問題第二級是降級替代比如搜索工具失敗就用緩存結(jié)果第三級是上報給模型讓模型決定怎么處理。三級都處理不了才終止任務(wù)。3.7 決策點七何時停止——完成判斷與終止條件最后一個決策點是判斷任務(wù)是否完成。這個看似簡單實際上很容易出問題。模型有時候會“過度完成”明明任務(wù)已經(jīng)結(jié)束了還在繼續(xù)調(diào)用工具有時候會“提前完成”信息還不夠就給出答案。終止條件要設(shè)計成多條件與邏輯任務(wù)完成標志為真且沒有待處理的子任務(wù)且輸出格式符合要求才終止。任何一個條件不滿足就繼續(xù)循環(huán)。同時要有硬性上限比如最大 15 輪超過就強制終止并返回當前最佳結(jié)果。注意最大循環(huán)次數(shù)不要設(shè)得太高。我見過設(shè) 50 輪的結(jié)果 Agent 在死循環(huán)里燒掉大量 token。一般任務(wù) 10 到 15 輪足夠復(fù)雜任務(wù) 20 輪也到頂了。4. 從零搭建一個最小可用 Agent 的完整實操4.1 環(huán)境準備與技術(shù)選型先說技術(shù)棧。如果你只是想理解 Agent 的原理用 Python 加任意一個支持函數(shù)調(diào)用的 LLM API 就夠了。如果你想快速搭一個能用的系統(tǒng)LangChain 或 CrewAI 是不錯的起點。如果你想要更細粒度的控制建議自己手寫循環(huán)不依賴框架。我個人的選擇是手寫核心循環(huán)加輕量工具庫。原因是我發(fā)現(xiàn)框架的抽象層在調(diào)試時反而增加難度出了問題不知道是框架的鍋還是自己的鍋。手寫循環(huán)雖然代碼多一些但每一行都在自己掌控中。環(huán)境依賴很簡單Python 3.10 以上、一個 LLM API 的 SDK、requests 庫用于調(diào)用外部工具。不需要數(shù)據(jù)庫不需要向量庫最小可用版本用內(nèi)存和文件就夠了。4.2 定義工具集與工具描述先定義三到五個基礎(chǔ)工具。我一般從這幾個開始搜索工具、計算工具、文件讀寫工具、HTTP 請求工具。每個工具用統(tǒng)一的格式定義tools [ { name: search, description: 搜索互聯(lián)網(wǎng)獲取實時信息。適用于查詢新聞、天氣、實時數(shù)據(jù)。不適用于數(shù)學(xué)計算、文件操作。, parameters: { query: {type: string, description: 搜索關(guān)鍵詞盡量具體} } }, { name: calculate, description: 執(zhí)行數(shù)學(xué)計算。適用于加減乘除、百分比、冪運算。不適用于需要外部數(shù)據(jù)的計算。, parameters: { expression: {type: string, description: 數(shù)學(xué)表達式如 2 3 * 4} } } ]工具描述里的“適用于”和“不適用于”是我強烈建議加的。實測下來加了這兩項之后工具選擇準確率能提升不少。4.3 構(gòu)建主循環(huán)與狀態(tài)管理主循環(huán)的結(jié)構(gòu)大概是這樣的def run_agent(user_input, max_turns15): state { goal: user_input, history: [], working_memory: {}, turn: 0, done: False } while not state[done] and state[turn] max_turns: state[turn] 1 # 構(gòu)建 prompt prompt build_prompt(state, tools) # 調(diào)用 LLM response call_llm(prompt) # 解析輸出 action parse_action(response) if action[type] FINISH: state[done] True state[result] action[content] elif action[type] TOOL_CALL: result execute_tool(action[name], action[params]) state[history].append({action: action, result: result}) update_working_memory(state, action, result) else: # 格式錯誤重試一次 state[history].append({error: invalid format}) return state.get(result, 任務(wù)未完成)這個結(jié)構(gòu)看起來簡單但每一部分都有細節(jié)。build_prompt要把工具描述、工作記憶、歷史記錄都拼進去同時控制總長度。parse_action要處理模型輸出的各種格式變體。update_working_memory要判斷哪些信息值得記住。4.4 參數(shù)計算與關(guān)鍵閾值選擇幾個關(guān)鍵參數(shù)需要根據(jù)實際情況調(diào)整。最大循環(huán)次數(shù)我一般設(shè) 15簡單任務(wù) 5 到 8 輪就結(jié)束了復(fù)雜任務(wù) 12 到 15 輪。上下文長度上限根據(jù)模型窗口來定一般留 20% 的余量給輸出。工具返回結(jié)果截斷閾值設(shè) 2000 字符超過就摘要。重試次數(shù)設(shè) 2 次第一次失敗后重試第二次失敗就降級。超時時間單個工具調(diào)用設(shè) 30 秒整個任務(wù)設(shè) 5 分鐘。這些數(shù)值不是固定的要根據(jù)你的具體場景調(diào)整。比如做實時對話的 Agent超時要設(shè)得更短做后臺批處理的可以放寬。4.5 實操現(xiàn)場一個完整任務(wù)的執(zhí)行記錄假設(shè)用戶輸入是“幫我查一下今天北京的天氣然后換算成華氏度”。第一輪模型判斷需要調(diào)用搜索工具參數(shù){query: 北京今天天氣}。工具返回“北京今天晴氣溫 25 攝氏度”。工作記憶更新{weather_celsius: 25}。第二輪模型判斷需要調(diào)用計算工具參數(shù){expression: 25 * 9/5 32}。工具返回 77。工作記憶更新{weather_fahrenheit: 77}。第三輪模型判斷信息足夠輸出 FINISH內(nèi)容為“北京今天晴氣溫 25 攝氏度約合 77 華氏度”。整個過程三輪循環(huán)兩次工具調(diào)用狀態(tài)更新兩次。這個流程跑通之后你就可以往里面加更多工具、更復(fù)雜的規(guī)劃邏輯、更完善的異常處理。5. 常見問題與排查技巧實錄5.1 工具調(diào)用死循環(huán)怎么破這是最常見的問題。Agent 反復(fù)調(diào)用同一個工具每次都得到相似結(jié)果但就是不結(jié)束。原因通常是模型沒有正確判斷“信息已經(jīng)夠了”。排查思路先看工作記憶里是否記錄了已獲取的信息。如果記錄了但模型還是繼續(xù)調(diào)用說明 prompt 里沒有明確告訴模型“這些信息已經(jīng)夠了”。解決辦法是在 prompt 里加一條規(guī)則“如果工作記憶中已包含回答用戶問題所需的所有信息必須輸出 FINISH”。另一個原因是工具返回結(jié)果沒有變化模型以為沒查到。這時候要在工具返回結(jié)果里加一個標記比如“已查詢過結(jié)果同上”讓模型知道這是重復(fù)查詢。5.2 模型輸出格式錯誤頻發(fā)怎么辦模型有時候不按你要求的 JSON 格式輸出而是輸出一段自然語言。這種情況在模型能力較弱時尤其常見。解決辦法有三層。第一層是prompt 里給格式示例讓模型照著抄。第二層是輸出解析器做容錯比如用正則提取 JSON 部分或者嘗試修復(fù)常見的格式錯誤。第三層是格式錯誤時自動重試把錯誤信息返回給模型讓它重新輸出。我一般三層都上。實測下來加了格式示例之后錯誤率能降一半加上容錯解析再降一半最后重試兜底基本不會因為格式問題卡死。5.3 上下文爆炸與信息丟失的平衡Agent 跑多輪之后上下文會越來越長。如果不控制很快就會超出模型窗口。但如果粗暴截斷又會丟失關(guān)鍵信息。我的做法是分層管理上下文。工作記憶始終保留因為它是最關(guān)鍵的狀態(tài)信息。歷史記錄只保留最近 5 輪更早的做摘要。工具返回結(jié)果只保留和當前任務(wù)相關(guān)的部分無關(guān)的丟棄。具體操作上每輪循環(huán)開始時先計算當前上下文長度如果超過閾值就對最早的歷史記錄做摘要壓縮。摘要用一次輕量模型調(diào)用完成成本很低。5.4 常見問題速查表問題現(xiàn)象可能原因排查方法解決方案Agent 不調(diào)用工具工具描述不清晰檢查工具描述是否說明使用場景補充“適用于/不適用于”標簽反復(fù)調(diào)用同一工具未判斷信息已足夠查看工作記憶是否記錄結(jié)果prompt 加完成判斷規(guī)則輸出格式錯誤模型能力不足檢查是否有格式示例加示例容錯解析重試上下文超限歷史記錄太長統(tǒng)計每輪 token 消耗分層管理摘要壓縮任務(wù)提前結(jié)束完成條件太寬松檢查終止條件邏輯改為多條件與邏輯工具調(diào)用超時外部服務(wù)不穩(wěn)定查看工具調(diào)用日志設(shè)超時重試降級5.5 獨家避坑技巧第一個技巧在工具返回結(jié)果里加“置信度”標記。比如搜索結(jié)果標注“高相關(guān)/低相關(guān)”讓模型知道哪些結(jié)果更可信。這個簡單的標記能顯著提升模型的信息篩選質(zhì)量。第二個技巧給 Agent 設(shè)一個“思考預(yù)算”。在 prompt 里告訴模型“你最多有 15 輪機會請高效使用”。模型知道有預(yù)算限制后會更傾向于在信息足夠時及時結(jié)束而不是無限探索。第三個技巧用“反向驗證”提升完成判斷準確率。在 Agent 準備輸出 FINISH 之前加一步驗證“請檢查你的答案是否完整回答了用戶的原始問題”。這一步能攔住不少提前完成的情況。第四個技巧日志要記錄每一輪的完整輸入輸出。Agent 出問題時光看最終結(jié)果根本不知道哪一步錯了。把每輪的 prompt、模型輸出、工具返回都記下來排查效率能提升好幾倍。6. 進階方向從能跑到好用還差什么6.1 多 Agent 協(xié)作的適用場景單 Agent 能解決大部分任務(wù)但有些場景適合多 Agent。比如一個負責調(diào)研、一個負責寫作、一個負責審核。多 Agent 的優(yōu)勢是每個 Agent 的職責更聚焦prompt 可以更精簡工具集可以更小。但多 Agent 也帶來新的問題Agent 之間怎么通信、怎么協(xié)調(diào)、怎么避免互相等待。我的建議是不要過早引入多 Agent。先把單 Agent 跑穩(wěn)確認瓶頸確實在“職責太多”而不是其他原因再考慮拆分。6.2 工具調(diào)用的安全邊界Agent 能調(diào)用工具意味著它能對外部世界產(chǎn)生影響。發(fā)郵件、改數(shù)據(jù)庫、執(zhí)行代碼這些操作一旦出錯后果可能很嚴重。安全邊界的設(shè)計原則是最小權(quán)限加人工確認。Agent 只應(yīng)該擁有完成當前任務(wù)所需的最小工具集。對于有副作用的操作比如發(fā)送、刪除、修改應(yīng)該加一道人工確認或者至少加一個“預(yù)覽”步驟。注意永遠不要給 Agent 無限制的代碼執(zhí)行權(quán)限。如果確實需要執(zhí)行代碼用沙箱環(huán)境限制可訪問的資源。6.3 性能優(yōu)化的幾個方向Agent 的性能瓶頸通常在兩個地方LLM 調(diào)用延遲和工具調(diào)用延遲。優(yōu)化 LLM 延遲可以用更小的模型做簡單決策只在關(guān)鍵步驟用大模型。優(yōu)化工具延遲可以并行調(diào)用無依賴的工具或者做結(jié)果緩存。還有一個容易被忽略的優(yōu)化點減少不必要的循環(huán)輪次。很多 Agent 之所以慢是因為做了太多無用功。通過優(yōu)化 prompt 讓模型更果斷地做決策比優(yōu)化單次調(diào)用速度效果更明顯。6.4 評估與迭代怎么知道 Agent 變好了Agent 的評估比傳統(tǒng)軟件難因為它的輸出不是確定性的。我的做法是建一個測試用例集包含 20 到 30 個典型任務(wù)每個任務(wù)有明確的成功標準。每次修改 prompt 或工具后跑一遍測試集看成功率的變化。除了成功率還要關(guān)注平均循環(huán)輪次和平均 token 消耗。一個 Agent 成功率提升了但輪次翻倍未必是好事。好的優(yōu)化應(yīng)該是成功率和效率同時改善。我在實際項目中的體會是Agent 的迭代很像調(diào)參但比調(diào)參更依賴對任務(wù)本身的理解。你得知道這個任務(wù)“合理的執(zhí)行路徑”是什么樣的才能判斷 Agent 的行為是否正常。如果自己都不清楚一個任務(wù)應(yīng)該幾步完成那就沒法評估 Agent 做得好不好。所以做 Agent 開發(fā)先把手動執(zhí)行這個任務(wù)的流程走一遍記錄下來這個記錄就是你評估 Agent 的基準線。