1. 一開始為什么要做 agency-agents這幾年智能體這個概念被炒得很熱各種框架層出不窮?？晌易约喊阎髁鞣桨付即盍艘槐橹篌w會就一個字虛。表面上都能聊、能調(diào)工具、能多步推理你真拿一個有壓力的真實業(yè)務(wù)過去它就原形畢露了——要么在大模型幻覺里打轉(zhuǎn)要么把一個簡單任務(wù)拆成一堆互相矛盾的子步驟要么壓根不知道什么時候該停手。我的需求其實很樸素做一個真正能自主推進(jìn)任務(wù)的系統(tǒng)而不是prompt 循環(huán) 工具調(diào)用的三件套。項目標(biāo)題里的 agency 不是代理機構(gòu)這個意思而是指智能體的能動性/自主決策能力。所以這個項目叫 agency-agents想做的就是把這種自主性落成一個可工程化、可觀測、可控制的框架。1.1 那些年我用鏈?zhǔn)骄幣诺谋锴趧庸ぶ拔伊?xí)慣性地先盤了一遍已有方案的痛點。最常見的問題是大家把智能體理解成在一個循環(huán)里反復(fù)調(diào)用大模型直到它說做完。聽上去很聰明實際跑起來你會看到它反復(fù)做同一件事或者一次任務(wù)里調(diào)了十幾次模型接口結(jié)果答案還不如一次性直接問來得好。第二個痛點是編排粒度太粗。很多框架把步驟定義成一個大函數(shù)開發(fā)者只需要塞進(jìn)去一個角色設(shè)定剩下全靠模型自由發(fā)揮。業(yè)務(wù)一旦復(fù)雜這個自由發(fā)揮就會變成災(zāi)難。你沒法在某個關(guān)鍵節(jié)點打斷它、修正它也沒法事后復(fù)盤它當(dāng)時為什么選了這條路徑。還有一個非?，F(xiàn)實的問題多智能體協(xié)作基本靠互相甩 prompt。A 智能體把一大段結(jié)果堆給 B 智能體B 再堆給 C鏈越長信息損耗和 token 消耗越離譜。更別提多個智能體同時操作外部資源時連最基本的并發(fā)互斥都沒有。1.2 自主性不是靠多寫幾個 prompt 就能實現(xiàn)的我在設(shè)計 agency-agents 時給自己定了幾條原則后來發(fā)現(xiàn)它們幾乎成了整個項目的地基第一自主性必須建立在顯式任務(wù)圖之上。智能體不是從第一個字開始自由翱翔而是先根據(jù)用戶目標(biāo)做任務(wù)分解再把子任務(wù)組織成一張有依賴關(guān)系的圖。每個節(jié)點都知道自己的輸入、輸出、可用工具和完成條件。這樣它既能自主決定下一步又能被人類在任意節(jié)點插話。第二每個決策都要留痕。大模型本身是黑盒如果系統(tǒng)不主動記錄它選了哪個工具、為什么選、輸入輸出是什么、中間有沒有重試那整個系統(tǒng)就是不可信的。我把決策日志當(dāng)成一等公民而不是事后從 API 調(diào)用記錄里猜。第三一切可以被量化治理。預(yù)算上限、最大步數(shù)、最大分解深度、工具白名單、超時時間這些不能只是配置文件里的擺設(shè)而要在運行時被強制執(zhí)行。自主不等于失控我們要的是在給定邊界內(nèi)的自主。這三條原則聽上去簡單把它們同時落到一個可運行的代碼架構(gòu)里花了我相當(dāng)長的時間。后面幾章我把關(guān)鍵設(shè)計一個個講清楚。2. 核心抽象任務(wù)圖、決策點與可回溯日志agency-agents 的第一版其實并不復(fù)雜我甚至沒有用任何現(xiàn)成的 Agent 框架核心就是三個數(shù)據(jù)結(jié)構(gòu)任務(wù)圖TaskGraph、決策節(jié)點DecisionNode和工具路由ToolRoute。整個運行過程可以概括為用戶目標(biāo)進(jìn)來規(guī)劃器生成任務(wù)圖執(zhí)行器沿著圖推進(jìn)每個節(jié)點上智能體也許要選擇工具、也許要生成子任務(wù)每走一步都寫日志。2.1 從線性鏈條到 DAG讓 Agent 自己決定下一步我見過很多流程編排框架其實只是一根直線步驟一、步驟二、步驟三最多加個 if 分支。真實業(yè)務(wù)里任務(wù)之間往往是依賴關(guān)系而不是先后關(guān)系。比如一個生成競品分析報告的任務(wù)它包含三個子任務(wù)抓取競品頁面、清洗數(shù)據(jù)、寫分析結(jié)論。寫分析結(jié)論依賴清洗后的數(shù)據(jù)但抓取和清洗之間并不是嚴(yán)格的先后關(guān)系——你可以直接抓取原始數(shù)據(jù)也可以先從已有數(shù)據(jù)庫里取。所以我用了一個有向無環(huán)圖DAG來表示任務(wù)。每個節(jié)點有兩種行為模式原子任務(wù)Atomic Task直接調(diào)用某個工具完成比如調(diào)用某搜索接口獲取關(guān)鍵詞 Top 100。復(fù)合任務(wù)Composite Task繼續(xù)向下分解出子圖由規(guī)劃器遞歸處理。規(guī)劃器在生成圖的時候不搞什么都讓大模型自由發(fā)揮的那一套而是先做一次目標(biāo)分析把用戶目標(biāo)拆成幾個語義塊然后做依賴推導(dǎo)決定哪些塊必須先做、哪些可以并行最后做資源綁定給每個塊分配可用的工具和預(yù)期產(chǎn)出。提示DAG 不是越復(fù)雜越好。如果任務(wù)本身只有兩個步驟就老老實實走線性流程別硬拆成五六個節(jié)點。后續(xù)我加了一個最大分解深度參數(shù)默認(rèn)是三層最多五層超過就觸發(fā)詢問用戶的降級動作防止規(guī)劃器把簡單任務(wù)切碎。2.2 決策點記錄每一個為什么都要能在日志里找到答案這是我認(rèn)為整個項目里最值錢的設(shè)計。大多數(shù)框架把模型 API 的 raw response 存下來就算完事但那些內(nèi)容噪聲太大復(fù)盤時根本翻不動。我在每個節(jié)點內(nèi)部增加了三個固定環(huán)節(jié)意圖分析Intent 這一步到底要做什么期望的產(chǎn)出格式是什么工具選擇Tool Selection 當(dāng)前可選工具列表是什么模型選了哪個候選得分是多少結(jié)果評估Evaluation 輸出是否符合 schema 校驗是否觸發(fā)重試重試原因是什么每一次執(zhí)行都會生成一條結(jié)構(gòu)化日志類似{ node_id: report_gen_001, intent: 生成最終分析報告需包含數(shù)據(jù)摘要與異常解釋, selected_tool: report_writer, candidate_tools: [report_writer, code_interpreter, search_engine], input_summary: 清洗后數(shù)據(jù)表共 38 行, output_summary: 報告已生成長度 1200 字, retries: 1, retry_reason: 輸出缺少 異常解釋 段落schema 校驗失敗, cost_usd: 0.023, timestamp: 2025-06-19T08:23:19Z }這條日志不僅用于事后審計它還有一個實時用途當(dāng)重試次數(shù)超過閾值時執(zhí)行器會跳過當(dāng)前決策把問題升級給人類處理。這樣你就不會看到智能體在同一個節(jié)點上糾結(jié)十幾次、燒掉一堆 token 的奇觀。2.3 工具路由不是函數(shù)調(diào)用而是候選列表篩選另一個容易出問題的點是工具調(diào)用。很多框架喜歡做function calling直接把模型的輸出映射到 Python 函數(shù)。這聽上去很順但模型經(jīng)常瞎編參數(shù)或者在一個不需要工具的上下文里強行調(diào)用工具。我在設(shè)計工具路由時沒有走直接映射這條路而是先讓模型從候選列表里選選完再做參數(shù)補全和校驗第一步模型返回一個工具的標(biāo)識符比如工具 ID而不是一大段 JSON 參數(shù)。第二步系統(tǒng)從工具注冊表里取出該工具的 JSON Schema讓模型基于這個 Schema 生成參數(shù)。第三步參數(shù)必須通過 pydantic 校驗不過就再給一次機會再不過就詢問用戶。這個設(shè)計的額外收益是模型不需要記住每個工具的完整參數(shù)格式它只需要知道這個工具能干什么、大概需要哪幾類信息。參數(shù)生成在被驗證過的 Schema 約束下進(jìn)行輸出質(zhì)量會穩(wěn)很多幻覺參數(shù)的概率明顯下降。3. 多 Agent 協(xié)作消息隊列、資源租約與記憶隔離單 Agent 的問題解決了多 Agent 才是真正的硬骨頭。agency-agents 里支持同時跑多個智能體比如一個負(fù)責(zé)數(shù)據(jù)采集、一個負(fù)責(zé)數(shù)據(jù)分析、一個負(fù)責(zé)寫作。如果讓它們各跑各的、最后拼起來你會發(fā)現(xiàn)協(xié)作兩個字根本不成立——因為它們之間沒有共同語言。3.1 為什么不能讓 Agent 之間直接互相傳大段文本最開始我的方案很簡單A 智能體把結(jié)果作為一段長文本塞給 B 智能體B 看完再干活。結(jié)果遇到了兩個大問題。第一是 token 消耗爆炸一份數(shù)據(jù)表如果直接渲染成文本傳過去一次就得吃掉幾千 token多傳幾輪任務(wù)還沒做完賬單先瘋了。第二是上下文污染B 智能體分不清哪些是 A 的最終結(jié)論、哪些是 A 的過程困惑容易被無關(guān)信息帶偏。后來我改成消息隊列 結(jié)構(gòu)化數(shù)據(jù)包的模式。智能體之間的通信不再傳輸對話文本而是傳輸一個帶有明確 schema 的數(shù)據(jù)包task_id屬于哪個父任務(wù)sender/receiver誰發(fā)的、誰接收payload_type數(shù)據(jù)類型比如table_chunk、summary_section、search_resultspayload_ref指向某個數(shù)據(jù)存儲位置的引用而不是直接塞大對象ttl這個包的有效時間過期自動丟棄B 智能體拿到的是引用 元信息而非整段文本。它需要具體數(shù)據(jù)的時候再通過專門的數(shù)據(jù)讀取工具去取。這個改動讓多智能體協(xié)作從人傳話變成了倉庫調(diào)度信息失真和 token 浪費同時下降。3.2 資源租約避免兩個 Agent 搶同一個文件多智能體并發(fā)操作外部資源的時候一定會遇到鎖問題。比如數(shù)據(jù)采集智能體和數(shù)據(jù)清洗智能體可能同時訪問某個緩存文件如果沒有互斥機制會出現(xiàn)半寫狀態(tài)或者臟讀。我早期用過一個笨辦法讓第二個智能體重試。等一會兒再讀也許就好了——事實證明這個辦法在大多數(shù)情況下只是把問題延后。最后我引入了一個非常簡單的資源租約表本質(zhì)就是一個 SQLite 表每次工具要訪問共享資源前先申請租約CREATE TABLE resource_leases ( resource_key TEXT PRIMARY KEY, lease_holder TEXT NOT NULL, expires_at TIMESTAMP NOT NULL, created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP );工具訪問資源的流程變成先嘗試申請租約成功則執(zhí)行操作完成后釋放失敗則等待并重試超過等待上限就把節(jié)點標(biāo)記為blocked等待人工協(xié)調(diào)。這個表排除了死鎖的可能因為租約一定有截止時間不會出現(xiàn)等到天荒地老的情況。3.3 記憶要分賬本會話隔離與長期知識的取舍做過智能體的人都知道記憶是個雙刃劍。讓智能體記住上一輪對話它能提供更好的上下文讓它記住太多歷史它就開始混淆邊界、把舊任務(wù)的信息套到新任務(wù)上。我在設(shè)計記憶機制的時候用了三本賬會話記憶Ephemeral只在當(dāng)前 run 內(nèi)有效任務(wù)結(jié)束自動清空。存放節(jié)點之間的臨時輸出。項目記憶Project同一個項目下共享帶版本號。比如這個任務(wù)的圖結(jié)構(gòu)怎么生成的上一次失敗在哪里。長期知識Long-term寫入獨立的向量庫但每次寫入必須經(jīng)過一個知識提煉步驟把原始信息壓縮成結(jié)構(gòu)化條目并記錄來源。核心的取舍是智能體永遠(yuǎn)不要直接讀歷史對話原文只允許讀提煉后的知識條目。這樣做避免了上下文污染也降低了 token 成本。4. 一個完整的實測案例自動生成競品監(jiān)測日報理論說了一堆還是上一個完整的案例來講。假設(shè)我們老大要求每天上午十點自動產(chǎn)出一份競品監(jiān)測日報內(nèi)容包括三家競品網(wǎng)站當(dāng)天是否有更新、有哪些新變化、這些變化對我們應(yīng)該意味著什么、以及三條運營建議。這個任務(wù)看起來不復(fù)雜但前提是每天自動跑任何一步出問題都得知道自己怎么修復(fù)。4.1 先把任務(wù)拆解清楚用 agency-agents 搭建之前我先把這個目標(biāo)拆成了任務(wù)圖數(shù)據(jù)采集節(jié)點 抓取三家競品的公開頁以及兩個行業(yè)信息來源輸出原始 HTML 或 RSS 條目。結(jié)構(gòu)化節(jié)點 從原始數(shù)據(jù)里抽取時間、標(biāo)題、摘要、鏈接四要素存為news_items表。分析節(jié)點 基于news_items生成 DIFF 對比重點標(biāo)記新增關(guān)鍵詞價格變動新上架功能。寫作節(jié)點 基于分析結(jié)果生成日報文本要求附上數(shù)據(jù)來源鏈接。交付節(jié)點 調(diào)用郵件接口發(fā)送給指定收件人并在內(nèi)部看板上創(chuàng)建一條任務(wù)記錄。這里沒有用線性步驟因為采集節(jié)點和結(jié)構(gòu)化節(jié)點可以部分并行而且寫作節(jié)點依賴的是分析結(jié)果而非原始數(shù)據(jù)這個依賴關(guān)系只有 DAG 才能清晰表達(dá)。規(guī)劃器在運行時自動生成了這張圖我只在配置里給了它數(shù)據(jù)源、產(chǎn)出物、發(fā)送對象這些邊界信息。4.2 代碼骨架三個核心類怎么協(xié)作架構(gòu)層面只寫了三個核心類整體邏輯不算復(fù)雜class Coordinator: def __init__(self, planner, executor): self.planner planner self.executor executor def run(self, objective: str, context: dict) - RunResult: task_graph self.planner.plan(objective, context) execution_log self.executor.execute(task_graph) return RunResult(graphtask_graph, logexecution_log) class Planner: def plan(self, objective: str, context: dict) - TaskGraph: subtasks self._decompose(objective, context) dependencies self._resolve_dependencies(subtasks) return TaskGraph(subtaskssubtasks, dependenciesdependencies) class Executor: def execute(self, graph: TaskGraph) - ExecutionLog: for node in graph.ordered_nodes(): if node.is_compound() and node.needs_decomposition(): node.graph self.planner.plan(node.description, node.context) self._run_node(node) return ExecutionLog(...)注意這里的ordered_nodes()不是簡單的拓?fù)渑判?。它還要考慮哪些節(jié)點可以并行執(zhí)行、哪些節(jié)點目前處于 blocked 狀態(tài)需要跳過。執(zhí)行器有一個工作線程池并行節(jié)點會被分到不同線程互不依賴的節(jié)點能同時跑。4.3 實際跑起來之后的幾個意外第一個意外是規(guī)劃器把結(jié)構(gòu)化節(jié)點和分析節(jié)點合并成了一個因為這兩個節(jié)點之間只隔了一個字段轉(zhuǎn)換模型判斷沒必要分開。這個行為本身合理但也暴露出一個問題模型過度合并會犧牲可觀測性。后來我加了規(guī)則要求任意兩個節(jié)點之間如果存在數(shù)據(jù)格式轉(zhuǎn)換或語義理解就必須保持獨立不能合并。第二個意外是采集節(jié)點反復(fù)請求同一個頁面因為前一次請求超時了。原始的設(shè)計里沒有去重緩存的概念導(dǎo)致同一個 URL 被請求了三次。后來我加了請求級緩存和冪等鍵同一任務(wù)內(nèi)相同參數(shù)的請求直接返回緩存結(jié)果成本馬上就下來了。第三個意外是寫作節(jié)點生成的日報里引用了結(jié)構(gòu)化節(jié)點里不存在的數(shù)據(jù)編號。這個屬于典型的模型幻覺輸入錯位最后通過斷言工具解決寫作節(jié)點在輸出日報前會自動檢查報告里引用的所有編號是否存在于數(shù)據(jù)源中不過斷言就重新生成最多重試兩次。實際效果很好之后幾乎沒有出現(xiàn)過無中生有的引用。5. 護(hù)欄與失敗降級讓自主系統(tǒng)不作死自主系統(tǒng)最怕的不是能力不夠而是能力夠但行為不可控。我給 agency-agents 設(shè)計護(hù)欄的時候參考的是彈幕游戲里那種保命機制你可以在邊界內(nèi)隨便操作但一旦越界系統(tǒng)立刻接管。5.1 成本上限與 Token 預(yù)算實時攔截大模型不是無限便宜的尤其一個長時間運行的多智能體系統(tǒng)一天跑下來成本控制不好真的會嚇人。我的做法是三層預(yù)算第一層是總預(yù)算這個 run 最多允許消耗多少費用超了直接停止并告知用戶任務(wù)因為預(yù)算不足被終止。第二層是節(jié)點預(yù)算每個節(jié)點有自己的 token 上限。比如結(jié)構(gòu)化節(jié)點預(yù)計最多輸入 2000 輸出 1000 token實測超過 4 倍就判定為異常觸發(fā)重規(guī)劃。第三層是實時攔截器每次調(diào)用大模型前庫里存有這個節(jié)點的歷史調(diào)用耗費的計數(shù)如果本次預(yù)計 token 已消耗 token 會超過節(jié)點預(yù)算攔截器會先拒絕這次調(diào)用而不是等到賬單出來再后悔。預(yù)算這個東西寧可設(shè)小一點頻繁補充也不要一開始設(shè)得很大指望模型節(jié)制。模型一點都不節(jié)制它只會想著完成任務(wù)不會替你心疼錢。5.2 失敗降級路徑從工具摘除到詢問用戶一個節(jié)點失敗了怎么辦很多框架的做法是重試 N 次然后掛掉。這個體驗很糟糕尤其對于無人值守的任務(wù)。我設(shè)計了四級降級路徑重試如果是臨時錯誤網(wǎng)絡(luò)抖動、API 超時等待后重試上限三次。換工具如果當(dāng)前工具持續(xù)失敗嘗試用同一意圖下的其他工具替代。比如搜索工具掛了就切換到站點抓取工具 提取摘要的組合方案。重規(guī)劃如果工具都不可用說明任務(wù)目標(biāo)本身有問題規(guī)劃器基于已獲得的部分?jǐn)?shù)據(jù)重新分解任務(wù)縮小目標(biāo)范圍。詢問用戶以上都失敗暫停任務(wù)生成一份帶上下文的問詢請求等待人類決定是跳過、修改目標(biāo)還是終止。這套降級路徑救了我很多次。尤其是在外部接口不穩(wěn)定的時候任務(wù)不會直接掛掉而是自動切換數(shù)據(jù)集繼續(xù)完成最后生成的報告里會明確標(biāo)注某數(shù)據(jù)源未更新使用了備選方案。讀者至少能知道數(shù)據(jù)里哪部分可信。5.3 逃逸檢測自循環(huán)、重復(fù)舊模式、工具調(diào)幻覺自主系統(tǒng)最容易被吐槽的問題就是跑飛了。我在執(zhí)行器里內(nèi)置了三個逃逸檢測器循環(huán)檢測如果連續(xù)五個節(jié)點的輸出高度相似用向量相似度判斷判定為自循環(huán)中斷并觸發(fā)重規(guī)劃。動作熵檢測如果一個任務(wù)在十個以上節(jié)點之間反復(fù)切換但整體目標(biāo)沒有任何進(jìn)展說明規(guī)劃可能失控觸發(fā)詢問用戶。參數(shù)幻覺檢測工具調(diào)用時如果參數(shù)與當(dāng)前上下文完全不相關(guān)比如分析金融報告時突然調(diào)用天氣查詢工具直接拒絕并記錄。這三個檢測器都是純代碼實現(xiàn)的沒有依賴額外的模型調(diào)用幾乎零成本。它們的意義在于把智能體沒問題從一種信念變成一種可驗證的斷言。每次任務(wù)結(jié)束時我會跑一份系統(tǒng)自檢報告列出所有節(jié)點是否越過護(hù)欄方便復(fù)盤。6. 關(guān)于什么時候不要用 Agent 方案的一點嘮叨做完這個項目之后我最大的收獲不是代碼而是一個反過來的認(rèn)知不是所有任務(wù)都適合做智能體。如果你手上是一個流程相對固定、步驟不超過五個、輸入輸出模式很明確的業(yè)務(wù)直接寫函數(shù)編排就是最優(yōu)解——便宜、穩(wěn)定、好調(diào)試。智能體方案適合的是那些目標(biāo)明確但路徑不確定的事比如開放性的調(diào)研、跨數(shù)據(jù)源的綜合分析、需要根據(jù)實時進(jìn)展調(diào)整方案的任務(wù)。我內(nèi)部已經(jīng)形成了一張表用來快速做技術(shù)選型判斷任務(wù)特征建議方案理由單一固定流程步驟小于 5傳統(tǒng)代碼流程便宜、可控、無需調(diào)試智能體部分節(jié)點需要模型理解上下文局部小模型節(jié)點只把語義理解交給模型其余保持代碼確定性路徑不固定且需要動態(tài)決策智能體方案任務(wù)圖動態(tài)生成的價值大多數(shù)據(jù)源 多角色協(xié)作智能體 消息隊列松耦合單點失敗不影響全局預(yù)算極其敏感毫厘必爭別用智能體的 token 成本開銷遠(yuǎn)大于固定流程寫到這里agency-agents 已經(jīng)穩(wěn)定跑了快兩個月我團隊里的日報生成行業(yè)調(diào)研數(shù)據(jù)異常復(fù)盤都遷移到了它上面。說句實話它沒有多炫酷核心代碼甚至有點樸素——一個任務(wù)圖、一套決策日志、三個護(hù)欄檢測器、一個消息隊列。但正是這些樸素的東西讓自主性從一句口號變成了可以審計、可以干預(yù)、可以控制的工程事實。最后分享一個經(jīng)驗如果你也在做類似的事先別急著寫代碼。把你手頭最熟悉的一個業(yè)務(wù)拿下來拆成任務(wù)圖跑通一遍再考慮通用化。直接搭一個大而全的平臺大概率會卡在你根本不知道哪些抽象是必要的這個階段。從真實的業(yè)務(wù)長出框架才是最有生命力的路徑。