1. 從agency-agents這個名字說起一個多智能體協作框架的定位第一次看到agency-agents這個項目名我的直覺是這大概率是一個圍繞代理agent和代理機構agency概念做文章的多智能體協作框架。拆開來看agency在英文里既有代理機構的意思也有能動性、自主行動能力的含義而agents則是復數形式的代理/智能體。把這兩個詞拼在一起指向的應該是一套讓多個智能體像一家機構里的不同角色那樣協同工作的系統。這個判斷不是憑空來的。近兩年圍繞大模型的應用開發(fā)已經從單次問答快速演進到讓模型自己規(guī)劃、調用工具、分步執(zhí)行任務的階段。單個智能體再強遇到復雜任務也會力不從心——上下文窗口有限、單點能力有短板、無法并行處理子任務。于是多智能體協作成了很自然的方向把一個大任務拆給多個各有分工的智能體讓它們像團隊一樣配合。agency-agents 這個名字恰好踩在這個方向上。需要先說明的是我拿到的項目正文、關鍵詞和摘要描述都是空的所以這篇內容不是對某個具體代碼倉庫的逐行解讀而是基于標題本身、結合多智能體協作這個領域的通用實踐做一次完整的拆解和落地推演。我會把如果我要從零搭一個叫 agency-agents 的多智能體協作框架我會怎么設計、怎么踩坑、怎么調優(yōu)這件事講透。對于正在做類似事情的人這篇可以直接當設計參考對于剛接觸多智能體的讀者也能借此建立一套完整的認知框架。適合讀這篇的人大概有三類一是想給自己的產品加上多角色協作能力的開發(fā)者二是被單個智能體越做越亂困擾、想找結構化方案的人三是對 agent 編排orchestration感興趣、想了解工程落地細節(jié)的技術負責人。下面我會從核心概念、架構設計、角色分工、通信機制、實操步驟、避坑經驗幾個層面展開盡量把每個為什么都講清楚。2. 多智能體協作到底解決了單智能體的哪些死結2.1 單智能體的三個典型瓶頸在動手設計 agency-agents 之前得先想明白一件事為什么非要多個智能體單個大模型加幾個工具調用很多時候也能跑通任務。我實際做過不少單智能體的項目總結下來它有三個繞不過去的瓶頸。第一個是上下文污染。當一個智能體既要理解用戶意圖、又要規(guī)劃步驟、還要執(zhí)行具體操作、最后還要檢查結果時所有這些信息都堆在同一個上下文里。任務一復雜上下文里就混進了大量中間過程的噪音模型很容易忘記最初的目標或者在執(zhí)行細節(jié)時被之前的規(guī)劃思路帶偏。這就像讓一個人同時當項目經理、程序員和測試腦子里的角色切換會互相干擾。第二個是能力無法專精。單智能體的系統提示詞system prompt往往要兼顧多種能力結果就是每種能力都寫得比較泛。你很難讓同一個提示詞既擅長嚴謹的代碼審查又擅長天馬行空的創(chuàng)意發(fā)散。提示詞越長越全模型對每一條的遵循度反而越低這是很常見的現象。第三個是無法并行與隔離。有些子任務之間沒有依賴關系本可以同時做但單智能體只能串行。更麻煩的是一個子任務失敗會污染整個上下文導致后續(xù)步驟全部受影響缺乏故障隔離。2.2 多智能體帶來的四個結構性收益agency-agents 這類框架的價值正是針對上面三個瓶頸給出的結構性解法。我把它歸納成四點收益。職責分離帶來的上下文純凈。每個智能體只關心自己那一段規(guī)劃者只管拆解任務執(zhí)行者只管干活審查者只管挑毛病。各自的上下文里只有和自己相關的信息噪音大幅減少遵循度自然提升。角色專精帶來的提示詞優(yōu)化空間。因為每個智能體只干一件事它的系統提示詞可以寫得非常聚焦、非常具體甚至可以為每個角色單獨調參、單獨選模型。便宜的模型干簡單的活貴的模型干關鍵的活成本也能優(yōu)化。并行執(zhí)行帶來的效率提升。沒有依賴關系的子任務可以分發(fā)給多個執(zhí)行智能體同時處理最后匯總。這在批量處理類任務上收益非常明顯。故障隔離帶來的魯棒性。某個執(zhí)行智能體跑掛了不會直接毀掉整個流程編排層可以重試、可以換一個智能體、可以把失敗信息交給審查者處理。這種隔離是單智能體很難做到的。理解了這四點后面所有的架構設計其實都是在回答一個問題怎么把職責分離、角色專精、并行執(zhí)行、故障隔離這四件事在工程上落地。3. agency-agents 的架構骨架編排層、角色層與共享狀態(tài)3.1 三層結構的分工如果讓我來設計 agency-agents我會把它拆成三層編排層Orchestration Layer、角色層Agent Layer、共享狀態(tài)層Shared State Layer。這三層各司其職邊界清晰是整個框架能穩(wěn)定運行的基礎。編排層是大腦負責接收用戶任務、決定用哪些角色、按什么順序調度、處理失敗重試、判斷任務是否完成。它本身通常也是一個智能體或者是一段確定性的調度邏輯。我的經驗是能用確定性代碼寫的調度邏輯就不要交給模型去決策。比如先規(guī)劃再執(zhí)行再審查這種固定流程用代碼寫死比讓模型自由發(fā)揮穩(wěn)定得多。模型只應該用在真正需要判斷力的地方比如任務拆解、結果評估。角色層是干活的團隊每個角色是一個獨立的智能體實例有自己的系統提示詞、工具集、模型配置。角色之間不直接互相調用而是通過編排層或共享狀態(tài)來交換信息。這一點很關鍵——如果讓角色之間隨意互相調用很快就會變成一團亂麻調試時根本追不清調用鏈。共享狀態(tài)層是公共白板存放任務描述、中間產物、各角色的輸出、執(zhí)行日志等。所有角色讀寫這塊共享區(qū)域而不是把信息塞在消息里傳來傳去。這樣做的好處是信息有單一可信來源任何角色都能看到全局進展也方便做持久化和斷點恢復。3.2 為什么用共享狀態(tài)而不是純消息傳遞這里我要專門解釋一下為什么傾向共享狀態(tài)而不是純消息傳遞因為這是很多人在設計多智能體系統時容易走偏的地方。純消息傳遞的模式下智能體 A 把結果發(fā)給 BB 處理完發(fā)給 C。聽起來很清晰但實際跑起來問題很多消息格式要嚴格約定一旦某個環(huán)節(jié)格式不對整條鏈就斷了中間結果無法復用如果 D 也需要 A 的輸出就得讓 A 再發(fā)一遍或者層層轉發(fā)調試時你只能看到一條條消息很難還原當前全局狀態(tài)到底是什么。共享狀態(tài)模式則像一塊大家都能讀寫的白板。A 把結果寫到白板的某個區(qū)域B、C、D 誰需要誰去讀。信息只寫一次多處復用。調試時直接看白板快照全局一目了然。當然共享狀態(tài)也有代價——需要處理并發(fā)寫入的沖突需要設計好狀態(tài)的結構。但對于 agency-agents 這種多角色協作場景共享狀態(tài)的收益遠大于成本。我通常會把共享狀態(tài)設計成一個結構化的對象大致包含這幾個字段任務目標、任務拆解后的子任務列表、每個子任務的狀態(tài)待處理/進行中/已完成/失敗、每個子任務的產出、全局的執(zhí)行日志、以及一個當前階段標記。這個結構用 JSON 或類似格式序列化方便持久化和恢復。3.3 編排層的調度策略選擇編排層的調度策略直接決定了整個系統的行為模式。常見的有三種順序流水線、動態(tài)路由、混合模式。順序流水線最簡單規(guī)劃者拆任務執(zhí)行者逐個做審查者最后檢查。適合流程固定的場景比如寫一份報告這種線性任務。優(yōu)點是穩(wěn)定可預測缺點是靈活性差。動態(tài)路由更靈活編排層根據當前狀態(tài)動態(tài)決定下一步該叫哪個角色。比如執(zhí)行者報告某個子任務失敗編排層可以決定是重試、是換個角色做、還是叫審查者介入。這種模式適合任務結構不確定的場景但調度邏輯復雜容易出 bug?；旌夏Ｊ绞俏易钔扑]的主干流程用順序流水線保證穩(wěn)定在關鍵決策點引入動態(tài)路由處理異常。比如正常情況按規(guī)劃→執(zhí)行→審查走但執(zhí)行階段如果某個子任務連續(xù)失敗兩次就動態(tài)插入一個診斷角色來分析原因。這樣既有穩(wěn)定性又有靈活性。4. 角色設計一個 agency 里到底該有哪些 agent4.1 核心角色清單與職責邊界一個能跑通復雜任務的 agency我建議至少包含這幾類角色。注意角色不是越多越好每多一個角色就多一份調度復雜度和 token 成本夠用就行。角色核心職責典型工具建議模型檔位規(guī)劃者 Planner把用戶任務拆成可執(zhí)行的子任務無或僅任務管理工具高能力模型執(zhí)行者 Executor完成具體子任務搜索、代碼執(zhí)行、文件讀寫等中高能力模型審查者 Reviewer檢查產出質量、發(fā)現錯誤無或校驗工具高能力模型匯總者 Synthesizer把多個子任務產出整合成最終結果無中高能力模型診斷者 Diagnoser分析失敗原因、給出修復建議日志讀取高能力模型規(guī)劃者是整個流程的起點它的輸出質量直接決定后續(xù)所有環(huán)節(jié)。我踩過的坑是規(guī)劃者拆的任務粒度太粗或太細都不行。太粗執(zhí)行者拿到一個模糊的大任務還是不知道怎么做太細子任務數量爆炸調度開銷和 token 成本飆升。我的經驗是每個子任務應該是一個執(zhí)行者能在一次交互內完成、且有明確驗收標準的單元。執(zhí)行者是數量最多的角色可以按領域再細分。比如做數據分析的 agency執(zhí)行者可以分成數據獲取者數據清洗者統計分析者可視化者。細分的好處是每個執(zhí)行者的提示詞和工具集都能高度專精。審查者的價值經常被低估。很多人覺得模型自己產出的東西自己檢查就行但實測下來讓一個獨立的、帶著挑刺心態(tài)的審查者來檢查發(fā)現問題的概率明顯高于讓執(zhí)行者自查。因為執(zhí)行者有自己的思維慣性容易對自己的產出過度自信。審查者的提示詞要明確要求它假設產出有問題主動找證據而不是看看有沒有問題。4.2 角色提示詞的寫法三個必須寫清楚的要素每個角色的系統提示詞我建議必須寫清楚三件事身份與目標、能力邊界、輸出格式。身份與目標要具體。不要寫你是一個助手而要寫你是一個負責把復雜任務拆解成可執(zhí)行步驟的規(guī)劃專家你的目標是產出粒度適中、依賴關系清晰的子任務列表。越具體模型越能進入狀態(tài)。能力邊界要明確說不做什么。比如執(zhí)行者的提示詞里要寫你只負責完成分配給你的子任務不要嘗試規(guī)劃整體流程不要修改其他子任務的內容。這條極其重要因為模型天然有越界的傾向不明確禁止它就會去干不屬于自己的活導致職責混亂。輸出格式要嚴格約定。多智能體系統里角色之間的輸出是要被程序解析的格式不對整個流程就斷了。我通常要求角色輸出結構化的 JSON并在提示詞里給出完整的 schema 示例。如果模型經常不遵守格式可以在提示詞末尾加一句只輸出 JSON不要有任何其他文字效果通常不錯。4.3 角色數量與成本的權衡這里分享一個很實際的經驗角色數量要跟著任務復雜度走不要一上來就搭一個十幾個角色的龐大體系。我見過有人一上來就設計了規(guī)劃、執(zhí)行、審查、匯總、診斷、記憶管理、工具路由等七八個角色結果調試了兩周還沒跑通一個完整任務。原因是角色越多交互路徑越多出問題的地方越多而且 token 成本是線性甚至指數級增長的。我的建議是從最小可用集開始規(guī)劃者 執(zhí)行者 審查者三個角色先跑通一個簡單任務。跑通之后再根據實際遇到的瓶頸逐步增加角色。比如發(fā)現執(zhí)行者經常失敗但不知道為什么再加診斷者發(fā)現多個執(zhí)行者產出需要整合再加匯總者。這種漸進式的做法比一次性設計一個大而全的體系要靠譜得多。5. 智能體之間的通信消息格式、狀態(tài)同步與沖突處理5.1 結構化消息格式的設計角色之間傳遞的信息必須是結構化的不能是自由文本。我通常設計一個統一的消息信封envelope包含這幾個字段發(fā)送者、接收者、消息類型、負載payload、時間戳、關聯的子任務 ID。消息類型我一般定義幾種任務分配、任務結果、任務失敗、狀態(tài)查詢、審查意見。每種類型對應不同的 payload 結構。比如任務結果的 payload 里要有子任務 ID、產出內容、執(zhí)行耗時、使用的工具列表任務失敗的 payload 里要有失敗原因、錯誤堆棧、已嘗試的方案。為什么要這么細因為編排層需要根據這些結構化字段做決策。比如看到某個子任務失敗且錯誤類型是工具調用超時編排層就知道可以重試如果錯誤類型是輸入格式錯誤那重試也沒用得讓規(guī)劃者重新拆任務。這些判斷都依賴結構化的錯誤信息自由文本是做不到的。5.2 共享狀態(tài)的并發(fā)寫入問題前面說了用共享狀態(tài)但共享狀態(tài)有個繞不開的問題多個執(zhí)行者并行寫入時怎么避免沖突我的做法是按子任務分區(qū)。共享狀態(tài)里每個子任務有自己獨立的區(qū)域執(zhí)行者只寫自己負責的子任務區(qū)域不碰別人的。這樣并行寫入時天然不沖突。全局性的字段比如當前階段整體進度只由編排層寫入執(zhí)行者只讀不寫。如果確實需要多個角色寫同一塊區(qū)域比如多個審查者都要往審查意見列表里追加那就用追加append而不是覆蓋overwrite的語義并且給每條記錄帶上寫入者標識和時間戳。這樣即使并發(fā)寫入也只是順序問題不會丟數據。5.3 狀態(tài)同步的時機與粒度狀態(tài)同步的時機也很講究。同步太頻繁開銷大同步太少各角色看到的狀態(tài)不一致容易做出錯誤決策。我的經驗是在角色切換的邊界做同步。也就是說一個角色完成工作、把結果寫入共享狀態(tài)后編排層做一次狀態(tài)快照然后再啟動下一個角色。這樣每個角色啟動時看到的都是最新的、一致的狀態(tài)。角色執(zhí)行過程中不需要實時同步因為它只操作自己那塊區(qū)域。對于并行執(zhí)行的多個執(zhí)行者它們各自完成后分別寫入自己的區(qū)域編排層等所有并行任務都結束后再做一次匯總同步。這種邊界同步的策略在保證一致性的同時把同步開銷降到了最低。6. 從零搭一個 agency-agents 的實操步驟6.1 環(huán)境準備與依賴選型假設現在要動手實現我會這樣準備環(huán)境。首先是語言和框架的選擇Python 是這類項目的主流選擇生態(tài)成熟各種大模型 SDK 都有官方支持。編排邏輯可以用純 Python 寫也可以用現成的編排框架但我建議核心調度邏輯自己寫因為現成框架的抽象往往和你的具體需求不完全匹配改起來反而更費勁。依賴方面至少需要一個大模型的調用 SDK、一個用于結構化輸出的校驗庫比如 Pydantic 這類做數據校驗的、一個持久化方案初期用本地文件或輕量數據庫就夠。如果涉及工具調用還需要準備各個工具對應的客戶端庫。配置管理要提前做好。模型 API 的密鑰、各角色的模型選擇、超時時間、重試次數這些都應該放在配置文件里不要硬編碼。我見過太多項目把這些寫死在代碼里換個環(huán)境就要改代碼非常痛苦。6.2 定義共享狀態(tài)的數據結構第一步是定義共享狀態(tài)。用 Pydantic 或類似工具定義一個狀態(tài)類包含任務目標、子任務列表、每個子任務的狀態(tài)和產出、執(zhí)行日志、當前階段。每個子任務本身也是一個結構包含 ID、描述、依賴的子任務 ID、狀態(tài)、產出、錯誤信息。定義好之后寫兩個基礎方法一個是把狀態(tài)序列化成 JSON 存盤一個是從 JSON 反序列化恢復。這兩個方法是斷點恢復的基礎一定要在項目早期就做好。我吃過虧——項目做到一半才想起來要支持斷點恢復結果發(fā)現狀態(tài)結構設計得不合理序列化出來一堆問題返工成本很高。6.3 實現規(guī)劃者任務拆解的關鍵技巧規(guī)劃者的實現核心是提示詞設計和輸出解析。提示詞里要明確要求它輸出一個子任務列表每個子任務包含描述、依賴關系、驗收標準。輸出用 JSON 格式方便解析。這里有個關鍵技巧在提示詞里給規(guī)劃者一個拆解原則。比如每個子任務應該能在一次交互內完成子任務之間的依賴關系要顯式聲明每個子任務要有可驗證的完成標準。不給這些原則規(guī)劃者拆出來的任務質量參差不齊。解析規(guī)劃者輸出時一定要做校驗。檢查子任務數量是否合理比如超過 20 個就要警惕、依賴關系是否有環(huán)、每個子任務是否有描述和驗收標準。校驗不通過就帶著錯誤信息讓規(guī)劃者重新拆通常重試一兩次就能得到合格的結果。6.4 實現執(zhí)行者工具調用與結果回寫執(zhí)行者的實現相對直接但有幾個細節(jié)要注意。執(zhí)行者拿到子任務后要根據任務描述決定調用哪些工具、按什么順序調用。這里我建議給執(zhí)行者一個明確的工具使用規(guī)范比如優(yōu)先使用搜索工具獲取事實信息代碼執(zhí)行前先檢查輸入格式。執(zhí)行完成后執(zhí)行者要把結果寫回共享狀態(tài)對應的子任務區(qū)域并更新子任務狀態(tài)。如果執(zhí)行失敗要寫入結構化的錯誤信息而不是簡單拋個異常。錯誤信息里至少要有失敗原因分類、詳細描述、已嘗試的方案。這些信息是后續(xù)診斷和重試的依據。6.5 實現審查者與匯總者審查者拿到執(zhí)行者的產出后對照子任務的驗收標準做檢查。它的輸出應該是一個結構化的審查結果通過/不通過、不通過的具體問題、修改建議。如果審查不通過編排層要把問題反饋給執(zhí)行者重新做或者交給診斷者分析。匯總者在所有子任務完成后啟動把所有子任務的產出整合成最終結果。它的提示詞要強調保持各部分的一致性消除重復內容確保整體邏輯連貫。匯總不是簡單拼接而是真正的整合這一步做不好前面所有工作都會打折扣。6.6 編排主循環(huán)的編寫編排主循環(huán)是整個系統的中樞。它的邏輯大致是初始化狀態(tài) → 調用規(guī)劃者 → 循環(huán)處理子任務按依賴順序無依賴的并行→ 每個子任務執(zhí)行后調用審查者 → 全部完成后調用匯總者 → 輸出最終結果。循環(huán)里要處理各種異常執(zhí)行失敗的重試、審查不通過的返工、超時的處理。每個異常處理分支都要有明確的策略和上限比如同一子任務最多重試 3 次整個任務最多運行 30 分鐘。沒有上限的循環(huán)是災難我見過因為一個子任務反復失敗導致整個流程跑了幾個小時、燒掉大量 token 的情況。7. 實測中踩過的坑與調優(yōu)經驗7.1 規(guī)劃者拆任務粒度失控最常見的坑是規(guī)劃者拆出來的任務粒度不合適。要么太粗執(zhí)行者拿到分析這份數據這種模糊任務無從下手要么太細把讀取文件和解析文件都拆成獨立子任務導致子任務數量爆炸。我的解法是在提示詞里給出正反例。比如正面例子是計算過去 12 個月的月度銷售增長率并生成趨勢圖反面例子是分析數據太粗和打開文件太細。給了具體例子之后規(guī)劃者的輸出質量明顯提升。另外可以在解析階段做自動檢查子任務描述少于一定字數就判定為太粗打回重拆。7.2 執(zhí)行者越界修改全局狀態(tài)執(zhí)行者越界是個隱蔽但危害很大的問題。表現是執(zhí)行者在完成自己任務的同時順手改了共享狀態(tài)里不屬于它的區(qū)域或者擅自修改了子任務列表。這會導致狀態(tài)混亂后續(xù)角色基于錯誤狀態(tài)做決策。解法是在執(zhí)行者的提示詞里明確禁止同時在代碼層面做權限控制——執(zhí)行者只能寫自己子任務對應的區(qū)域寫其他區(qū)域直接拒絕并記錄警告。提示詞約束加代碼約束雙保險基本能杜絕這個問題。7.3 審查者過于寬松或過于苛刻審查者的尺度很難把握。太寬松問題漏過去最終結果質量差太苛刻什么都通不過執(zhí)行者反復返工流程卡死。我的調法是給審查者明確的判定標準并且要求它區(qū)分必須修改和建議優(yōu)化兩類問題。必須修改的才觸發(fā)返工建議優(yōu)化的記錄在案但不阻塞流程。這樣既保證了質量底線又避免了無限返工。另外可以給審查者設一個通過率的軟約束如果它連續(xù)判定多個子任務不通過就提示它重新審視標準是否過嚴。7.4 token 成本失控的排查多智能體系統的 token 成本很容易失控因為每個角色都要消耗 token而且共享狀態(tài)越大每個角色讀取時消耗的 token 越多。排查成本問題我一般先看共享狀態(tài)的大小。如果狀態(tài)里堆積了大量中間過程的詳細日志每個角色讀取時都要把這些日志讀進去成本自然高。解法是給共享狀態(tài)做分層角色默認只讀和自己相關的部分全局摘要信息單獨維護一份精簡版。這樣每個角色讀取的上下文就小很多。另一個成本大頭是重試。如果某個子任務反復失敗重試token 消耗會成倍增長。所以要給重試設上限并且每次重試時把之前的失敗信息精簡后再傳給執(zhí)行者避免上下文越滾越大。7.5 并行執(zhí)行時的資源競爭并行執(zhí)行多個子任務時如果它們都要調用同一個外部工具比如同一個搜索接口可能會觸發(fā)限流。這個坑我在實際項目里踩過多個執(zhí)行者同時發(fā)請求結果被接口方限流全部失敗。解法是給外部工具調用加一個統一的限流器控制并發(fā)數。另外并行度不要設太高一般 3 到 5 個并行就夠了再高收益遞減而風險上升。并行度這個參數最好做成可配置的方便根據實際情況調整。8. 這套框架適合什么場景以及后續(xù)可以怎么擴展agency-agents 這類多智能體協作框架最適合的是任務結構相對復雜、可以拆解、且對結果質量有要求的場景。比如長文檔的撰寫與審校、多步驟的數據分析流程、需要多輪驗證的代碼生成、復雜的信息調研與整合。這些場景的共同點是單次交互搞不定但拆開之后每個子任務都不算太難。反過來如果任務本身很簡單比如單輪問答、簡單的格式轉換那用多智能體就是殺雞用牛刀徒增成本和復雜度。判斷標準很簡單如果你用單智能體加幾個工具調用就能穩(wěn)定搞定就不要上多智能體。后續(xù)擴展方向我覺得有幾個值得嘗試。一是引入長期記憶讓 agency 能記住之前處理過的類似任務復用經驗。二是動態(tài)角色生成根據任務類型自動決定需要哪些角色而不是預先寫死。三是多 agency 協作讓多個 agency 各自負責一塊再有一個更高層的編排者協調它們。這些方向都很有意思但每加一層復雜度調試難度都會上一個臺階建議在單 agency 跑穩(wěn)之后再考慮。最后分享一個我自己的體會多智能體系統的調試比單智能體難得多因為問題可能出在任何一個角色、任何一次交互上。所以日志和可觀測性一定要在項目早期就做好。每個角色的輸入輸出、每次狀態(tài)變更、每個決策點都要有清晰的日志。我現在的習慣是在編排層加一個回放功能能把一次完整執(zhí)行的所有交互按時間順序打印出來。有了這個排查問題的時間能縮短一大半。這個投入絕對值得。