1. 拆之前先想清楚為什么要看這個 Agent 框架大模型圈子里做應(yīng)用的人最近一年繞不開一個詞——Agent。但真正動手寫過 Agent 的人都知道從能聊天到能干活之間隔著一道巨大的鴻溝。你讓模型調(diào)用一個工具它可能給你編一個不存在的函數(shù)名你讓它連續(xù)執(zhí)行三步任務(wù)它可能在第二步就忘了第一步的上下文你想給它加一個新能力結(jié)果發(fā)現(xiàn)得改核心調(diào)度邏輯牽一發(fā)動全身。我最近花了兩天時間把一個開源 Agent 框架的源碼從頭到尾拆了一遍。這個框架的核心賣點就兩個字插件化。拆完之后我的感受是它把插件化這件事做到了一個相當(dāng)徹底的程度——不是那種預(yù)留了幾個擴展點的偽插件化而是從工具注冊、執(zhí)行調(diào)度、上下文管理到多 Agent 協(xié)作每一層都是可插拔的。這篇文章適合兩類人看一類是正在選型 Agent 框架、想知道插件化到底能做到什么程度的開發(fā)者另一類是自己正在寫 Agent 調(diào)度邏輯、想?yún)⒖家幌鲁墒煸O(shè)計思路的工程師。我會從整體架構(gòu)、核心模塊、實操流程、踩坑經(jīng)驗四個維度展開盡量把每個設(shè)計決策背后的為什么講清楚。說明本文基于對該框架公開源碼的分析和實際運行測試涉及的具體項目名稱和代碼細(xì)節(jié)做了脫敏處理但技術(shù)邏輯和設(shè)計思路保持原樣。2. 整體架構(gòu)拆解插件化到底體現(xiàn)在哪幾層2.1 從一次完整的 Agent 調(diào)用說起要看懂一個框架的插件化設(shè)計最好的方式不是先看目錄結(jié)構(gòu)而是先跟一遍完整的調(diào)用鏈路。我以一個最典型的場景為例用戶說幫我查一下明天北京的天氣然后根據(jù)天氣推薦穿什么衣服。這個請求進(jìn)入框架后大致經(jīng)歷以下幾個階段意圖解析框架把用戶輸入交給大模型模型判斷需要調(diào)用天氣查詢工具輸出一個結(jié)構(gòu)化的工具調(diào)用請求。工具路由框架根據(jù)模型輸出的工具名稱在注冊表中找到對應(yīng)的工具實現(xiàn)。參數(shù)校驗與執(zhí)行對模型輸出的參數(shù)做校驗然后執(zhí)行工具函數(shù)拿到天氣數(shù)據(jù)。結(jié)果回傳與二次推理把天氣數(shù)據(jù)塞回對話上下文再次調(diào)用模型模型根據(jù)天氣數(shù)據(jù)生成穿衣建議。最終輸出把模型的最終回復(fù)返回給用戶。這個鏈路看起來簡單但每一步都藏著插件化的設(shè)計空間。比如第2步的工具路由如果框架把工具名稱硬編碼在調(diào)度邏輯里那你每加一個工具就得改核心代碼。而這個框架的做法是工具注冊表本身就是一個可替換的組件你甚至可以把默認(rèn)的本地注冊表換成一個遠(yuǎn)程的工具市場。2.2 四層插件化架構(gòu)拆完源碼后我把它的插件化設(shè)計歸納為四個層次從外到內(nèi)依次是層級插件化對象擴展方式典型場景第一層工具Tool實現(xiàn)標(biāo)準(zhǔn)接口并注冊添加自定義 API 調(diào)用第二層執(zhí)行器Executor替換執(zhí)行策略切換同步/異步/分布式執(zhí)行第三層記憶Memory替換存儲后端從內(nèi)存切換到向量數(shù)據(jù)庫第四層規(guī)劃器Planner替換推理策略從 ReAct 切換到 Plan-and-Execute這四層不是孤立的它們之間通過明確定義的接口通信。這意味著你可以在不改動其他層的前提下單獨替換任意一層的實現(xiàn)。比如你只想把記憶后端從內(nèi)存換成 Redis那只需要實現(xiàn) Memory 接口然后在初始化時傳入你的實現(xiàn)即可工具層和規(guī)劃器層完全無感知。2.3 為什么是這四層而不是別的我一開始有個疑問為什么偏偏抽象出這四層后來想明白了這四層對應(yīng)的是 Agent 運行時的四個核心關(guān)注點——能做什么工具、怎么執(zhí)行執(zhí)行器、記得什么記憶、怎么決策規(guī)劃器。任何一個 Agent 系統(tǒng)不管用什么語言寫、跑在什么環(huán)境里都逃不開這四個問題。把這四個關(guān)注點各自抽象成可替換的組件好處是顯而易見的。舉個實際例子你在開發(fā)環(huán)境用內(nèi)存做記憶存儲跑得好好的上線后發(fā)現(xiàn)多輪對話一多內(nèi)存扛不住了這時候你只需要換一個基于數(shù)據(jù)庫的 Memory 實現(xiàn)其他代碼一行不用改。這種局部替換、全局無感的能力才是插件化真正的價值。實操心得判斷一個框架的插件化是不是真插件化有個簡單的測試方法——試著在不看核心源碼的情況下只通過文檔和接口定義替換掉其中一個組件。如果替換過程中你被迫去讀調(diào)度器的內(nèi)部實現(xiàn)那說明抽象層沒做干凈。3. 工具系統(tǒng)插件化的門面與核心3.1 一個工具從定義到被調(diào)用的完整生命周期工具系統(tǒng)是大多數(shù)開發(fā)者接觸這個框架的第一個入口也是插件化體現(xiàn)得最直觀的地方。我以一個自定義工具為例走一遍完整流程。假設(shè)我要添加一個查詢快遞物流的工具。第一步是定義工具的描述信息這部分信息會被傳給大模型讓模型知道這個工具的存在和用法。描述信息通常包括工具名稱、功能說明、參數(shù)列表每個參數(shù)的類型、是否必填、含義。第二步是實現(xiàn)工具的執(zhí)行邏輯?？蚣芤蠊ぞ叩膱?zhí)行函數(shù)接收一個參數(shù)字典返回一個字符串或結(jié)構(gòu)化結(jié)果。這里有個設(shè)計細(xì)節(jié)值得注意執(zhí)行函數(shù)的返回值會被框架統(tǒng)一序列化后塞回對話上下文所以你的返回值最好是模型能理解的格式而不是一堆二進(jìn)制數(shù)據(jù)。第三步是注冊。注冊的方式通常有兩種裝飾器注冊和顯式注冊。裝飾器注冊寫起來更簡潔適合工具數(shù)量少的場景顯式注冊更靈活適合需要動態(tài)決定注冊哪些工具的場景。# 裝飾器注冊的典型寫法偽代碼 tool(namequery_logistics, description根據(jù)快遞單號查詢物流信息) def query_logistics(tracking_number: str) - str: # 實際調(diào)用物流 API result call_logistics_api(tracking_number) return format_result(result)3.2 工具描述的質(zhì)量直接決定調(diào)用準(zhǔn)確率這是我在實操中體會最深的一點。很多人寫工具描述很隨意寫個查詢天氣就完事了結(jié)果模型經(jīng)常在不需要的時候調(diào)用它或者調(diào)用時傳錯參數(shù)。工具描述本質(zhì)上是給模型看的使用說明書寫得越清楚模型調(diào)用越準(zhǔn)確。我總結(jié)了幾條寫工具描述的經(jīng)驗功能說明要包含什么時候用和什么時候不用。比如當(dāng)用戶詢問實時天氣時使用此工具如果用戶只是閑聊天氣話題不要調(diào)用。參數(shù)說明要給出示例值。模型看到示例值后對參數(shù)格式的理解會準(zhǔn)確很多。工具名稱用動詞開頭保持唯一性。避免出現(xiàn)兩個功能相似、名稱也相似的工具模型會混淆。3.3 工具執(zhí)行的安全邊界工具執(zhí)行是 Agent 與外部世界交互的窗口也是風(fēng)險最集中的地方。這個框架在工具執(zhí)行層做了幾道防線我覺得設(shè)計得挺合理。第一道是參數(shù)校驗?？蚣軙鶕?jù)工具定義中的參數(shù)類型對模型輸出的參數(shù)做類型檢查。如果模型輸出了一個字符串但工具定義要求整數(shù)框架會在執(zhí)行前攔截并返回錯誤信息給模型讓模型重新生成。第二道是超時控制。每個工具執(zhí)行都有超時限制防止某個工具卡死導(dǎo)致整個 Agent 流程掛起。超時時間可以全局配置也可以針對單個工具單獨設(shè)置。第三道是異常隔離。工具執(zhí)行過程中拋出的異常會被框架捕獲轉(zhuǎn)換成模型能理解的錯誤信息而不是直接讓整個流程崩潰。這一點很重要——模型收到錯誤信息后往往能自己調(diào)整策略重試。注意事項如果你要添加的工具涉及敏感操作比如寫數(shù)據(jù)庫、發(fā)請求到外部系統(tǒng)建議在工具實現(xiàn)內(nèi)部再加一層權(quán)限校驗不要完全依賴框架層面的防護(hù)?？蚣艿男ｒ炇峭ㄓ玫臉I(yè)務(wù)層面的安全需要你自己兜底。4. 執(zhí)行器與調(diào)度插件化的發(fā)動機4.1 執(zhí)行器的職責(zé)邊界執(zhí)行器是框架里最容易被忽視、但設(shè)計難度最高的部分。它的職責(zé)是接收規(guī)劃器輸出的執(zhí)行計劃按順序或并行地調(diào)用工具處理執(zhí)行過程中的各種異常最后把結(jié)果匯總返回。為什么說它設(shè)計難度高因為執(zhí)行器要處理的情況太多了工具有依賴關(guān)系怎么辦某個工具執(zhí)行失敗了要不要重試多個工具可以并行執(zhí)行時怎么調(diào)度執(zhí)行時間過長怎么中斷這些問題沒有標(biāo)準(zhǔn)答案不同的業(yè)務(wù)場景需要不同的策略。這個框架的做法是把執(zhí)行器抽象成一個接口默認(rèn)提供一個通用實現(xiàn)同時允許你替換成自己的實現(xiàn)。默認(rèn)實現(xiàn)覆蓋了最常見的場景——順序執(zhí)行、失敗重試、超時中斷。如果你的場景比較特殊比如需要分布式執(zhí)行那就自己實現(xiàn)一個執(zhí)行器。4.2 順序執(zhí)行與并行執(zhí)行的取舍默認(rèn)執(zhí)行器采用的是順序執(zhí)行策略也就是一個工具執(zhí)行完再執(zhí)行下一個。這個選擇乍看保守但仔細(xì)想想是合理的。順序執(zhí)行的最大好處是上下文一致性有保障。每個工具執(zhí)行完后結(jié)果會立即更新到上下文中下一個工具執(zhí)行時能看到最新的上下文。如果改成并行執(zhí)行多個工具同時讀寫上下文就需要處理并發(fā)一致性問題復(fù)雜度會上升一個量級。但順序執(zhí)行也有明顯的短板如果兩個工具之間沒有依賴關(guān)系順序執(zhí)行就是浪費時間。比如同時查天氣和查匯率這兩個操作完全可以并行。所以框架在執(zhí)行器層面預(yù)留了并行執(zhí)行的擴展點你可以根據(jù)工具之間的依賴關(guān)系動態(tài)決定哪些工具可以并行。我實測下來對于大多數(shù)對話式 Agent 場景順序執(zhí)行已經(jīng)夠用了。真正需要并行執(zhí)行的往往是那種批量處理類的任務(wù)比如同時查詢十個城市的天氣。這種場景下與其在 Agent 層面做并行不如把批量查詢封裝成一個工具在工具內(nèi)部做并行。4.3 重試策略的設(shè)計細(xì)節(jié)工具執(zhí)行失敗是常態(tài)尤其是調(diào)用外部 API 的時候。框架的默認(rèn)重試策略是失敗后重試兩次每次間隔一秒。這個策略對大多數(shù)場景夠用但有幾個細(xì)節(jié)值得注意。首先不是所有失敗都值得重試。如果失敗原因是參數(shù)錯誤重試多少次都沒用反而浪費時間和 token?？蚣艿淖龇ㄊ菂^(qū)分錯誤類型網(wǎng)絡(luò)超時類的錯誤會重試參數(shù)校驗類的錯誤直接返回給模型。其次重試次數(shù)不是越多越好。重試次數(shù)太多會導(dǎo)致整個流程響應(yīng)時間過長用戶體驗變差。我一般把重試次數(shù)控制在兩次以內(nèi)超過兩次還失敗就讓模型換個思路。最后重試時要考慮冪等性。如果工具的操作不是冪等的比如下單這種操作重試可能會導(dǎo)致重復(fù)下單。這種工具應(yīng)該在實現(xiàn)內(nèi)部做好冪等控制而不是依賴框架的重試機制。5. 記憶系統(tǒng)插件化里的隱形功臣5.1 短期記憶與長期記憶的分工記憶系統(tǒng)是 Agent 框架里最容易被低估的模塊。很多人覺得記憶就是把對話歷史存起來但實際上記憶系統(tǒng)的設(shè)計直接決定了 Agent 能不能處理長對話、能不能記住用戶偏好、能不能從歷史經(jīng)驗中學(xué)習(xí)。這個框架把記憶分成了短期記憶和長期記憶兩層。短期記憶存的是當(dāng)前對話的上下文通常有長度限制超出限制后會做截斷或摘要。長期記憶存的是跨對話的信息比如用戶的偏好、歷史任務(wù)的結(jié)果通常存在外部存儲里。兩層記憶的分工很明確短期記憶保證當(dāng)前對話的連貫性長期記憶保證 Agent 的個性和經(jīng)驗積累。這種分層設(shè)計的好處是你可以針對不同的記憶層采用不同的存儲策略和淘汰策略。5.2 記憶的寫入與檢索策略記憶系統(tǒng)最難的不是存而是什么時候存、存什么、怎么取。先說寫入。不是所有對話內(nèi)容都值得存入長期記憶。如果每句話都存長期記憶很快就會被噪音淹沒?？蚣艿淖龇ㄊ翘峁┮粋€可配置的寫入策略你可以選擇每輪對話都寫入、只在任務(wù)完成后寫入或者由模型判斷是否值得寫入。再說檢索。當(dāng) Agent 需要用到長期記憶時怎么從海量記憶中找出相關(guān)的那幾條最簡單的做法是按時間倒序取最近幾條但這種方式在記憶量大時效果很差。更好的做法是用向量檢索把記憶轉(zhuǎn)成向量存起來檢索時用語義相似度匹配。這個框架默認(rèn)提供的是基于關(guān)鍵詞的簡單檢索但預(yù)留了向量檢索的擴展接口。如果你用的是支持向量檢索的存儲后端只需要實現(xiàn)對應(yīng)的 Memory 接口即可。5.3 記憶壓縮長對話的必修課長對話場景下上下文長度是個硬約束。模型的上下文窗口就那么大對話輪次一多早期的內(nèi)容就會被擠出去。這時候就需要記憶壓縮?？蚣芴峁┝藥追N壓縮策略我比較常用的是摘要壓縮當(dāng)對話輪次超過閾值時把最早的幾輪對話交給模型做摘要用摘要替換原始對話。這樣既保留了關(guān)鍵信息又大幅縮短了上下文長度。實操心得摘要壓縮的提示詞很關(guān)鍵。我試過幾種寫法最后發(fā)現(xiàn)效果最好的是讓模型提取對話中的事實性信息和用戶偏好忽略寒暄和重復(fù)內(nèi)容。這樣壓縮后的摘要信息密度高后續(xù)對話中模型能準(zhǔn)確回憶起關(guān)鍵信息。6. 規(guī)劃器插件化的大腦6.1 ReAct 與 Plan-and-Execute 的適用場景規(guī)劃器決定了 Agent 怎么思考。這個框架內(nèi)置了兩種規(guī)劃策略ReAct 和 Plan-and-Execute。ReAct 的思路是邊想邊做模型先輸出一個思考然后決定調(diào)用哪個工具拿到結(jié)果后再思考下一步。這種方式靈活適合步驟不確定的任務(wù)但缺點是容易走一步看一步缺乏全局規(guī)劃。Plan-and-Execute 的思路是先規(guī)劃再執(zhí)行模型先制定一個完整的執(zhí)行計劃然后按計劃逐步執(zhí)行。這種方式適合步驟明確的任務(wù)執(zhí)行效率高但缺點是計劃一旦制定就不容易調(diào)整遇到意外情況可能卡住。我的經(jīng)驗是任務(wù)步驟少于三步、且步驟之間有依賴關(guān)系時用 ReAct任務(wù)步驟多、但步驟相對獨立時用 Plan-and-Execute。當(dāng)然也可以把兩者結(jié)合先用 Plan-and-Execute 制定大框架每個步驟內(nèi)部用 ReAct 靈活處理。6.2 規(guī)劃器的可替換性設(shè)計規(guī)劃器的插件化體現(xiàn)在它是一個獨立的組件通過標(biāo)準(zhǔn)接口與執(zhí)行器通信。規(guī)劃器輸出的是一個執(zhí)行計劃執(zhí)行器不關(guān)心這個計劃是怎么來的只負(fù)責(zé)執(zhí)行。這種設(shè)計的好處是你可以實現(xiàn)自己的規(guī)劃器。比如你想用某個特定的大模型做規(guī)劃或者你想實現(xiàn)一種全新的規(guī)劃策略比如基于樹搜索的規(guī)劃只需要實現(xiàn)規(guī)劃器接口即可執(zhí)行器和工具層完全不用改。我試過替換默認(rèn)規(guī)劃器實現(xiàn)了一個帶反思的規(guī)劃器每次執(zhí)行完一個步驟后讓模型反思一下當(dāng)前進(jìn)展是否符合預(yù)期如果不符合就重新規(guī)劃。這個規(guī)劃器在復(fù)雜任務(wù)上的表現(xiàn)比默認(rèn)的好不少但代價是 token 消耗增加了大約 40%。6.3 規(guī)劃器的提示詞工程規(guī)劃器的效果很大程度上取決于提示詞的質(zhì)量?？蚣苣J(rèn)的規(guī)劃器提示詞寫得比較通用但在特定場景下你需要針對性地調(diào)整。我總結(jié)了幾條規(guī)劃器提示詞的調(diào)整經(jīng)驗明確輸出格式。規(guī)劃器的輸出需要被程序解析所以格式必須嚴(yán)格。我一般要求模型輸出 JSON 格式的計劃每個步驟包含步驟描述和所需工具兩個字段。限制步驟數(shù)量。不加限制的話模型可能會規(guī)劃出十幾步的計劃其中很多步驟是冗余的。我一般限制在五步以內(nèi)。提供工具清單。規(guī)劃器需要知道有哪些工具可用才能制定出可執(zhí)行的計劃。把工具清單和工具描述一起放進(jìn)提示詞里規(guī)劃準(zhǔn)確率會明顯提升。7. 實操從零搭一個帶自定義插件的 Agent7.1 環(huán)境準(zhǔn)備與依賴安裝前面講的都是設(shè)計層面的東西這一節(jié)我?guī)阕咭槐橥暾膶嵅倭鞒獭＜僭O(shè)我們要搭一個個人助理 Agent具備三個能力查天氣、記筆記、查筆記。環(huán)境準(zhǔn)備比較簡單核心依賴就是框架本身和它依賴的大模型 SDK。我建議用虛擬環(huán)境隔離依賴避免和系統(tǒng)里的其他包沖突。# 創(chuàng)建虛擬環(huán)境 python -m venv agent_env source agent_env/bin/activate # 安裝框架和模型 SDK pip install agent-framework model-sdk安裝完成后先跑一個最小示例驗證環(huán)境是否正常。最小示例通常就是讓 Agent 回答一個簡單問題不涉及工具調(diào)用。如果這一步能跑通說明基礎(chǔ)環(huán)境沒問題。7.2 定義并注冊三個自定義工具接下來定義三個工具。查天氣工具調(diào)用外部天氣 API記筆記工具把內(nèi)容寫入本地文件查筆記工具從本地文件讀取內(nèi)容。# 查天氣工具 tool(nameget_weather, description查詢指定城市的實時天氣。當(dāng)用戶詢問天氣時使用。) def get_weather(city: str) - str: # 調(diào)用天氣 API返回格式化后的天氣信息 data weather_api.query(city) return f{city}當(dāng)前天氣{data[condition]}溫度{data[temp]}℃ # 記筆記工具 tool(namesave_note, description保存一條筆記。當(dāng)用戶要求記錄信息時使用。) def save_note(content: str) - str: with open(notes.txt, a, encodingutf-8) as f: f.write(content \n) return 筆記已保存 # 查筆記工具 tool(namesearch_notes, description搜索已保存的筆記。當(dāng)用戶詢問之前記錄的信息時使用。) def search_notes(keyword: str) - str: with open(notes.txt, r, encodingutf-8) as f: lines f.readlines() matched [l for l in lines if keyword in l] return \n.join(matched) if matched else 沒有找到相關(guān)筆記三個工具定義完后框架會自動把它們注冊到工具注冊表中。這里有個細(xì)節(jié)裝飾器的執(zhí)行順序會影響注冊順序但一般不影響功能因為框架在路由時會根據(jù)工具名稱精確匹配。7.3 配置記憶后端與規(guī)劃器工具定義好后接下來配置記憶后端和規(guī)劃器。開發(fā)階段我用內(nèi)存做記憶存儲規(guī)劃器用默認(rèn)的 ReAct。# 初始化 Agent agent Agent( modelyour-model-name, memoryInMemoryMemory(max_turns20), # 保留最近20輪對話 plannerReActPlanner(), executorSequentialExecutor(max_retries2, timeout30) )這里的參數(shù)選擇有講究。max_turns20是我實測下來比較平衡的值太小了容易丟失上下文太大了會拖慢響應(yīng)速度。max_retries2和timeout30也是類似都是根據(jù)實際使用體驗調(diào)出來的。7.4 跑通第一個多輪任務(wù)配置完成后跑一個多輪任務(wù)測試一下。我設(shè)計的測試場景是用戶幫我查一下上海的天氣Agent 調(diào)用查天氣工具返回天氣信息用戶幫我把今天的天氣記下來Agent 調(diào)用記筆記工具保存天氣信息用戶我之前記過哪些關(guān)于天氣的筆記Agent 調(diào)用查筆記工具返回匹配的筆記這個測試場景覆蓋了工具調(diào)用、上下文傳遞、記憶檢索三個核心能力。如果三步都能正確執(zhí)行說明 Agent 的基本功能已經(jīng)跑通了。我實測下來這個流程在默認(rèn)配置下能跑通但第三步偶爾會失敗——模型有時候會忘記之前查到的天氣信息導(dǎo)致記筆記時內(nèi)容不完整。解決辦法是在記筆記工具的提示詞里明確要求從對話歷史中提取天氣信息或者在規(guī)劃器層面增加一步確認(rèn)信息完整性的檢查。8. 常見問題與排查技巧實錄8.1 工具調(diào)用失敗的高頻原因在實操過程中工具調(diào)用失敗是最常見的問題。我把遇到過的原因整理成了一張速查表問題現(xiàn)象可能原因排查方法解決方案模型不調(diào)用工具工具描述不清晰檢查工具描述是否說明了使用場景補充什么時候用的說明調(diào)用時參數(shù)錯誤參數(shù)定義不明確檢查參數(shù)類型和示例值在參數(shù)描述中加示例工具執(zhí)行超時外部 API 響應(yīng)慢查看工具執(zhí)行日志增加超時時間或加重試返回結(jié)果模型看不懂返回格式不規(guī)范檢查返回值是否結(jié)構(gòu)化統(tǒng)一返回 JSON 字符串多輪對話后工具失效上下文被截斷檢查記憶配置增加記憶輪次或做摘要壓縮這張表里的每一條都是我實際踩過的坑。其中模型不調(diào)用工具和調(diào)用時參數(shù)錯誤這兩類問題占了所有問題的七成以上而根源基本都是工具描述寫得不夠清楚。8.2 上下文丟失的排查思路上下文丟失是另一個高頻問題尤其是在長對話場景下。表現(xiàn)是Agent 在對話早期能正確使用某個信息但對話進(jìn)行到十幾輪后就忘記了這個信息。排查這個問題的思路是先確認(rèn)記憶配置是否合理再確認(rèn)上下文是否被意外截斷。框架一般會提供日志記錄每輪對話實際傳給模型的上下文內(nèi)容。把日志打出來看一眼就能知道是記憶沒存進(jìn)去還是存進(jìn)去了但沒被檢索出來。如果是記憶沒存進(jìn)去檢查寫入策略如果是存進(jìn)去了但沒檢索出來檢查檢索策略。我遇到過一次比較隱蔽的情況記憶存進(jìn)去了檢索也能檢索到但檢索到的記憶沒有被正確拼接到提示詞里。這種問題只能通過看日志發(fā)現(xiàn)。8.3 性能優(yōu)化的幾個實用技巧Agent 的性能瓶頸通常不在計算而在等待——等模型響應(yīng)、等工具執(zhí)行、等網(wǎng)絡(luò)傳輸。優(yōu)化性能的核心思路是減少等待。第一個技巧是緩存工具結(jié)果。對于查詢類的工具如果同樣的參數(shù)在短時間內(nèi)被多次調(diào)用可以直接返回緩存結(jié)果。我實測下來這個優(yōu)化能減少大約 30% 的工具調(diào)用耗時。第二個技巧是精簡提示詞。提示詞越長模型響應(yīng)越慢。把不必要的說明刪掉把工具描述寫精煉能明顯提升響應(yīng)速度。第三個技巧是并行執(zhí)行無依賴的工具。前面說過默認(rèn)執(zhí)行器是順序執(zhí)行的但如果你的場景里有大量無依賴的工具調(diào)用可以考慮替換成并行執(zhí)行器。注意事項并行執(zhí)行雖然快但會帶來上下文一致性問題。如果你的工具之間有隱式的依賴關(guān)系比如工具 B 依賴工具 A 寫入的數(shù)據(jù)千萬不要并行執(zhí)行。9. 插件化設(shè)計的邊界與取舍拆完這個框架我最大的感受是插件化不是越多越好而是要在靈活性和復(fù)雜度之間找到平衡點。這個框架把插件化做到了工具、執(zhí)行器、記憶、規(guī)劃器四個層面但并沒有把提示詞模板、日志系統(tǒng)這些也做成插件。為什么因為提示詞模板和日志系統(tǒng)的變化頻率低做成插件帶來的靈活性收益抵不過增加的抽象復(fù)雜度。這給了我一個重要的啟發(fā)判斷一個模塊該不該插件化關(guān)鍵看它的變化頻率和變化維度。變化頻率高、變化維度多的模塊值得插件化變化頻率低、變化維度單一的模塊硬編碼反而更清晰。另外插件化帶來的一個隱性成本是調(diào)試難度上升。當(dāng)出問題時你需要在多個插件之間來回排查而不是在一個文件里從上往下讀。所以我在實際項目中會盡量控制插件的數(shù)量只在真正需要靈活替換的地方做插件化。這個框架的插件化設(shè)計我覺得最值得借鑒的一點是每個插件接口都定義得非常窄。工具接口只要求實現(xiàn)執(zhí)行方法記憶接口只要求實現(xiàn)存和取方法。接口越窄實現(xiàn)起來越簡單替換成本越低。反觀有些框架插件接口定義得又寬又復(fù)雜實現(xiàn)一個插件要寫幾百行代碼這種插件化就失去了意義。最后分享一個我在拆源碼時用的小技巧先看接口定義文件再看默認(rèn)實現(xiàn)最后看測試用例。接口定義告訴你能做什么默認(rèn)實現(xiàn)告訴你怎么做測試用例告訴你怎么用。按這個順序看理解一個陌生框架的速度會快很多。