多智能體系統(tǒng)聽起來很復(fù)雜但真正上手之后核心就一句話用一個主控角色把任務(wù)拆開分給幾個專門負(fù)責(zé)不同工作的 Agent最后再把結(jié)果收回來。這篇文章要拆解的就是怎么從零搭建一條 Hermes Agent 多智能體鏈路用 1 個主控調(diào)度 3 個 Agent底層模型接 Qwen 通義千問。適合正在做 Agent 開發(fā)、想從單 Agent 往多 Agent 協(xié)作過渡的讀者也適合那些已經(jīng)跑通 Demo 但不知道生產(chǎn)環(huán)境里怎么配置主控、任務(wù)隊列和失敗重試的人。這里要提前說清楚Hermes Agent 的配置項在不同版本里會有差異文章里給的配置結(jié)構(gòu)是通用示例。你落地的時候先把版本和 API 方式確認(rèn)好再照著調(diào)。1. 先搞清楚它解決的是多 Agent 協(xié)作不是替代模型很多人在學(xué) Agent 開發(fā)時第一個念頭是“哪個框架更強大”。但多智能體系統(tǒng)真正的價值不是讓單個模型推理能力變強而是把任務(wù)的流程控制權(quán)從代碼里拿出來交給一個主控 Agent 去編排。Hermes Agent 這類框架解決的核心問題是多個角色之間怎么通信、任務(wù)怎么分發(fā)、結(jié)果怎么匯總。1.1 主控調(diào)度不是“更聰明的模型”主控調(diào)度器一般不需要比工作 Agent 更強的模型能力它更像一個項目管理者。它的職責(zé)是理解用戶輸入把目標(biāo)拆成多個子任務(wù)按順序或并行分發(fā)給對應(yīng) Agent最后把返回結(jié)果合并成最終答復(fù)。工作 Agent 則更專注有的負(fù)責(zé)檢索資料有的負(fù)責(zé)分析文本有的負(fù)責(zé)生成內(nèi)容。這樣做的好處是每個 Agent 的提示詞、工具和上下文都可以單獨控制不會因為任務(wù)類型混雜而互相干擾。實測中的體會是主控模型的選擇會影響任務(wù)拆分的質(zhì)量。如果主控模型本身理解能力不夠就會把任務(wù)拆錯導(dǎo)致下游 Agent 拿到錯誤指令。所以預(yù)算允許時主控盡量用能力更強一點的模型工作 Agent 可以根據(jù)任務(wù)難度搭配不同檔位。順帶說一句多智能體系統(tǒng)的交互模式并不只有“主控派單”這一種。業(yè)內(nèi)常見的還有流水線模式、協(xié)作模式和辯論模式。流水線模式適合步驟固定、前一步輸出就是下一步輸入的場景協(xié)作模式適合多個 Agent 地位平等、共同完成一個目標(biāo)的場景辯論模式適合需要多角度審視的決策任務(wù)。本文用的“1 個主控調(diào)度 3 個 Agent”屬于主控派單模式也是上手最容易、問題最好定位的一種先把這種跑明白再研究其他模式會更穩(wěn)。1.2 為什么這里選 Qwen 通義千問選 Qwen 作為底層模型主要有幾個原因。第一Qwen 有 API 和本地部署兩條路線開發(fā)階段用 API 最快生產(chǎn)環(huán)境如果對數(shù)據(jù)有要求可以再切本地模型。第二Qwen 的通用能力、中文理解能力和工具調(diào)用能力都比較均衡在 Agent 場景下不容易出現(xiàn)指令理解偏差。第三它在很多框架里已經(jīng)有現(xiàn)成的接入方式配置量不大。如果走 API 路線一般就是申請 Key然后在 Agent 配置里把 provider 指向 Qwen 對應(yīng)的服務(wù)地址如果走本地路線需要先確認(rèn)顯存和內(nèi)存。我的建議是第一次學(xué)習(xí)用 API 最穩(wěn)等流程跑通了再考慮本地化不要一開始就卡在模型部署上。1.3 三個 Agent 的角色怎么分標(biāo)題里的“3 個 Agent”實際落地時角色可以根據(jù)業(yè)務(wù)改但一個比較穩(wěn)妥的起步組合是檢索 Agent負(fù)責(zé)查知識庫、查外部資料把原始信息帶回來。分析 Agent負(fù)責(zé)對檢索結(jié)果做結(jié)構(gòu)化處理比如總結(jié)、提取要點、對比差異。生成 Agent負(fù)責(zé)把最終結(jié)果整理成完整、可讀的回復(fù)。這個分法最大的好處是職責(zé)邊界清晰。主控只需要決定“哪個任務(wù)交給誰”不需要關(guān)心每個 Agent 內(nèi)部怎么實現(xiàn)。后面要加第 4 個、第 5 個 Agent 時也不會影響已經(jīng)跑通的鏈路。2. 環(huán)境準(zhǔn)備先跑通最小可用環(huán)境再談?wù){(diào)度多智能體系統(tǒng)出問題一半以上不是框架問題而是環(huán)境問題。所以安裝之前先把運行條件確認(rèn)一遍。2.1 本地環(huán)境需要什么Hermes Agent 如果走桌面端或本地服務(wù)方式系統(tǒng)層面一般支持 Windows、macOS 和 Linux。我用 Mac 和 Linux 都跑過Windows 上如果用 WSL 或原生終端也能跑但要注意路徑分隔符和權(quán)限問題。依賴方面至少要準(zhǔn)備Python 環(huán)境建議用 3.10 以上很多 Agent 項目的新特性只在新版本里支持。Node.js 環(huán)境部分前端界面和工具包依賴它。一個可用的模型訪問憑據(jù)也就是 Qwen API Key或者本地模型的訪問地址。磁盤空間盡量留出 5GB 以上。如果還要裝本地模型那要按模型體積單獨評估。安裝前先檢查這三個命令能不能正常輸出版本信息python --version、node --version、git --version。任何一個報錯都先解決掉再往下走。2.2 安裝 Hermes Agent 與依賴安裝這類框架最常見的坑是依賴版本沖突。我的建議是新建一個獨立的虛擬環(huán)境不要直接裝到系統(tǒng) Python 里。這樣后面升級依賴、重裝環(huán)境都不會影響其他項目。安裝完成后先執(zhí)行一個最基礎(chǔ)的健康檢查比如查看版本號或幫助命令確認(rèn)主程序能正常啟動。注意如果工具在安裝或首次使用時提示需要登錄官網(wǎng)、注冊賬號這是正?，F(xiàn)象。很多 Agent 工具的第一道認(rèn)證不是模型 API Key而是工具平臺本身的賬號體系。不要急著跳過先看提示要的是工具平臺賬號還是模型服務(wù)賬號兩者通常不一樣。Mac 和 Linux 的主要差異在依賴安裝方式上。Linux 環(huán)境經(jīng)常缺系統(tǒng)級編譯工具遇到本地包編譯報錯時先安裝 build-essential 這類基礎(chǔ)工具M(jìn)ac 上則要注意是不是用了 Homebrew 的 Python 和系統(tǒng)自帶 Python 混在一起容易把依賴裝亂。如果不想處理這些直接先跑官方推薦的安裝腳本或容器方式能省不少時間。CLI 交互界面里常見的返回上一級、回到主頁面這類命令不同版本差異很大。不要靠記憶硬敲啟動后先看 help 命令列出來的選項每個版本的快捷鍵和子命令命名都不一定一樣。2.3 確認(rèn) Qwen 模型可以正常響應(yīng)在接入多智能體調(diào)度之前先單獨驗證模型能不能通。最直接的方法是寫一個最小請求腳本調(diào)用一次 Qwen API傳入一段簡單文本確認(rèn)返回值結(jié)構(gòu)完整。這一步很重要。如果模型調(diào)用本身就不通后面配置主控和三個 Agent 時你會分不清報錯到底來自框架還是模型。實測時我一般先做一次 curl 或腳本調(diào)用確認(rèn)三件事API Key 是否有效。請求地址和模型名稱是否匹配。返回內(nèi)容里是否包含正常的結(jié)果字段。把這三點確認(rèn)好再進(jìn)入 Hermes Agent 配置排錯范圍會小很多。這里給一段類似的請求示例字段以你的服務(wù)商文檔為準(zhǔn)curl -X POST https://your-qwen-endpoint/v1/chat/completions \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { model: qwen-max, messages: [ {role: user, content: 你好請回復(fù)一句話確認(rèn)模型服務(wù)正常} ] }如果返回里有 choices 字段并且 message.content 是正常文本說明模型服務(wù)沒問題。接下來就可以放心配置 Hermes Agent。3. 配置主控與三個 Agent核心是職責(zé)和上下文的邊界多智能體配置和單 Agent 最大的區(qū)別是你要同時管理多個提示詞、多個模型參數(shù)、多個任務(wù)通道。如果所有 Agent 都共用同一套配置那多 Agent 架構(gòu)就失去了意義。3.1 配置文件里需要確認(rèn)哪些內(nèi)容一份典型的多 Agent 配置通常包含這幾塊主控 Agent模型、系統(tǒng)提示詞、最大迭代次數(shù)、任務(wù)拆分規(guī)則。工作 Agent各自獨立模型或共用模型、專屬系統(tǒng)提示詞、可調(diào)用工具。調(diào)度規(guī)則任務(wù)類型到 Agent 的映射關(guān)系。全局配置API Key、超時時間、日志目錄、輸出目錄。主控的 system prompt 是最重要的。它要讓主控知道自己不是直接回答問題的專家而是任務(wù)分發(fā)者。建議在提示詞里明確寫清楚“遇到任務(wù)時先判斷需要調(diào)用哪個 Agent不要自己越權(quán)完成所有工作”。3.2 一個主控加三個 Agent 的示例配置下面是一個通用結(jié)構(gòu)示例具體字段名需要按你安裝的版本調(diào)整但思路是通用的orchestrator: name: main_controller model: provider: qwen model_name: qwen-max system_prompt: | 你是整個多智能體系統(tǒng)的主控調(diào)度器。 請將用戶任務(wù)拆解為子任務(wù)并分配給對應(yīng)的 worker agent。 不要直接替 worker 完成全部工作。 workers: - name: retriever_agent model: provider: qwen model_name: qwen-plus system_prompt: | 你是資料檢索 Agent負(fù)責(zé)查找和返回原始資料。 返回結(jié)果時保留來源和關(guān)鍵段落。 - name: analyzer_agent model: provider: qwen model_name: qwen-plus system_prompt: | 你是分析 Agent負(fù)責(zé)對資料做總結(jié)、歸納和對比。 輸出必須結(jié)構(gòu)化使用要點列表。 - name: generator_agent model: provider: qwen model_name: qwen-max system_prompt: | 你是內(nèi)容生成 Agent負(fù)責(zé)把分析結(jié)果整理成最終回復(fù)。 語言要清晰、完整、可讀性強。 routing: - task_type: search target: retriever_agent - task_type: analyze target: analyzer_agent - task_type: generate target: generator_agent global: timeout_seconds: 120 max_iterations: 5 log_dir: ./logs output_dir: ./output這份配置里主控和生成 Agent 用了更強一點的模型檢索和分析用了低一檔的模型。這樣做的目的是控制成本同時保證關(guān)鍵環(huán)節(jié)的生成質(zhì)量。如果你的任務(wù)比較簡單全部用同一型號也可以但最好讓每個 Agent 的系統(tǒng)提示詞保持獨立。3.3 任務(wù)分發(fā)和上下文傳遞配置好之后還要想清楚任務(wù)是怎么流轉(zhuǎn)的。常見的方式有兩種順序流轉(zhuǎn)主控先調(diào)檢索 Agent拿回資料再調(diào)分析 Agent最后調(diào)生成 Agent。條件流轉(zhuǎn)主控根據(jù)用戶問題的類型直接決定調(diào)哪個 Agent可以跳步。這兩種方式在代碼實現(xiàn)上差別不大但主控提示詞和調(diào)度規(guī)則要寫清楚。順序流轉(zhuǎn)適合處理鏈路固定的任務(wù)比如“查資料、做分析、出報告”條件流轉(zhuǎn)適合開放式問題比如“用戶問天氣就直接回不用啟動檢索”。上下文傳遞是另一個容易踩坑的點。每個 Agent 的輸入不能把上一輪的完整對話全部塞進(jìn)去否則上下文會越來越長帶來兩個問題一是 token 消耗變大二是模型容易被無關(guān)信息干擾。建議只傳遞“當(dāng)前子任務(wù)的輸入 必要的中間結(jié)果摘要”并在主控里做結(jié)果壓縮。4. 從單任務(wù)驗證到批量任務(wù)先跑通再開并發(fā)配置完成后最忌諱直接跑一個復(fù)雜的真實任務(wù)。一定要先做最小驗證。4.1 先跑一條簡單任務(wù)我建議用一條邊界非常明顯的問題來測試?yán)纭罢埛治鲆幌逻@段文本的核心觀點輸出三段總結(jié)”。這個任務(wù)需要檢索、分析和生成三個環(huán)節(jié)但輸入很短方便定位問題。第一輪跑的時候重點看四件事主控是否成功啟動日志里能看到模型調(diào)用記錄。主控是否把任務(wù)分發(fā)給了正確的 Agent。每個 Agent 是否返回了內(nèi)容。最終輸出是否把三個環(huán)節(jié)的結(jié)果匯總起來。如果第一輪就報錯先不要調(diào)參數(shù)。去看日志里的完整報錯信息尤其是發(fā)生錯誤的環(huán)節(jié)。是多 Agent 配置沒加載還是模型調(diào)用失敗還是某個 Agent 的提示詞格式有問題。大部分問題在這一步就能定位。4.2 批量任務(wù)和并發(fā)控制單任務(wù)跑通后再考慮批量。批量任務(wù)的核心不是“一次能跑多少條”而是“跑掛之后能不能恢復(fù)”。所以批量前先確認(rèn)三個能力輸入列表是否支持從文件讀取。每條任務(wù)是否有獨立 ID 或獨立輸出文件。失敗任務(wù)是否會重試重試次數(shù)和間隔是否能配置。并發(fā)數(shù)不要一上來就拉滿。先開 2 到 3 個并發(fā)觀察資源占用和響應(yīng)時間再逐步往上加。很多框架默認(rèn)并發(fā)數(shù)看起來很高但實際受 API 限流和本地資源限制過高的并發(fā)只會讓失敗率上升。如果跑的是長任務(wù)建議給每條任務(wù)設(shè)置合理超時時間并在輸出目錄里保留日志。這樣即使任務(wù)失敗也能根據(jù)日志恢復(fù)而不是整套流程重新跑一遍。4.3 輸出結(jié)果怎么驗證輸出不是“有內(nèi)容”就算成功。多 Agent 系統(tǒng)里要驗證結(jié)果是否符合預(yù)期至少看三層。第一層完整性。最終回復(fù)是否包含所有必要部分有沒有因為某個 Agent 結(jié)果為空導(dǎo)致整體內(nèi)容缺失。第二層一致性。三個 Agent 的輸出是否在結(jié)論上互相矛盾特別是檢索結(jié)果和分析結(jié)果之間。第三層可重復(fù)性。同一輸入跑兩次結(jié)果是否有明顯波動。如果模型參數(shù)固定、輸入固定結(jié)果應(yīng)該相對穩(wěn)定。如果每次輸出差異很大說明提示詞約束不夠需要把輸出格式要求寫得更細(xì)。5. 常見故障和排查順序從日志到輸入再到參數(shù)多 Agent 系統(tǒng)故障排查最怕的就是憑感覺改參數(shù)。正確做法是固定一套排查順序一層層縮小范圍。5.1 API Key、模型名稱與網(wǎng)絡(luò)問題這一類問題通常在日志里會直接報 401、403、404 或超時。先確認(rèn)三件事API Key 有沒有復(fù)制完整有沒有空格或換行。模型名稱是不是服務(wù)商支持的準(zhǔn)確名稱比如 qwen-max、qwen-plus 這類寫法。網(wǎng)絡(luò)能不能正常訪問模型服務(wù)地址公司內(nèi)網(wǎng)或有防火墻時經(jīng)常在這里卡住。注意模型名稱寫錯是最常見的低級別錯誤。很多人在本地跑通了換到服務(wù)端時模型名沒改導(dǎo)致請求直接失敗。5.2 任務(wù)卡住、超時和“輸出死循環(huán)”任務(wù)卡住不要直接殺進(jìn)程。先看日志停在哪一步判斷是主控還在等 Agent還是某個 Agent 在等待模型返回。如果日志長時間沒有新內(nèi)容大概率是模型調(diào)用超時或者上下文過長導(dǎo)致響應(yīng)變慢。如果你在日志里看到類似 “the agent execution provider did not respond in time” 的報錯先不用懷疑框架壞了。這類提示本質(zhì)上就是執(zhí)行組件沒有按時返回常見原因包括模型服務(wù)端響應(yīng)慢、網(wǎng)絡(luò)超時、上下文太長、并發(fā)數(shù)超過了服務(wù)商限流。處理順序是先降低并發(fā)再縮短單次輸入最后適當(dāng)調(diào)大超時時間。三者都試過還沒解決再回頭查網(wǎng)絡(luò)穩(wěn)定性。搜索熱詞里常提到的“qwen 輸出死循環(huán)”本質(zhì)上是 Agent 在多次迭代中反復(fù)調(diào)用同一個工具或輸出同一段內(nèi)容。解決辦法有兩個方向一是限制最大迭代輪數(shù)比如全局配置里把 max_iterations 調(diào)小二是檢查系統(tǒng)提示詞是否給 Agent 留下了“重復(fù)操作”的空間。比如“如果分析失敗重試一次”這種指令在沒寫重試上限時就可能變成無限重試。5.3 資源占用和并發(fā)下的穩(wěn)定性批量跑任務(wù)時如果出現(xiàn)內(nèi)存飆升、響應(yīng)變慢、任務(wù)互相擠占資源就需要看資源占用。先用系統(tǒng)監(jiān)控工具查看 CPU、內(nèi)存、磁盤讀寫。如果內(nèi)存占用持續(xù)升高可能是中間結(jié)果沒有釋放或者是上下文對象沒有清理。此時先降低并發(fā)數(shù)再檢查日志輸出和臨時文件。低配置機(jī)器能跑通 Demo不代表能跑批量任務(wù)。我的建議是內(nèi)存小于 8GB 的環(huán)境把并發(fā)控制在 1 到 2內(nèi)存 16GB 以上再考慮開更高的并發(fā)。API 型任務(wù)還要考慮服務(wù)商側(cè)的限流不能只看本地資源。給一個大概的判斷表現(xiàn)象優(yōu)先排查次要排查請求返回 401/403API Key 是否正確賬號是否有權(quán)限請求超時網(wǎng)絡(luò)連通性模型上下文長度、服務(wù)商負(fù)載主控不派單主控提示詞是否誤配路由規(guī)則是否匹配任務(wù)類型Agent 返回為空該 Agent 的輸入內(nèi)容模型是否被安全策略攔截批量任務(wù)部分失敗單條任務(wù)輸入格式并發(fā)數(shù)和限流6. 從 Demo 到生產(chǎn)落地知識庫、MCP 和 Agent 安全邊界把多 Agent 系統(tǒng)跑通之后下一步通常就是往生產(chǎn)環(huán)境靠。這里有幾個方向值得關(guān)注。6.1 給 Agent 外掛知識庫搜索熱詞里反復(fù)出現(xiàn)“hermes agent 外掛知識庫”說明這是很多人剛跑通 Demo 后就遇到的問題。外掛知識庫的本質(zhì)是把檢索環(huán)節(jié)從“讓模型憑記憶回答”變成“先查資料再回答”。常見做法是將文檔切片后存入向量數(shù)據(jù)庫比如 Milvus檢索 Agent 根據(jù)用戶問題做向量檢索再把命中片段交給分析 Agent。這樣做的好處是回答有依據(jù)缺點是系統(tǒng)復(fù)雜度明顯上升。落地時建議先確保持一種清晰的文檔切片和檢索召回策略再逐步加。向量數(shù)據(jù)庫不是必須的。如果知識庫文檔很少直接用關(guān)鍵詞檢索也能頂一段時間。我的建議是文檔量少、業(yè)務(wù)簡單時不要為了用 Milvus 而引入 Milvus先跑通鏈路最重要。6.2 MCP 與 Skill 的區(qū)別很多 Agent 框架現(xiàn)在都支持 MCP 和 Skill。MCP 是模型上下文協(xié)議解決的是 Agent 與外部工具連接的標(biāo)準(zhǔn)問題比如通過 MCP 讓 Agent 調(diào)用數(shù)據(jù)庫、訪問 API、讀寫文件。Skill 更像一個內(nèi)置的專用技能包通常封裝了提示詞、工具調(diào)用流程和參數(shù)模板。兩者的區(qū)別我的理解是MCP 偏協(xié)議層解決“能不能接”的問題Skill 偏應(yīng)用層解決“接上后怎么用得更好”的問題。實際使用時一個 Skill 內(nèi)部可能調(diào)用了多個 MCP 工具。所以不要把兩者對立起來而是看你的 Agent 需要什么能力再決定從哪一層擴(kuò)展。6.3 Agent 安全邊界多 Agent 系統(tǒng)在安全上比單 Agent 更需要注意因為任務(wù)會經(jīng)過多個角色風(fēng)險面更大。至少要做四件事每個 Agent 的權(quán)限最小化檢索 Agent 不能同時擁有寫文件權(quán)限。對 Agent 可調(diào)用的工具做白名單不要開放任意命令執(zhí)行。日志脫敏避免 API Key 和用戶敏感信息落到普通日志里。外層再加一道請求審核確認(rèn)用戶輸入不會被用于惡意指令注入。這些點看起來不起眼但在生產(chǎn)環(huán)境里是最容易出問題的。多智能體系統(tǒng)一旦上線被調(diào)用的就不只是模型能力還有你暴露給 Agent 的數(shù)據(jù)庫、文件系統(tǒng)和外部服務(wù)。權(quán)限邊界不控制好出事的概率會大幅上升。最后再說一點。這個方案真正落地時最該盯住的不是功能列表而是輸入格式、資源占用和失敗重試。先把單任務(wù)跑穩(wěn)再開并發(fā)先驗證模型連通性再配置復(fù)雜調(diào)度先把輸出目錄和日志規(guī)劃好再談知識庫和 MCP。多智能體系統(tǒng)的復(fù)雜度是一點點堆出來的排查思路也得按層來跳步只會讓問題更難定位。