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