作實戰(zhàn)：從架構設計到Handoff機制與Skill實現(xiàn))
1. 多 Agent 協(xié)作到底在解決什么問題1.1 從單兵作戰(zhàn)到團隊配合的必然轉變先說一個我自己的真實經(jīng)歷。去年我接手了一個需求要在一周內(nèi)完成一個包含數(shù)據(jù)清洗、特征工程、模型訓練、報告生成和可視化看板的完整項目。如果按傳統(tǒng)方式我一個人從頭寫到尾光是調試數(shù)據(jù)管道就能耗掉三天。后來我嘗試把這套流程拆成四個獨立的 Agent 來跑——一個專門負責數(shù)據(jù)清洗一個負責特征工程一個負責模型訓練和評估最后一個負責生成報告和圖表。結果三天就交付了而且每個環(huán)節(jié)的質量比我一個人硬扛還要穩(wěn)定。這就是多 Agent 協(xié)作最樸素的價值把復雜任務拆解成多個獨立但互相配合的執(zhí)行單元每個單元專注做好一件事通過明確的交接協(xié)議串聯(lián)起來。很多人第一次聽到“多 Agent 協(xié)作”會覺得這是個很玄的概念其實你完全可以把它理解成一個小型軟件團隊。團隊里有前端、后端、測試、產(chǎn)品每個人有自己的職責邊界有明確的輸入和輸出有約定的溝通方式。多 Agent 系統(tǒng)也是一樣的道理只不過團隊成員從人變成了 AI 實例。1.2 什么場景下真的需要多 Agent不是所有任務都值得上多 Agent。我踩過的坑告訴我下面這幾類場景才是多 Agent 真正能發(fā)揮價值的地方任務鏈路長且環(huán)節(jié)異構比如從原始數(shù)據(jù)到最終報告中間要經(jīng)過清洗、分析、建模、寫作等多個性質完全不同的階段。用一個 Agent 從頭做到尾它很容易在某個環(huán)節(jié)“忘記”前面的約束或者在風格上前后不一致。需要多視角交叉驗證比如代碼審查場景一個 Agent 寫代碼另一個 Agent 專門挑毛病第三個 Agent 負責跑測試。這種“對抗式”協(xié)作能顯著降低錯誤率。單次上下文窗口不夠用當任務涉及大量文檔、代碼庫或數(shù)據(jù)集時單個 Agent 的上下文很容易被撐爆。拆成多個 Agent 后每個 Agent 只加載自己需要的那部分信息效率反而更高。需要并行加速有些子任務之間沒有依賴關系比如同時生成多個模塊的文檔、同時測試多個接口。多 Agent 并行跑時間能壓縮到原來的幾分之一。反過來如果你的任務就是“幫我寫一段正則表達式”或者“解釋一下這個報錯”那完全沒必要上多 Agent單個 Agent 甚至直接問搜索引擎更快。工具選型的第一原則永遠是夠用就好別為了炫技而過度設計。1.3 多 Agent 協(xié)作的核心挑戰(zhàn)多 Agent 聽起來很美但真正落地時會遇到幾個非?，F(xiàn)實的問題第一個是上下文傳遞。Agent A 做完數(shù)據(jù)清洗后怎么把結果和必要的元信息傳給 Agent B如果傳得太多B 的上下文被撐爆如果傳得太少B 缺少關鍵信息導致輸出質量下降。這個平衡點需要反復調試。第二個是職責邊界模糊。我見過很多失敗的多 Agent 項目根本原因就是兩個 Agent 的職責有重疊導致互相“踢皮球”或者重復勞動。比如一個 Agent 負責“分析數(shù)據(jù)”另一個負責“生成洞察”這兩個職責在實際操作中很難劃清界限。第三個是錯誤傳播。如果 Agent A 的輸出有錯誤Agent B 基于錯誤輸入繼續(xù)工作錯誤會被逐級放大到最后你拿到一份看起來完整但完全不可信的結果。所以多 Agent 系統(tǒng)里必須有校驗和回滾機制。第四個是協(xié)調開銷。Agent 之間通信本身也要消耗資源和時間。如果拆得太細協(xié)調開銷可能超過任務本身的收益。我一般建議初次嘗試時控制在 3 到 5 個 Agent 之間跑通后再根據(jù)實際瓶頸決定是否繼續(xù)拆分。理解了這些挑戰(zhàn)接下來我們進入具體的方案設計。2. 多 Agent 協(xié)作的整體架構設計2.1 三種主流協(xié)作模式及選型依據(jù)在實際項目中我總結出三種最常用的多 Agent 協(xié)作模式每種模式適合不同的任務類型。第一種是流水線模式Pipeline。Agent 按順序排列前一個的輸出是后一個的輸入像工廠流水線一樣。這種模式最適合任務鏈路清晰、階段劃分明確的場景比如“數(shù)據(jù)清洗 → 特征工程 → 模型訓練 → 報告生成”。優(yōu)點是邏輯簡單、易于調試缺點是如果中間某個環(huán)節(jié)出錯整個鏈路都要重跑。第二種是主從模式Orchestrator-Worker。有一個“主 Agent”負責拆解任務、分配工作、匯總結果多個“從 Agent”各自執(zhí)行子任務。這種模式適合任務可以并行拆分的場景比如同時生成多個模塊的代碼。主 Agent 相當于項目經(jīng)理從 Agent 相當于執(zhí)行者。優(yōu)點是并行效率高缺點是主 Agent 的調度邏輯需要精心設計否則容易成為瓶頸。第三種是辯論模式Debate。多個 Agent 對同一個問題給出各自的答案然后通過交叉評審或投票選出最優(yōu)解。這種模式適合需要高質量決策的場景比如代碼審查、方案評審。優(yōu)點是能顯著降低單點錯誤缺點是資源消耗成倍增加。我個人的選型經(jīng)驗是這樣的模式適合場景資源消耗實現(xiàn)難度推薦指數(shù)流水線階段清晰的線性任務中等低五星主從可并行拆分的任務較高中四星辯論高質量決策場景高高三星對于大多數(shù)初次嘗試多 Agent 的團隊我強烈建議從流水線模式開始。它的心智負擔最小調試起來最直觀而且能覆蓋大部分實際需求。2.2 為什么我選擇 Handoff 作為核心交接機制在多 Agent 協(xié)作中Agent 之間的“交接”是最關鍵的環(huán)節(jié)。我試過幾種不同的交接方式最后穩(wěn)定在Handoff機制上。Handoff 的核心思想很簡單當前 Agent 完成自己的任務后不是直接把原始輸出丟給下一個 Agent而是生成一份結構化的“交接文檔”包含任務摘要、關鍵決策、未解決問題和下一步建議。下一個 Agent 拿到這份文檔后能快速理解上下文而不需要重新閱讀所有原始材料。我舉個例子說明為什么 Handoff 比直接傳遞原始輸出更好。假設 Agent A 負責數(shù)據(jù)清洗它處理了 10 萬條數(shù)據(jù)刪除了 3000 條異常值填充了 500 個缺失值。如果直接把清洗后的數(shù)據(jù)丟給 Agent BB 完全不知道中間發(fā)生了什么可能會對某些數(shù)據(jù)分布感到困惑。但如果 A 生成一份 Handoff 文檔寫明“刪除了 3000 條異常值原因是超出 3 倍標準差填充了 500 個缺失值使用中位數(shù)填充”B 就能在理解數(shù)據(jù)來源的基礎上繼續(xù)工作。Handoff 文檔我一般要求包含以下幾個字段任務摘要用兩三句話說明這個環(huán)節(jié)做了什么。關鍵決策列出所有影響后續(xù)環(huán)節(jié)的重要選擇以及選擇理由。輸出物清單明確列出傳遞給下一個 Agent 的文件、數(shù)據(jù)或代碼。未解決問題如果有遺留問題明確標注出來提醒下游 Agent 注意。下一步建議基于當前進展給下一個 Agent 提供行動建議。這套機制看起來增加了額外工作但實際跑下來它節(jié)省的溝通成本遠遠超過生成文檔的成本。尤其是在多輪迭代中Handoff 文檔就是整個系統(tǒng)的“記憶”能有效防止上下文丟失。2.3 AGENTS.md讓協(xié)作規(guī)則可配置、可復用多 Agent 系統(tǒng)跑起來后最大的痛點之一是規(guī)則散落在各個 Agent 的提示詞里改一處要改好幾處而且容易漏改。后來我引入了AGENTS.md文件來集中管理協(xié)作規(guī)則。AGENTS.md本質上是一個配置文件里面定義了每個 Agent 的角色、職責、輸入輸出格式、交接規(guī)則和約束條件。所有 Agent 在啟動時都會讀取這個文件確保大家對規(guī)則的理解是一致的。我通常把AGENTS.md分成幾個區(qū)塊# AGENTS.md ## 全局規(guī)則 - 所有 Agent 輸出必須使用 Markdown 格式 - 所有 Agent 必須在輸出末尾附上 Handoff 文檔 - 任何 Agent 發(fā)現(xiàn)上游輸入有問題必須立即中止并報告 ## Agent 定義 ### Agent A: 數(shù)據(jù)清洗 - 職責讀取原始數(shù)據(jù)處理缺失值、異常值和重復值 - 輸入raw_data.csv - 輸出cleaned_data.csv handoff_a.md - 約束不得修改原始數(shù)據(jù)文件 ### Agent B: 特征工程 - 職責基于清洗后的數(shù)據(jù)生成特征 - 輸入cleaned_data.csv handoff_a.md - 輸出features.csv handoff_b.md - 約束必須記錄每個特征的生成邏輯 ## 交接規(guī)則 - 上游 Agent 必須在 Handoff 文檔中明確標注輸出物的路徑和格式 - 下游 Agent 在開始工作前必須驗證輸入物的完整性和格式 - 如果驗證失敗下游 Agent 必須回退給上游 Agent 并說明原因有了這個文件整個系統(tǒng)的規(guī)則就變得透明且可維護。新增一個 Agent 時只需要在AGENTS.md里加一段定義其他 Agent 不需要做任何修改。這比把規(guī)則硬編碼在每個 Agent 的提示詞里要優(yōu)雅得多。2.4 上下文變量的設計與傳遞多 Agent 協(xié)作中上下文變量的設計直接決定了系統(tǒng)的穩(wěn)定性和效率。我一般把上下文變量分成三類第一類是全局變量比如項目名稱、目標描述、輸出目錄、時間戳。這些變量在所有 Agent 之間共享每個 Agent 都能讀取但只有主 Agent 有權限修改。第二類是階段變量比如當前處理的數(shù)據(jù)文件路徑、上一步的統(tǒng)計摘要、中間產(chǎn)物的版本號。這些變量隨著任務推進而更新每個 Agent 完成工作后負責更新自己相關的部分。第三類是局部變量只在單個 Agent 內(nèi)部使用比如臨時文件路徑、調試信息、中間計算結果。這些變量不參與交接任務完成后自動清理。我踩過的一個坑是早期我把所有變量都放在一個全局字典里結果 Agent 之間互相覆蓋導致數(shù)據(jù)錯亂。后來改成分類管理后問題就消失了。上下文變量管理的核心原則是誰產(chǎn)生誰負責誰修改誰記錄。3. 核心 Skill 的設計與實現(xiàn)細節(jié)3.1 什么是 Skill為什么它比普通提示詞更強在多 Agent 系統(tǒng)里Skill 是我用來封裝“可復用能力”的基本單元。你可以把它理解成一個函數(shù)有明確的輸入、有確定的處理邏輯、有規(guī)范的輸出。和普通提示詞相比Skill 有幾個顯著優(yōu)勢可復用同一個 Skill 可以被多個 Agent 調用不需要重復編寫提示詞。可測試Skill 的輸入輸出是明確的可以單獨寫測試用例驗證?？山M合多個 Skill 可以串聯(lián)或并聯(lián)形成更復雜的能力?？砂姹竟芾鞸kill 可以像代碼一樣進行版本控制方便追蹤變更。我目前維護的 Skill 庫里有幾十個常用 Skill覆蓋了數(shù)據(jù)讀取、格式轉換、代碼生成、質量檢查、報告撰寫等常見需求。每次啟動新項目時我只需要從庫里挑選合適的 Skill 組合起來就能快速搭建出一個可用的多 Agent 系統(tǒng)。3.2 一個強大協(xié)作 Skill 的完整結構下面我以一個實際在用的“協(xié)作調度 Skill”為例拆解它的完整結構。這個 Skill 的作用是接收一個任務描述自動拆解成子任務分配給對應的 Agent并管理整個執(zhí)行流程。name: collaboration-orchestrator version: 2.3.0 description: 多 Agent 協(xié)作調度 Skill負責任務拆解、分配、監(jiān)控和結果匯總 inputs: - name: task_description type: string required: true description: 待完成的任務描述 - name: available_agents type: list required: true description: 可用 Agent 列表及其能力描述 - name: max_rounds type: integer default: 5 description: 最大迭代輪數(shù) outputs: - name: final_result type: string description: 最終匯總結果 - name: execution_log type: object description: 完整執(zhí)行日志包含每輪的任務分配和結果 steps: - name: analyze_task action: 分析任務描述識別關鍵環(huán)節(jié)和依賴關系 - name: decompose action: 將任務拆解成子任務標注每個子任務的輸入輸出 - name: assign action: 根據(jù) Agent 能力匹配子任務 - name: execute action: 按依賴順序執(zhí)行子任務收集結果 - name: validate action: 校驗每個子任務的輸出質量 - name: aggregate action: 匯總所有子任務結果生成最終輸出 constraints: - 每個子任務必須有明確的驗收標準 - 如果某個子任務失敗最多重試 2 次 - 如果重試后仍失敗記錄問題并繼續(xù)執(zhí)行不依賴該子任務的部分這個 Skill 的設計有幾個關鍵點值得說明第一輸入輸出明確。每個字段都有類型和描述調用方不需要猜測怎么傳參。第二步驟可追蹤。每個步驟都有名字和動作描述執(zhí)行過程中可以精確知道當前進行到哪一步。第三約束條件清晰。什么情況下重試、什么情況下跳過、什么情況下中止都有明確規(guī)定。第四版本化管理。version字段讓我能追蹤 Skill 的演進歷史出問題時可以快速回滾到上一個穩(wěn)定版本。3.3 Skill 的注冊、發(fā)現(xiàn)與調用機制Skill 寫好后需要一套機制讓 Agent 能夠發(fā)現(xiàn)并調用它。我采用的是“注冊中心 按需加載”的方案。注冊中心本質上是一個索引文件記錄了所有可用 Skill 的名稱、版本、描述和入口路徑。Agent 啟動時先讀取注冊中心了解當前有哪些 Skill 可用。當 Agent 需要某個能力時根據(jù)描述匹配到對應的 Skill然后加載并調用。{ skills: [ { name: collaboration-orchestrator, version: 2.3.0, path: ./skills/orchestrator, tags: [協(xié)作, 調度, 任務拆解] }, { name: data-cleaner, version: 1.5.2, path: ./skills/data-cleaner, tags: [數(shù)據(jù), 清洗, 預處理] }, { name: report-generator, version: 3.1.0, path: ./skills/report-generator, tags: [報告, 寫作, 匯總] } ] }這種設計的好處是解耦。Agent 不需要硬編碼任何 Skill 的路徑只需要根據(jù)標簽或描述來匹配。新增 Skill 時只需要在注冊中心加一條記錄所有 Agent 都能立即發(fā)現(xiàn)并使用它。我踩過的一個坑是早期我把 Skill 的調用邏輯直接寫在 Agent 的提示詞里結果每次新增 Skill 都要修改所有 Agent 的提示詞維護成本極高。改成注冊中心機制后這個問題徹底解決了。3.4 協(xié)作 Skill 中的錯誤處理與重試策略多 Agent 系統(tǒng)跑起來后錯誤是常態(tài)而不是例外。我的協(xié)作 Skill 里內(nèi)置了一套分層的錯誤處理策略第一層是輸入校驗。每個 Skill 在執(zhí)行前先校驗輸入是否符合預期格式。如果不符合立即返回錯誤不進入實際處理邏輯。這能攔截掉大部分低級錯誤。第二層是執(zhí)行監(jiān)控。Skill 執(zhí)行過程中記錄關鍵節(jié)點的狀態(tài)。如果某個步驟超時或返回異常立即中止并記錄現(xiàn)場信息。第三層是重試機制。對于可恢復的錯誤比如網(wǎng)絡超時、臨時資源不足自動重試最多 2 次。重試時適當調整參數(shù)比如增加超時時間或降低并發(fā)數(shù)。第四層是降級處理。如果重試后仍然失敗根據(jù)預設的降級策略處理。比如某個數(shù)據(jù)源不可用就使用緩存數(shù)據(jù)某個 Agent 不可用就把它的任務分配給備用 Agent。第五層是人工介入。如果所有自動處理都失敗系統(tǒng)會生成一份詳細的錯誤報告包含失敗環(huán)節(jié)、錯誤信息、已嘗試的解決方案和建議的人工處理步驟。這套分層策略的核心思想是能自動恢復的自動恢復不能自動恢復的優(yōu)雅降級實在不行才找人。實際跑下來90% 以上的錯誤都能在前三層解決需要人工介入的情況很少。4. 完整實操流程從零搭建一個多 Agent 協(xié)作系統(tǒng)4.1 環(huán)境準備與目錄結構規(guī)劃在開始搭建之前先把目錄結構規(guī)劃好。我一般用這樣的結構project/ ├── AGENTS.md # 協(xié)作規(guī)則配置 ├── skills/ # Skill 庫 │ ├── registry.json # Skill 注冊中心 │ ├── orchestrator/ # 協(xié)作調度 Skill │ ├──># Agent A: 數(shù)據(jù)準備者 ## 角色 你是一個數(shù)據(jù)準備專家負責將原始數(shù)據(jù)轉化為可供分析使用的干凈數(shù)據(jù)集。 ## 職責 - 讀取原始數(shù)據(jù)文件 - 處理缺失值、異常值和重復值 - 統(tǒng)一數(shù)據(jù)格式和編碼 - 生成數(shù)據(jù)質量報告 ## 輸入 - 原始數(shù)據(jù)文件路徑 - 數(shù)據(jù)字典如果有 ## 輸出 - 清洗后的數(shù)據(jù)文件 - 數(shù)據(jù)質量報告 - Handoff 文檔 ## 約束 - 不得修改原始數(shù)據(jù)文件 - 所有清洗操作必須記錄在 Handoff 文檔中 - 如果數(shù)據(jù)質量問題超過閾值必須中止并報告 ## 交接規(guī)則 完成工作后生成 handoff_a.md包含 - 任務摘要 - 關鍵決策及理由 - 輸出物清單 - 未解決問題 - 對 Agent B 的建議這種定義方式的好處是邊界清晰。每個 Agent 知道自己該做什么、不該做什么、做到什么程度算完成。實際跑下來職責邊界清晰的系統(tǒng)出錯率比模糊定義的系統(tǒng)低很多。4.3 編寫協(xié)作 Skill 的完整代碼下面是一個簡化版的協(xié)作調度 Skill 的核心代碼用 Python 實現(xiàn)import json import yaml from pathlib import Path from datetime import datetime class CollaborationOrchestrator: def __init__(self, config_path, registry_path): self.config yaml.safe_load(Path(config_path).read_text()) self.registry json.loads(Path(registry_path).read_text()) self.execution_log [] self.handoffs {} def analyze_task(self, task_description): 分析任務識別關鍵環(huán)節(jié) # 實際實現(xiàn)中這里會調用 LLM 做任務分析 # 簡化版根據(jù)關鍵詞匹配 stages [] if 數(shù)據(jù) in task_description or 清洗 in task_description: stages.append(data_preparation) if 分析 in task_description or 統(tǒng)計 in task_description: stages.append(analysis) if 報告 in task_description or 匯總 in task_description: stages.append(reporting) return stages def decompose(self, task_description, stages): 將任務拆解成子任務 subtasks [] for i, stage in enumerate(stages): subtask { id: ftask_{i1}, stage: stage, description: f執(zhí)行 {stage} 階段的工作, depends_on: [ftask_{i}] if i 0 else [], status: pending } subtasks.append(subtask) return subtasks def assign(self, subtasks): 根據(jù) Agent 能力匹配子任務 agent_mapping { data_preparation: agent_a, analysis: agent_b, reporting: agent_c } for subtask in subtasks: subtask[assigned_to] agent_mapping.get(subtask[stage], unknown) return subtasks def execute(self, subtasks): 按依賴順序執(zhí)行子任務 completed set() max_rounds self.config.get(max_rounds, 5) for round_num in range(max_rounds): progress False for subtask in subtasks: if subtask[status] ! pending: continue if not all(dep in completed for dep in subtask[depends_on]): continue # 執(zhí)行子任務 result self._run_subtask(subtask) subtask[status] completed if result[success] else failed subtask[result] result if result[success]: completed.add(subtask[id]) self.handoffs[subtask[id]] result.get(handoff, {}) else: # 重試邏輯 if subtask.get(retry_count, 0) 2: subtask[retry_count] subtask.get(retry_count, 0) 1 subtask[status] pending progress True self._log(subtask) if not progress: break return subtasks def _run_subtask(self, subtask): 實際執(zhí)行子任務這里需要接入具體的 Agent 調用 # 簡化版返回模擬結果 return { success: True, output: f{subtask[stage]} 完成, handoff: { task_id: subtask[id], summary: f完成 {subtask[stage]} 階段, timestamp: datetime.now().isoformat() } } def validate(self, subtasks): 校驗子任務輸出質量 issues [] for subtask in subtasks: if subtask[status] ! completed: issues.append(f{subtask[id]} 未完成) elif not subtask.get(result, {}).get(output): issues.append(f{subtask[id]} 輸出為空) return issues def aggregate(self, subtasks): 匯總所有子任務結果 final_result { task_summary: 多 Agent 協(xié)作任務完成, subtask_results: [ { id: s[id], stage: s[stage], status: s[status], output: s.get(result, {}).get(output, ) } for s in subtasks ], handoffs: self.handoffs, execution_log: self.execution_log } return final_result def _log(self, subtask): 記錄執(zhí)行日志 self.execution_log.append({ timestamp: datetime.now().isoformat(), task_id: subtask[id], stage: subtask[stage], status: subtask[status], assigned_to: subtask.get(assigned_to) }) def run(self, task_description): 完整執(zhí)行流程 stages self.analyze_task(task_description) subtasks self.decompose(task_description, stages) subtasks self.assign(subtasks) subtasks self.execute(subtasks) issues self.validate(subtasks) result self.aggregate(subtasks) result[issues] issues return result這段代碼的核心邏輯是分析 → 拆解 → 分配 → 執(zhí)行 → 校驗 → 匯總。每一步都有明確的輸入輸出方便調試和擴展。實際使用時_run_subtask方法需要接入真實的 Agent 調用邏輯。我一般會在這里調用 LLM API把 Agent 的提示詞和當前上下文傳進去拿到輸出后再解析成結構化結果。4.4 運行、監(jiān)控與結果驗證系統(tǒng)跑起來后監(jiān)控是必不可少的。我一般關注幾個關鍵指標每個子任務的執(zhí)行時間如果某個子任務耗時異常說明可能遇到了問題。重試次數(shù)重試次數(shù)過多說明輸入質量或 Skill 邏輯有問題。Handoff 文檔的完整性如果 Handoff 文檔缺少關鍵字段下游 Agent 會受影響。最終輸出的質量這是最直觀的指標可以通過人工抽檢或自動校驗來評估。我通常會在logs/目錄下生成一份詳細的執(zhí)行日志格式如下{ run_id: 20250115_143022, task: 生成一份銷售數(shù)據(jù)分析報告, start_time: 2025-01-15T14:30:22, end_time: 2025-01-15T14:35:47, total_duration_seconds: 325, subtasks: [ { id: task_1, stage: data_preparation, status: completed, duration_seconds: 120, retry_count: 0 }, { id: task_2, stage: analysis, status: completed, duration_seconds: 150, retry_count: 1 }, { id: task_3, stage: reporting, status: completed, duration_seconds: 55, retry_count: 0 } ], issues: [] }有了這份日志出問題時可以快速定位到具體環(huán)節(jié)。比如上面這個例子task_2重試了一次說明分析階段可能遇到了數(shù)據(jù)格式問題下次可以針對性優(yōu)化。5. 常見問題與排查技巧實錄5.1 Agent 之間上下文丟失怎么辦這是多 Agent 系統(tǒng)里最常見的問題。表現(xiàn)是下游 Agent 的輸出明顯偏離了上游的意圖或者重復問了上游已經(jīng)解決的問題。根本原因通常是 Handoff 文檔寫得太簡略或者關鍵信息沒有結構化地傳遞。我踩過的一個典型坑是Agent A 在清洗數(shù)據(jù)時刪除了某列但沒有在 Handoff 文檔里說明結果 Agent B 在分析時找不到這列直接報錯。解決方案是強制要求 Handoff 文檔包含“變更清單”字段明確列出所有對數(shù)據(jù)的修改操作。同時下游 Agent 在開始工作前必須先校驗輸入物是否符合預期如果不符合立即回退并說明原因。我現(xiàn)在的做法是在AGENTS.md里加一條硬性規(guī)則任何 Agent 在修改輸入數(shù)據(jù)后必須在 Handoff 文檔的“變更清單”中逐條記錄修改內(nèi)容、修改原因和影響范圍。下游 Agent 在開始工作前必須核對變更清單確認無誤后才能繼續(xù)。這條規(guī)則加上后上下文丟失的問題減少了 80% 以上。5.2 任務拆解粒度怎么把握拆得太粗單個 Agent 負擔過重容易出錯拆得太細協(xié)調開銷超過任務本身。我的一般原則是每個子任務的執(zhí)行時間控制在 1 到 5 分鐘之間。太短說明拆得過細太長說明還可以繼續(xù)拆。每個子任務有明確的驗收標準。如果說不清楚“做到什么程度算完成”說明拆解還不夠清晰。子任務之間的依賴關系盡量簡單。如果依賴關系復雜到需要畫圖才能理清說明拆解方式有問題應該重新設計。我通常先用粗粒度拆解跑一遍觀察哪個環(huán)節(jié)耗時最長或出錯最多然后針對性地細化那個環(huán)節(jié)。這種“先跑通再優(yōu)化”的方式比一開始就追求完美拆解要高效得多。5.3 Skill 調用失敗的排查思路Skill 調用失敗時我一般按這個順序排查第一步檢查輸入格式。90% 的失敗都是輸入格式不對導致的。用jsonschema之類的工具做嚴格校驗能攔截掉大部分問題。第二步檢查依賴資源。Skill 依賴的文件、API、數(shù)據(jù)庫是否可用我遇到過好幾次因為臨時文件被清理導致 Skill 失敗的情況后來加了資源檢查步驟就解決了。第三步檢查權限。Skill 是否有權限讀寫目標文件是否有權限調用外部服務權限問題在多 Agent 系統(tǒng)里很常見因為不同 Agent 可能運行在不同的權限上下文中。第四步查看詳細日志。如果前三步都沒問題就需要看 Skill 內(nèi)部的執(zhí)行日志了。我一般會在 Skill 的關鍵節(jié)點打日志方便定位問題。下面是我整理的一份常見問題速查表問題現(xiàn)象可能原因排查方法解決方案Skill 返回空結果輸入格式錯誤檢查輸入 schema修正輸入格式Skill 執(zhí)行超時依賴資源不可用檢查文件/API 狀態(tài)恢復資源或使用備用方案Skill 報權限錯誤權限配置不當檢查文件/服務權限調整權限配置Skill 輸出不符合預期提示詞不清晰檢查 Skill 定義優(yōu)化提示詞和約束條件Skill 頻繁重試輸入質量差檢查上游輸出優(yōu)化上游 Agent 的輸出質量5.4 多 Agent 系統(tǒng)的性能優(yōu)化經(jīng)驗系統(tǒng)跑通后下一步就是優(yōu)化性能。我總結了幾條實用的優(yōu)化經(jīng)驗第一并行化無依賴的子任務。如果兩個子任務之間沒有依賴關系就讓它們并行跑。我用asyncio實現(xiàn)并行調度實測下來能把總耗時壓縮 40% 左右。第二緩存重復計算的結果。有些 Skill 的輸出是確定性的同樣的輸入總是得到同樣的輸出。這類 Skill 的結果可以緩存起來下次遇到相同輸入時直接返回緩存結果。第三精簡 Handoff 文檔。Handoff 文檔不是越詳細越好關鍵是傳遞“下游需要知道的信息”。我一般控制在 500 字以內(nèi)超過這個長度就說明可能包含了冗余信息。第四合理設置超時時間。超時時間太短會導致正常任務被誤殺太長會導致問題任務拖慢整個系統(tǒng)。我一般根據(jù)歷史執(zhí)行時間的 P95 值來設置留出 20% 的余量。第五定期清理中間產(chǎn)物。多 Agent 系統(tǒng)跑久了workspace/intermediate/目錄會積累大量臨時文件。我一般設置一個定時任務每天清理超過 7 天的中間產(chǎn)物避免磁盤空間被占滿。5.5 從單 Agent 遷移到多 Agent 的注意事項如果你現(xiàn)在用的是單 Agent想遷移到多 Agent我建議按這個順序來第一步先梳理現(xiàn)有流程。把單 Agent 做的事情拆解成清晰的步驟標注每步的輸入輸出。這一步不需要寫代碼用紙筆或者流程圖工具就行。第二步識別可獨立拆分的環(huán)節(jié)。哪些環(huán)節(jié)是相對獨立的哪些環(huán)節(jié)之間有強依賴優(yōu)先拆分獨立環(huán)節(jié)。第三步先拆一個環(huán)節(jié)試試。不要一次性全拆先拆一個環(huán)節(jié)跑通后再拆下一個。這樣風險可控出問題也容易回滾。第四步建立 Handoff 機制。在拆分之前先把 Handoff 文檔的格式和規(guī)則定好。這是多 Agent 協(xié)作的基礎設施必須先建好。第五步逐步替換。每次替換一個環(huán)節(jié)觀察一段時間確認穩(wěn)定后再替換下一個。全部替換完成后再考慮優(yōu)化整體性能。我自己的經(jīng)驗是從單 Agent 遷移到多 Agent最大的挑戰(zhàn)不是技術而是思維方式的轉變。你需要從“一個 Agent 做所有事”轉變?yōu)椤岸鄠€ Agent 各司其職、互相配合”。這個轉變需要時間但只要跑通第一個多 Agent 項目后面的路就順了。6. 多 Agent 協(xié)作的擴展方向與個人體會6.1 從固定流程到動態(tài)編排目前我用的多 Agent 系統(tǒng)還是以固定流程為主任務拆解和 Agent 分配都是預先定義好的。下一步我想嘗試的是動態(tài)編排根據(jù)任務的實際特點自動決定拆解方式和 Agent 組合。比如同樣是數(shù)據(jù)分析任務如果數(shù)據(jù)量小可能只需要兩個 Agent如果數(shù)據(jù)量大且復雜可能需要五個 Agent。動態(tài)編排的核心是讓系統(tǒng)具備“元認知”能力能夠評估任務難度并做出相應的資源分配決策。我目前的想法是引入一個“評估 Agent”專門負責任務難度評估和資源規(guī)劃。它不直接執(zhí)行任務而是為其他 Agent 提供調度建議。這個思路還在驗證中等跑通了再單獨寫一篇分享。6.2 多 Agent 系統(tǒng)的可觀測性建設系統(tǒng)越復雜可觀測性越重要。我現(xiàn)在正在完善的是多 Agent 系統(tǒng)的監(jiān)控面板希望能實時看到每個 Agent 的狀態(tài)、每個子任務的進度、每個 Skill 的調用情況?？捎^測性建設我分三個層次日志層記錄所有關鍵事件包括 Agent 啟動、任務分配、Skill 調用、錯誤發(fā)生等。指標層統(tǒng)計關鍵指標比如任務完成率、平均執(zhí)行時間、重試率、錯誤率等。追蹤層追蹤單個任務的完整執(zhí)行鏈路從任務創(chuàng)建到最終輸出中間經(jīng)過了哪些 Agent、哪些 Skill、哪些決策。這三個層次建好后排查問題會變得非常高效。以前需要翻半天日志才能定位的問題現(xiàn)在在面板上掃一眼就能發(fā)現(xiàn)異常。6.3 我踩過的三個大坑第一個坑是過度設計。剛開始做多 Agent 時我設計了七個 Agent每個 Agent 負責一個非常細的環(huán)節(jié)。結果協(xié)調開銷巨大系統(tǒng)跑起來比單 Agent 還慢。后來砍到三個 Agent效率反而提升了。教訓是Agent 數(shù)量不是越多越好夠用就行。第二個坑是忽視 Handoff 文檔的質量。早期我覺得 Handoff 文檔就是走個形式隨便寫寫就行。結果下游 Agent 經(jīng)常因為缺少關鍵信息而輸出錯誤結果。后來我把 Handoff 文檔的質量納入驗收標準問題才解決。教訓是Handoff 文檔是多 Agent 系統(tǒng)的生命線必須認真對待。第三個坑是沒有回滾機制。有一次 Agent B 的輸出有問題但系統(tǒng)沒有檢測到繼續(xù)往下跑最后生成了一份完全錯誤的報告。后來我加了校驗和回滾機制任何環(huán)節(jié)發(fā)現(xiàn)問題都能立即中止并回退到上一個穩(wěn)定狀態(tài)。教訓是多 Agent 系統(tǒng)必須有容錯和回滾能力否則錯誤會逐級放大。6.4 給初次嘗試者的實用建議如果你正準備嘗試多 Agent 協(xié)作我最后分享幾條實用建議從簡單任務開始。不要一上來就挑戰(zhàn)復雜項目先找一個兩三個環(huán)節(jié)的小任務跑通流程。跑通后再逐步增加復雜度。先把 Handoff 機制建好。這是多 Agent 協(xié)作的基礎設施不要等到出問題了才想起來補。我一般建議在寫第一個 Agent 之前就把 Handoff 文檔的模板和規(guī)則定好?？刂?Agent 數(shù)量。初次嘗試建議控制在 3 個以內(nèi)跑通后再根據(jù)實際需要增加。Agent 越多協(xié)調開銷越大出問題的概率也越高。重視日志和監(jiān)控。多 Agent 系統(tǒng)的調試比單 Agent 復雜得多沒有完善的日志和監(jiān)控排查問題會非常痛苦。保持耐心。多 Agent 協(xié)作不是一蹴而就的需要反復調試和優(yōu)化。我自己的第一個多 Agent 項目跑了整整兩周才穩(wěn)定下來但穩(wěn)定之后效率提升是實實在在的。這套多 Agent 協(xié)作方案我目前已經(jīng)在三個實際項目中落地使用最長的跑了半年多整體穩(wěn)定性不錯。當然它肯定不是唯一正確的方案不同團隊、不同場景可能需要不同的設計。關鍵是理解背后的核心原理然后根據(jù)自己的實際情況靈活調整。 多Agent協(xié)作實戰(zhàn)：從架構設計到Handoff機制與Skill實現(xiàn)
1. 多 Agent 協(xié)作到底在解決什么問題1.1 從單兵作戰(zhàn)到團隊配合的必然轉變先說一個我自己的真實經(jīng)歷。去年我接手了一個需求要在一周內(nèi)完成一個包含數(shù)據(jù)清洗、特征工程、模型訓練、報告生成和可視化看板的完整項目。如果按傳統(tǒng)方式我一個人從頭寫到尾光是調試數(shù)據(jù)管道就能耗掉三天。后來我嘗試把這套流程拆成四個獨立的 Agent 來跑——一個專門負責數(shù)據(jù)清洗一個負責特征工程一個負責模型訓練和評估最后一個負責生成報告和圖表。結果三天就交付了而且每個環(huán)節(jié)的質量比我一個人硬扛還要穩(wěn)定。這就是多 Agent 協(xié)作最樸素的價值把復雜任務拆解成多個獨立但互相配合的執(zhí)行單元每個單元專注做好一件事通過明確的交接協(xié)議串聯(lián)起來。很多人第一次聽到“多 Agent 協(xié)作”會覺得這是個很玄的概念其實你完全可以把它理解成一個小型軟件團隊。團隊里有前端、后端、測試、產(chǎn)品每個人有自己的職責邊界有明確的輸入和輸出有約定的溝通方式。多 Agent 系統(tǒng)也是一樣的道理只不過團隊成員從人變成了 AI 實例。1.2 什么場景下真的需要多 Agent不是所有任務都值得上多 Agent。我踩過的坑告訴我下面這幾類場景才是多 Agent 真正能發(fā)揮價值的地方任務鏈路長且環(huán)節(jié)異構比如從原始數(shù)據(jù)到最終報告中間要經(jīng)過清洗、分析、建模、寫作等多個性質完全不同的階段。用一個 Agent 從頭做到尾它很容易在某個環(huán)節(jié)“忘記”前面的約束或者在風格上前后不一致。需要多視角交叉驗證比如代碼審查場景一個 Agent 寫代碼另一個 Agent 專門挑毛病第三個 Agent 負責跑測試。這種“對抗式”協(xié)作能顯著降低錯誤率。單次上下文窗口不夠用當任務涉及大量文檔、代碼庫或數(shù)據(jù)集時單個 Agent 的上下文很容易被撐爆。拆成多個 Agent 后每個 Agent 只加載自己需要的那部分信息效率反而更高。需要并行加速有些子任務之間沒有依賴關系比如同時生成多個模塊的文檔、同時測試多個接口。多 Agent 并行跑時間能壓縮到原來的幾分之一。反過來如果你的任務就是“幫我寫一段正則表達式”或者“解釋一下這個報錯”那完全沒必要上多 Agent單個 Agent 甚至直接問搜索引擎更快。工具選型的第一原則永遠是夠用就好別為了炫技而過度設計。1.3 多 Agent 協(xié)作的核心挑戰(zhàn)多 Agent 聽起來很美但真正落地時會遇到幾個非?，F(xiàn)實的問題第一個是上下文傳遞。Agent A 做完數(shù)據(jù)清洗后怎么把結果和必要的元信息傳給 Agent B如果傳得太多B 的上下文被撐爆如果傳得太少B 缺少關鍵信息導致輸出質量下降。這個平衡點需要反復調試。第二個是職責邊界模糊。我見過很多失敗的多 Agent 項目根本原因就是兩個 Agent 的職責有重疊導致互相“踢皮球”或者重復勞動。比如一個 Agent 負責“分析數(shù)據(jù)”另一個負責“生成洞察”這兩個職責在實際操作中很難劃清界限。第三個是錯誤傳播。如果 Agent A 的輸出有錯誤Agent B 基于錯誤輸入繼續(xù)工作錯誤會被逐級放大到最后你拿到一份看起來完整但完全不可信的結果。所以多 Agent 系統(tǒng)里必須有校驗和回滾機制。第四個是協(xié)調開銷。Agent 之間通信本身也要消耗資源和時間。如果拆得太細協(xié)調開銷可能超過任務本身的收益。我一般建議初次嘗試時控制在 3 到 5 個 Agent 之間跑通后再根據(jù)實際瓶頸決定是否繼續(xù)拆分。理解了這些挑戰(zhàn)接下來我們進入具體的方案設計。2. 多 Agent 協(xié)作的整體架構設計2.1 三種主流協(xié)作模式及選型依據(jù)在實際項目中我總結出三種最常用的多 Agent 協(xié)作模式每種模式適合不同的任務類型。第一種是流水線模式Pipeline。Agent 按順序排列前一個的輸出是后一個的輸入像工廠流水線一樣。這種模式最適合任務鏈路清晰、階段劃分明確的場景比如“數(shù)據(jù)清洗 → 特征工程 → 模型訓練 → 報告生成”。優(yōu)點是邏輯簡單、易于調試缺點是如果中間某個環(huán)節(jié)出錯整個鏈路都要重跑。第二種是主從模式Orchestrator-Worker。有一個“主 Agent”負責拆解任務、分配工作、匯總結果多個“從 Agent”各自執(zhí)行子任務。這種模式適合任務可以并行拆分的場景比如同時生成多個模塊的代碼。主 Agent 相當于項目經(jīng)理從 Agent 相當于執(zhí)行者。優(yōu)點是并行效率高缺點是主 Agent 的調度邏輯需要精心設計否則容易成為瓶頸。第三種是辯論模式Debate。多個 Agent 對同一個問題給出各自的答案然后通過交叉評審或投票選出最優(yōu)解。這種模式適合需要高質量決策的場景比如代碼審查、方案評審。優(yōu)點是能顯著降低單點錯誤缺點是資源消耗成倍增加。我個人的選型經(jīng)驗是這樣的模式適合場景資源消耗實現(xiàn)難度推薦指數(shù)流水線階段清晰的線性任務中等低五星主從可并行拆分的任務較高中四星辯論高質量決策場景高高三星對于大多數(shù)初次嘗試多 Agent 的團隊我強烈建議從流水線模式開始。它的心智負擔最小調試起來最直觀而且能覆蓋大部分實際需求。2.2 為什么我選擇 Handoff 作為核心交接機制在多 Agent 協(xié)作中Agent 之間的“交接”是最關鍵的環(huán)節(jié)。我試過幾種不同的交接方式最后穩(wěn)定在Handoff機制上。Handoff 的核心思想很簡單當前 Agent 完成自己的任務后不是直接把原始輸出丟給下一個 Agent而是生成一份結構化的“交接文檔”包含任務摘要、關鍵決策、未解決問題和下一步建議。下一個 Agent 拿到這份文檔后能快速理解上下文而不需要重新閱讀所有原始材料。我舉個例子說明為什么 Handoff 比直接傳遞原始輸出更好。假設 Agent A 負責數(shù)據(jù)清洗它處理了 10 萬條數(shù)據(jù)刪除了 3000 條異常值填充了 500 個缺失值。如果直接把清洗后的數(shù)據(jù)丟給 Agent BB 完全不知道中間發(fā)生了什么可能會對某些數(shù)據(jù)分布感到困惑。但如果 A 生成一份 Handoff 文檔寫明“刪除了 3000 條異常值原因是超出 3 倍標準差填充了 500 個缺失值使用中位數(shù)填充”B 就能在理解數(shù)據(jù)來源的基礎上繼續(xù)工作。Handoff 文檔我一般要求包含以下幾個字段任務摘要用兩三句話說明這個環(huán)節(jié)做了什么。關鍵決策列出所有影響后續(xù)環(huán)節(jié)的重要選擇以及選擇理由。輸出物清單明確列出傳遞給下一個 Agent 的文件、數(shù)據(jù)或代碼。未解決問題如果有遺留問題明確標注出來提醒下游 Agent 注意。下一步建議基于當前進展給下一個 Agent 提供行動建議。這套機制看起來增加了額外工作但實際跑下來它節(jié)省的溝通成本遠遠超過生成文檔的成本。尤其是在多輪迭代中Handoff 文檔就是整個系統(tǒng)的“記憶”能有效防止上下文丟失。2.3 AGENTS.md讓協(xié)作規(guī)則可配置、可復用多 Agent 系統(tǒng)跑起來后最大的痛點之一是規(guī)則散落在各個 Agent 的提示詞里改一處要改好幾處而且容易漏改。后來我引入了AGENTS.md文件來集中管理協(xié)作規(guī)則。AGENTS.md本質上是一個配置文件里面定義了每個 Agent 的角色、職責、輸入輸出格式、交接規(guī)則和約束條件。所有 Agent 在啟動時都會讀取這個文件確保大家對規(guī)則的理解是一致的。我通常把AGENTS.md分成幾個區(qū)塊# AGENTS.md ## 全局規(guī)則 - 所有 Agent 輸出必須使用 Markdown 格式 - 所有 Agent 必須在輸出末尾附上 Handoff 文檔 - 任何 Agent 發(fā)現(xiàn)上游輸入有問題必須立即中止并報告 ## Agent 定義 ### Agent A: 數(shù)據(jù)清洗 - 職責讀取原始數(shù)據(jù)處理缺失值、異常值和重復值 - 輸入raw_data.csv - 輸出cleaned_data.csv handoff_a.md - 約束不得修改原始數(shù)據(jù)文件 ### Agent B: 特征工程 - 職責基于清洗后的數(shù)據(jù)生成特征 - 輸入cleaned_data.csv handoff_a.md - 輸出features.csv handoff_b.md - 約束必須記錄每個特征的生成邏輯 ## 交接規(guī)則 - 上游 Agent 必須在 Handoff 文檔中明確標注輸出物的路徑和格式 - 下游 Agent 在開始工作前必須驗證輸入物的完整性和格式 - 如果驗證失敗下游 Agent 必須回退給上游 Agent 并說明原因有了這個文件整個系統(tǒng)的規(guī)則就變得透明且可維護。新增一個 Agent 時只需要在AGENTS.md里加一段定義其他 Agent 不需要做任何修改。這比把規(guī)則硬編碼在每個 Agent 的提示詞里要優(yōu)雅得多。2.4 上下文變量的設計與傳遞多 Agent 協(xié)作中上下文變量的設計直接決定了系統(tǒng)的穩(wěn)定性和效率。我一般把上下文變量分成三類第一類是全局變量比如項目名稱、目標描述、輸出目錄、時間戳。這些變量在所有 Agent 之間共享每個 Agent 都能讀取但只有主 Agent 有權限修改。第二類是階段變量比如當前處理的數(shù)據(jù)文件路徑、上一步的統(tǒng)計摘要、中間產(chǎn)物的版本號。這些變量隨著任務推進而更新每個 Agent 完成工作后負責更新自己相關的部分。第三類是局部變量只在單個 Agent 內(nèi)部使用比如臨時文件路徑、調試信息、中間計算結果。這些變量不參與交接任務完成后自動清理。我踩過的一個坑是早期我把所有變量都放在一個全局字典里結果 Agent 之間互相覆蓋導致數(shù)據(jù)錯亂。后來改成分類管理后問題就消失了。上下文變量管理的核心原則是誰產(chǎn)生誰負責誰修改誰記錄。3. 核心 Skill 的設計與實現(xiàn)細節(jié)3.1 什么是 Skill為什么它比普通提示詞更強在多 Agent 系統(tǒng)里Skill 是我用來封裝“可復用能力”的基本單元。你可以把它理解成一個函數(shù)有明確的輸入、有確定的處理邏輯、有規(guī)范的輸出。和普通提示詞相比Skill 有幾個顯著優(yōu)勢可復用同一個 Skill 可以被多個 Agent 調用不需要重復編寫提示詞。可測試Skill 的輸入輸出是明確的可以單獨寫測試用例驗證?？山M合多個 Skill 可以串聯(lián)或并聯(lián)形成更復雜的能力?？砂姹竟芾鞸kill 可以像代碼一樣進行版本控制方便追蹤變更。我目前維護的 Skill 庫里有幾十個常用 Skill覆蓋了數(shù)據(jù)讀取、格式轉換、代碼生成、質量檢查、報告撰寫等常見需求。每次啟動新項目時我只需要從庫里挑選合適的 Skill 組合起來就能快速搭建出一個可用的多 Agent 系統(tǒng)。3.2 一個強大協(xié)作 Skill 的完整結構下面我以一個實際在用的“協(xié)作調度 Skill”為例拆解它的完整結構。這個 Skill 的作用是接收一個任務描述自動拆解成子任務分配給對應的 Agent并管理整個執(zhí)行流程。name: collaboration-orchestrator version: 2.3.0 description: 多 Agent 協(xié)作調度 Skill負責任務拆解、分配、監(jiān)控和結果匯總 inputs: - name: task_description type: string required: true description: 待完成的任務描述 - name: available_agents type: list required: true description: 可用 Agent 列表及其能力描述 - name: max_rounds type: integer default: 5 description: 最大迭代輪數(shù) outputs: - name: final_result type: string description: 最終匯總結果 - name: execution_log type: object description: 完整執(zhí)行日志包含每輪的任務分配和結果 steps: - name: analyze_task action: 分析任務描述識別關鍵環(huán)節(jié)和依賴關系 - name: decompose action: 將任務拆解成子任務標注每個子任務的輸入輸出 - name: assign action: 根據(jù) Agent 能力匹配子任務 - name: execute action: 按依賴順序執(zhí)行子任務收集結果 - name: validate action: 校驗每個子任務的輸出質量 - name: aggregate action: 匯總所有子任務結果生成最終輸出 constraints: - 每個子任務必須有明確的驗收標準 - 如果某個子任務失敗最多重試 2 次 - 如果重試后仍失敗記錄問題并繼續(xù)執(zhí)行不依賴該子任務的部分這個 Skill 的設計有幾個關鍵點值得說明第一輸入輸出明確。每個字段都有類型和描述調用方不需要猜測怎么傳參。第二步驟可追蹤。每個步驟都有名字和動作描述執(zhí)行過程中可以精確知道當前進行到哪一步。第三約束條件清晰。什么情況下重試、什么情況下跳過、什么情況下中止都有明確規(guī)定。第四版本化管理。version字段讓我能追蹤 Skill 的演進歷史出問題時可以快速回滾到上一個穩(wěn)定版本。3.3 Skill 的注冊、發(fā)現(xiàn)與調用機制Skill 寫好后需要一套機制讓 Agent 能夠發(fā)現(xiàn)并調用它。我采用的是“注冊中心 按需加載”的方案。注冊中心本質上是一個索引文件記錄了所有可用 Skill 的名稱、版本、描述和入口路徑。Agent 啟動時先讀取注冊中心了解當前有哪些 Skill 可用。當 Agent 需要某個能力時根據(jù)描述匹配到對應的 Skill然后加載并調用。{ skills: [ { name: collaboration-orchestrator, version: 2.3.0, path: ./skills/orchestrator, tags: [協(xié)作, 調度, 任務拆解] }, { name: data-cleaner, version: 1.5.2, path: ./skills/data-cleaner, tags: [數(shù)據(jù), 清洗, 預處理] }, { name: report-generator, version: 3.1.0, path: ./skills/report-generator, tags: [報告, 寫作, 匯總] } ] }這種設計的好處是解耦。Agent 不需要硬編碼任何 Skill 的路徑只需要根據(jù)標簽或描述來匹配。新增 Skill 時只需要在注冊中心加一條記錄所有 Agent 都能立即發(fā)現(xiàn)并使用它。我踩過的一個坑是早期我把 Skill 的調用邏輯直接寫在 Agent 的提示詞里結果每次新增 Skill 都要修改所有 Agent 的提示詞維護成本極高。改成注冊中心機制后這個問題徹底解決了。3.4 協(xié)作 Skill 中的錯誤處理與重試策略多 Agent 系統(tǒng)跑起來后錯誤是常態(tài)而不是例外。我的協(xié)作 Skill 里內(nèi)置了一套分層的錯誤處理策略第一層是輸入校驗。每個 Skill 在執(zhí)行前先校驗輸入是否符合預期格式。如果不符合立即返回錯誤不進入實際處理邏輯。這能攔截掉大部分低級錯誤。第二層是執(zhí)行監(jiān)控。Skill 執(zhí)行過程中記錄關鍵節(jié)點的狀態(tài)。如果某個步驟超時或返回異常立即中止并記錄現(xiàn)場信息。第三層是重試機制。對于可恢復的錯誤比如網(wǎng)絡超時、臨時資源不足自動重試最多 2 次。重試時適當調整參數(shù)比如增加超時時間或降低并發(fā)數(shù)。第四層是降級處理。如果重試后仍然失敗根據(jù)預設的降級策略處理。比如某個數(shù)據(jù)源不可用就使用緩存數(shù)據(jù)某個 Agent 不可用就把它的任務分配給備用 Agent。第五層是人工介入。如果所有自動處理都失敗系統(tǒng)會生成一份詳細的錯誤報告包含失敗環(huán)節(jié)、錯誤信息、已嘗試的解決方案和建議的人工處理步驟。這套分層策略的核心思想是能自動恢復的自動恢復不能自動恢復的優(yōu)雅降級實在不行才找人。實際跑下來90% 以上的錯誤都能在前三層解決需要人工介入的情況很少。4. 完整實操流程從零搭建一個多 Agent 協(xié)作系統(tǒng)4.1 環(huán)境準備與目錄結構規(guī)劃在開始搭建之前先把目錄結構規(guī)劃好。我一般用這樣的結構project/ ├── AGENTS.md # 協(xié)作規(guī)則配置 ├── skills/ # Skill 庫 │ ├── registry.json # Skill 注冊中心 │ ├── orchestrator/ # 協(xié)作調度 Skill │ ├──># Agent A: 數(shù)據(jù)準備者 ## 角色 你是一個數(shù)據(jù)準備專家負責將原始數(shù)據(jù)轉化為可供分析使用的干凈數(shù)據(jù)集。 ## 職責 - 讀取原始數(shù)據(jù)文件 - 處理缺失值、異常值和重復值 - 統(tǒng)一數(shù)據(jù)格式和編碼 - 生成數(shù)據(jù)質量報告 ## 輸入 - 原始數(shù)據(jù)文件路徑 - 數(shù)據(jù)字典如果有 ## 輸出 - 清洗后的數(shù)據(jù)文件 - 數(shù)據(jù)質量報告 - Handoff 文檔 ## 約束 - 不得修改原始數(shù)據(jù)文件 - 所有清洗操作必須記錄在 Handoff 文檔中 - 如果數(shù)據(jù)質量問題超過閾值必須中止并報告 ## 交接規(guī)則 完成工作后生成 handoff_a.md包含 - 任務摘要 - 關鍵決策及理由 - 輸出物清單 - 未解決問題 - 對 Agent B 的建議這種定義方式的好處是邊界清晰。每個 Agent 知道自己該做什么、不該做什么、做到什么程度算完成。實際跑下來職責邊界清晰的系統(tǒng)出錯率比模糊定義的系統(tǒng)低很多。4.3 編寫協(xié)作 Skill 的完整代碼下面是一個簡化版的協(xié)作調度 Skill 的核心代碼用 Python 實現(xiàn)import json import yaml from pathlib import Path from datetime import datetime class CollaborationOrchestrator: def __init__(self, config_path, registry_path): self.config yaml.safe_load(Path(config_path).read_text()) self.registry json.loads(Path(registry_path).read_text()) self.execution_log [] self.handoffs {} def analyze_task(self, task_description): 分析任務識別關鍵環(huán)節(jié) # 實際實現(xiàn)中這里會調用 LLM 做任務分析 # 簡化版根據(jù)關鍵詞匹配 stages [] if 數(shù)據(jù) in task_description or 清洗 in task_description: stages.append(data_preparation) if 分析 in task_description or 統(tǒng)計 in task_description: stages.append(analysis) if 報告 in task_description or 匯總 in task_description: stages.append(reporting) return stages def decompose(self, task_description, stages): 將任務拆解成子任務 subtasks [] for i, stage in enumerate(stages): subtask { id: ftask_{i1}, stage: stage, description: f執(zhí)行 {stage} 階段的工作, depends_on: [ftask_{i}] if i 0 else [], status: pending } subtasks.append(subtask) return subtasks def assign(self, subtasks): 根據(jù) Agent 能力匹配子任務 agent_mapping { data_preparation: agent_a, analysis: agent_b, reporting: agent_c } for subtask in subtasks: subtask[assigned_to] agent_mapping.get(subtask[stage], unknown) return subtasks def execute(self, subtasks): 按依賴順序執(zhí)行子任務 completed set() max_rounds self.config.get(max_rounds, 5) for round_num in range(max_rounds): progress False for subtask in subtasks: if subtask[status] ! pending: continue if not all(dep in completed for dep in subtask[depends_on]): continue # 執(zhí)行子任務 result self._run_subtask(subtask) subtask[status] completed if result[success] else failed subtask[result] result if result[success]: completed.add(subtask[id]) self.handoffs[subtask[id]] result.get(handoff, {}) else: # 重試邏輯 if subtask.get(retry_count, 0) 2: subtask[retry_count] subtask.get(retry_count, 0) 1 subtask[status] pending progress True self._log(subtask) if not progress: break return subtasks def _run_subtask(self, subtask): 實際執(zhí)行子任務這里需要接入具體的 Agent 調用 # 簡化版返回模擬結果 return { success: True, output: f{subtask[stage]} 完成, handoff: { task_id: subtask[id], summary: f完成 {subtask[stage]} 階段, timestamp: datetime.now().isoformat() } } def validate(self, subtasks): 校驗子任務輸出質量 issues [] for subtask in subtasks: if subtask[status] ! completed: issues.append(f{subtask[id]} 未完成) elif not subtask.get(result, {}).get(output): issues.append(f{subtask[id]} 輸出為空) return issues def aggregate(self, subtasks): 匯總所有子任務結果 final_result { task_summary: 多 Agent 協(xié)作任務完成, subtask_results: [ { id: s[id], stage: s[stage], status: s[status], output: s.get(result, {}).get(output, ) } for s in subtasks ], handoffs: self.handoffs, execution_log: self.execution_log } return final_result def _log(self, subtask): 記錄執(zhí)行日志 self.execution_log.append({ timestamp: datetime.now().isoformat(), task_id: subtask[id], stage: subtask[stage], status: subtask[status], assigned_to: subtask.get(assigned_to) }) def run(self, task_description): 完整執(zhí)行流程 stages self.analyze_task(task_description) subtasks self.decompose(task_description, stages) subtasks self.assign(subtasks) subtasks self.execute(subtasks) issues self.validate(subtasks) result self.aggregate(subtasks) result[issues] issues return result這段代碼的核心邏輯是分析 → 拆解 → 分配 → 執(zhí)行 → 校驗 → 匯總。每一步都有明確的輸入輸出方便調試和擴展。實際使用時_run_subtask方法需要接入真實的 Agent 調用邏輯。我一般會在這里調用 LLM API把 Agent 的提示詞和當前上下文傳進去拿到輸出后再解析成結構化結果。4.4 運行、監(jiān)控與結果驗證系統(tǒng)跑起來后監(jiān)控是必不可少的。我一般關注幾個關鍵指標每個子任務的執(zhí)行時間如果某個子任務耗時異常說明可能遇到了問題。重試次數(shù)重試次數(shù)過多說明輸入質量或 Skill 邏輯有問題。Handoff 文檔的完整性如果 Handoff 文檔缺少關鍵字段下游 Agent 會受影響。最終輸出的質量這是最直觀的指標可以通過人工抽檢或自動校驗來評估。我通常會在logs/目錄下生成一份詳細的執(zhí)行日志格式如下{ run_id: 20250115_143022, task: 生成一份銷售數(shù)據(jù)分析報告, start_time: 2025-01-15T14:30:22, end_time: 2025-01-15T14:35:47, total_duration_seconds: 325, subtasks: [ { id: task_1, stage: data_preparation, status: completed, duration_seconds: 120, retry_count: 0 }, { id: task_2, stage: analysis, status: completed, duration_seconds: 150, retry_count: 1 }, { id: task_3, stage: reporting, status: completed, duration_seconds: 55, retry_count: 0 } ], issues: [] }有了這份日志出問題時可以快速定位到具體環(huán)節(jié)。比如上面這個例子task_2重試了一次說明分析階段可能遇到了數(shù)據(jù)格式問題下次可以針對性優(yōu)化。5. 常見問題與排查技巧實錄5.1 Agent 之間上下文丟失怎么辦這是多 Agent 系統(tǒng)里最常見的問題。表現(xiàn)是下游 Agent 的輸出明顯偏離了上游的意圖或者重復問了上游已經(jīng)解決的問題。根本原因通常是 Handoff 文檔寫得太簡略或者關鍵信息沒有結構化地傳遞。我踩過的一個典型坑是Agent A 在清洗數(shù)據(jù)時刪除了某列但沒有在 Handoff 文檔里說明結果 Agent B 在分析時找不到這列直接報錯。解決方案是強制要求 Handoff 文檔包含“變更清單”字段明確列出所有對數(shù)據(jù)的修改操作。同時下游 Agent 在開始工作前必須先校驗輸入物是否符合預期如果不符合立即回退并說明原因。我現(xiàn)在的做法是在AGENTS.md里加一條硬性規(guī)則任何 Agent 在修改輸入數(shù)據(jù)后必須在 Handoff 文檔的“變更清單”中逐條記錄修改內(nèi)容、修改原因和影響范圍。下游 Agent 在開始工作前必須核對變更清單確認無誤后才能繼續(xù)。這條規(guī)則加上后上下文丟失的問題減少了 80% 以上。5.2 任務拆解粒度怎么把握拆得太粗單個 Agent 負擔過重容易出錯拆得太細協(xié)調開銷超過任務本身。我的一般原則是每個子任務的執(zhí)行時間控制在 1 到 5 分鐘之間。太短說明拆得過細太長說明還可以繼續(xù)拆。每個子任務有明確的驗收標準。如果說不清楚“做到什么程度算完成”說明拆解還不夠清晰。子任務之間的依賴關系盡量簡單。如果依賴關系復雜到需要畫圖才能理清說明拆解方式有問題應該重新設計。我通常先用粗粒度拆解跑一遍觀察哪個環(huán)節(jié)耗時最長或出錯最多然后針對性地細化那個環(huán)節(jié)。這種“先跑通再優(yōu)化”的方式比一開始就追求完美拆解要高效得多。5.3 Skill 調用失敗的排查思路Skill 調用失敗時我一般按這個順序排查第一步檢查輸入格式。90% 的失敗都是輸入格式不對導致的。用jsonschema之類的工具做嚴格校驗能攔截掉大部分問題。第二步檢查依賴資源。Skill 依賴的文件、API、數(shù)據(jù)庫是否可用我遇到過好幾次因為臨時文件被清理導致 Skill 失敗的情況后來加了資源檢查步驟就解決了。第三步檢查權限。Skill 是否有權限讀寫目標文件是否有權限調用外部服務權限問題在多 Agent 系統(tǒng)里很常見因為不同 Agent 可能運行在不同的權限上下文中。第四步查看詳細日志。如果前三步都沒問題就需要看 Skill 內(nèi)部的執(zhí)行日志了。我一般會在 Skill 的關鍵節(jié)點打日志方便定位問題。下面是我整理的一份常見問題速查表問題現(xiàn)象可能原因排查方法解決方案Skill 返回空結果輸入格式錯誤檢查輸入 schema修正輸入格式Skill 執(zhí)行超時依賴資源不可用檢查文件/API 狀態(tài)恢復資源或使用備用方案Skill 報權限錯誤權限配置不當檢查文件/服務權限調整權限配置Skill 輸出不符合預期提示詞不清晰檢查 Skill 定義優(yōu)化提示詞和約束條件Skill 頻繁重試輸入質量差檢查上游輸出優(yōu)化上游 Agent 的輸出質量5.4 多 Agent 系統(tǒng)的性能優(yōu)化經(jīng)驗系統(tǒng)跑通后下一步就是優(yōu)化性能。我總結了幾條實用的優(yōu)化經(jīng)驗第一并行化無依賴的子任務。如果兩個子任務之間沒有依賴關系就讓它們并行跑。我用asyncio實現(xiàn)并行調度實測下來能把總耗時壓縮 40% 左右。第二緩存重復計算的結果。有些 Skill 的輸出是確定性的同樣的輸入總是得到同樣的輸出。這類 Skill 的結果可以緩存起來下次遇到相同輸入時直接返回緩存結果。第三精簡 Handoff 文檔。Handoff 文檔不是越詳細越好關鍵是傳遞“下游需要知道的信息”。我一般控制在 500 字以內(nèi)超過這個長度就說明可能包含了冗余信息。第四合理設置超時時間。超時時間太短會導致正常任務被誤殺太長會導致問題任務拖慢整個系統(tǒng)。我一般根據(jù)歷史執(zhí)行時間的 P95 值來設置留出 20% 的余量。第五定期清理中間產(chǎn)物。多 Agent 系統(tǒng)跑久了workspace/intermediate/目錄會積累大量臨時文件。我一般設置一個定時任務每天清理超過 7 天的中間產(chǎn)物避免磁盤空間被占滿。5.5 從單 Agent 遷移到多 Agent 的注意事項如果你現(xiàn)在用的是單 Agent想遷移到多 Agent我建議按這個順序來第一步先梳理現(xiàn)有流程。把單 Agent 做的事情拆解成清晰的步驟標注每步的輸入輸出。這一步不需要寫代碼用紙筆或者流程圖工具就行。第二步識別可獨立拆分的環(huán)節(jié)。哪些環(huán)節(jié)是相對獨立的哪些環(huán)節(jié)之間有強依賴優(yōu)先拆分獨立環(huán)節(jié)。第三步先拆一個環(huán)節(jié)試試。不要一次性全拆先拆一個環(huán)節(jié)跑通后再拆下一個。這樣風險可控出問題也容易回滾。第四步建立 Handoff 機制。在拆分之前先把 Handoff 文檔的格式和規(guī)則定好。這是多 Agent 協(xié)作的基礎設施必須先建好。第五步逐步替換。每次替換一個環(huán)節(jié)觀察一段時間確認穩(wěn)定后再替換下一個。全部替換完成后再考慮優(yōu)化整體性能。我自己的經(jīng)驗是從單 Agent 遷移到多 Agent最大的挑戰(zhàn)不是技術而是思維方式的轉變。你需要從“一個 Agent 做所有事”轉變?yōu)椤岸鄠€ Agent 各司其職、互相配合”。這個轉變需要時間但只要跑通第一個多 Agent 項目后面的路就順了。6. 多 Agent 協(xié)作的擴展方向與個人體會6.1 從固定流程到動態(tài)編排目前我用的多 Agent 系統(tǒng)還是以固定流程為主任務拆解和 Agent 分配都是預先定義好的。下一步我想嘗試的是動態(tài)編排根據(jù)任務的實際特點自動決定拆解方式和 Agent 組合。比如同樣是數(shù)據(jù)分析任務如果數(shù)據(jù)量小可能只需要兩個 Agent如果數(shù)據(jù)量大且復雜可能需要五個 Agent。動態(tài)編排的核心是讓系統(tǒng)具備“元認知”能力能夠評估任務難度并做出相應的資源分配決策。我目前的想法是引入一個“評估 Agent”專門負責任務難度評估和資源規(guī)劃。它不直接執(zhí)行任務而是為其他 Agent 提供調度建議。這個思路還在驗證中等跑通了再單獨寫一篇分享。6.2 多 Agent 系統(tǒng)的可觀測性建設系統(tǒng)越復雜可觀測性越重要。我現(xiàn)在正在完善的是多 Agent 系統(tǒng)的監(jiān)控面板希望能實時看到每個 Agent 的狀態(tài)、每個子任務的進度、每個 Skill 的調用情況?？捎^測性建設我分三個層次日志層記錄所有關鍵事件包括 Agent 啟動、任務分配、Skill 調用、錯誤發(fā)生等。指標層統(tǒng)計關鍵指標比如任務完成率、平均執(zhí)行時間、重試率、錯誤率等。追蹤層追蹤單個任務的完整執(zhí)行鏈路從任務創(chuàng)建到最終輸出中間經(jīng)過了哪些 Agent、哪些 Skill、哪些決策。這三個層次建好后排查問題會變得非常高效。以前需要翻半天日志才能定位的問題現(xiàn)在在面板上掃一眼就能發(fā)現(xiàn)異常。6.3 我踩過的三個大坑第一個坑是過度設計。剛開始做多 Agent 時我設計了七個 Agent每個 Agent 負責一個非常細的環(huán)節(jié)。結果協(xié)調開銷巨大系統(tǒng)跑起來比單 Agent 還慢。后來砍到三個 Agent效率反而提升了。教訓是Agent 數(shù)量不是越多越好夠用就行。第二個坑是忽視 Handoff 文檔的質量。早期我覺得 Handoff 文檔就是走個形式隨便寫寫就行。結果下游 Agent 經(jīng)常因為缺少關鍵信息而輸出錯誤結果。后來我把 Handoff 文檔的質量納入驗收標準問題才解決。教訓是Handoff 文檔是多 Agent 系統(tǒng)的生命線必須認真對待。第三個坑是沒有回滾機制。有一次 Agent B 的輸出有問題但系統(tǒng)沒有檢測到繼續(xù)往下跑最后生成了一份完全錯誤的報告。后來我加了校驗和回滾機制任何環(huán)節(jié)發(fā)現(xiàn)問題都能立即中止并回退到上一個穩(wěn)定狀態(tài)。教訓是多 Agent 系統(tǒng)必須有容錯和回滾能力否則錯誤會逐級放大。6.4 給初次嘗試者的實用建議如果你正準備嘗試多 Agent 協(xié)作我最后分享幾條實用建議從簡單任務開始。不要一上來就挑戰(zhàn)復雜項目先找一個兩三個環(huán)節(jié)的小任務跑通流程。跑通后再逐步增加復雜度。先把 Handoff 機制建好。這是多 Agent 協(xié)作的基礎設施不要等到出問題了才想起來補。我一般建議在寫第一個 Agent 之前就把 Handoff 文檔的模板和規(guī)則定好?？刂?Agent 數(shù)量。初次嘗試建議控制在 3 個以內(nèi)跑通后再根據(jù)實際需要增加。Agent 越多協(xié)調開銷越大出問題的概率也越高。重視日志和監(jiān)控。多 Agent 系統(tǒng)的調試比單 Agent 復雜得多沒有完善的日志和監(jiān)控排查問題會非常痛苦。保持耐心。多 Agent 協(xié)作不是一蹴而就的需要反復調試和優(yōu)化。我自己的第一個多 Agent 項目跑了整整兩周才穩(wěn)定下來但穩(wěn)定之后效率提升是實實在在的。這套多 Agent 協(xié)作方案我目前已經(jīng)在三個實際項目中落地使用最長的跑了半年多整體穩(wěn)定性不錯。當然它肯定不是唯一正確的方案不同團隊、不同場景可能需要不同的設計。關鍵是理解背后的核心原理然后根據(jù)自己的實際情況靈活調整。