聊 Agent 的文章這半年多太多了但大部分停在概念層要么講 Prompt 技巧要么貼個(gè)框架 Demo。我這篇不太一樣想從一個(gè)實(shí)際做過(guò)的工程角度把 Agent 系統(tǒng)這套東西掰開(kāi)揉碎講清楚它到底解決什么問(wèn)題、理想形態(tài)長(zhǎng)什么樣、框架怎么選、代碼怎么寫(xiě)、坑在哪里。文章后半部分還會(huì)給一個(gè)真實(shí)落地的完整拆解包括工具 Schema、ReAct 循環(huán)、記憶接入和評(píng)測(cè)方案你可以直接照著搭。先交代一個(gè)反常識(shí)的結(jié)論Agent 系統(tǒng)最大的難點(diǎn)不在模型而在工程。模型選型、提示詞編排這些東西兩三天就能上手真正難的是把記憶、工具、編排、安全和評(píng)測(cè)這幾層結(jié)構(gòu)搭穩(wěn)讓系統(tǒng)在真實(shí)業(yè)務(wù)里不失控、不燒錢(qián)、可排查。這篇就按這個(gè)思路展開(kāi)。1. 先想清楚Agent 到底是一套什么系統(tǒng)1.1 別被概念帶偏Agent 的核心是決策閉環(huán)講 Agent 之前先把概念校準(zhǔn)一下。現(xiàn)在市面上很多號(hào)稱(chēng) Agent 的產(chǎn)品本質(zhì)上是把 Prompt 寫(xiě)得很唬人讓模型按照固定格式輸出 JSON外邊再包一層 if-else。這類(lèi)東西不是不能用但它缺了 Agent 最核心的東西自主決策循環(huán)。真正的 Agent 系統(tǒng)至少要滿(mǎn)足三個(gè)特征。第一它能感知環(huán)境比如拿到用戶(hù)任務(wù)、看到工具返回的狀態(tài)第二它能做決策決定下一步調(diào)用哪個(gè)工具、按什么順序執(zhí)行第三它能根據(jù)結(jié)果修正把工具返回的數(shù)據(jù)喂回模型繼續(xù)推理直到任務(wù)完成或者觸發(fā)終止條件。這個(gè)閉環(huán)一旦成立系統(tǒng)就能處理那些沒(méi)有標(biāo)準(zhǔn)答案、步驟不固定的任務(wù)。這也是 Agent 和傳統(tǒng)工作流最本質(zhì)的區(qū)別——工作流是預(yù)先把每一步寫(xiě)死Agent 是讓模型自己走流程。我判斷一個(gè)需求要不要上 Agent就提一個(gè)問(wèn)題任務(wù)的步驟是否固定如果固定用傳統(tǒng)工作流引擎更穩(wěn)省 token、好排查、行為可控如果步驟不固定或者各種分支路徑太多這時(shí)候才值得考慮 Agent。很多團(tuán)隊(duì)一開(kāi)始就把架構(gòu)想復(fù)雜了恨不得第一版就上多 Agent、上復(fù)雜記憶結(jié)果后面調(diào)試起來(lái)極其痛苦。我的經(jīng)驗(yàn)是能用規(guī)則解決的就用規(guī)則模型只在規(guī)則的間隙里做決策這樣系統(tǒng)才抗造。還有一個(gè)容易被忽略的點(diǎn)執(zhí)行層的存在。很多項(xiàng)目做到模型生成計(jì)劃就停了沒(méi)有真正調(diào)用外部系統(tǒng)因?yàn)檎{(diào)用意味著權(quán)限、沙箱、審批、超時(shí)這些工程負(fù)擔(dān)。但恰恰是執(zhí)行層決定了一個(gè) Agent 是會(huì)說(shuō)話(huà)的文檔還是能干活的系統(tǒng)。我堅(jiān)持的原則是沒(méi)有實(shí)際副作用的決策循環(huán)不算 Agent。1.2 方法論從業(yè)務(wù)閉環(huán)倒推而不是從框架倒推我見(jiàn)過(guò)太多失敗項(xiàng)目開(kāi)頭就錯(cuò)了團(tuán)隊(duì)先選好 LangChain 或者 Dify然后才開(kāi)始想用它做什么。正確順序是反過(guò)來(lái)的——先畫(huà)出任務(wù)閉環(huán)再?zèng)Q定哪些環(huán)節(jié)交給模型哪些交給規(guī)則哪些留給人工。舉一個(gè)我自己做過(guò)的例子。我們要做一個(gè)智能客服加工單處理的 Agent用戶(hù)輸入是一句自然語(yǔ)言問(wèn)題最終輸出是解決方案文本 一條已創(chuàng)建的工單 歸檔摘要。把這條鏈路拆開(kāi)依次是意圖識(shí)別、知識(shí)檢索、方案生成、工單創(chuàng)建、異常升級(jí)。拆到這里架構(gòu)需求就很清楚了需要一個(gè)規(guī)劃器一個(gè)檢索工具一個(gè)工單工具一個(gè)人工審批節(jié)點(diǎn)。每一步用什么模型、要不要調(diào) RAG都是直接從業(yè)務(wù)需求反推出來(lái)的而不是框架決定的。方法論的第二個(gè)要點(diǎn)是從最小可跑閉環(huán)開(kāi)始。不要第一步就搞長(zhǎng)鏈路、復(fù)雜記憶、多 Agent 編排先拿一個(gè)模型 兩個(gè)工具 一個(gè)終止條件跑通一遍讓真實(shí)用戶(hù)用一版再往里加能力。我做工程這多年越來(lái)越認(rèn)同一個(gè)說(shuō)法Agent 系統(tǒng)是長(zhǎng)出來(lái)的不是設(shè)計(jì)出來(lái)的。這和寫(xiě)傳統(tǒng)單體軟件的心態(tài)完全相反傳統(tǒng)軟件講究先架構(gòu)后編碼Agent 系統(tǒng)講究先跑通再生長(zhǎng)。因?yàn)槟Ｐ偷男袨槟銢](méi)法在設(shè)計(jì)階段完全預(yù)測(cè)只有跑起來(lái)才發(fā)現(xiàn)工具描述哪里寫(xiě)反了、上下文在哪里丟失了、哪類(lèi)問(wèn)題它天生就處理不了。1.3 理想形態(tài)不是一張架構(gòu)圖是一組取舍原則很多人喜歡看架構(gòu)圖但架構(gòu)圖其實(shí)是最終結(jié)果真正值錢(qián)的是背后的取舍原則。Agent 系統(tǒng)的理想形態(tài)并不是組件越多越高級(jí)、也不是越自動(dòng)化越好而是每一層都有明確的邊界和可控的出口。幾個(gè)我長(zhǎng)期堅(jiān)持的原則直接分享在這里。第一模型負(fù)責(zé)不確定的推理系統(tǒng)負(fù)責(zé)確定的事實(shí)第二所有工具調(diào)用必須可追蹤、可回滾高副作用操作必須有人在環(huán)第三記憶必須分層不能指望一個(gè)上下文窗口裝下所有東西第四永遠(yuǎn)有終止條件包括最大輪數(shù)、超時(shí)、預(yù)算上限第五評(píng)測(cè)不是上線(xiàn)之后再做而是從第一天就有的回放機(jī)制。這幾條原則貫穿了我在正文后面講的所有設(shè)計(jì)也是我后來(lái)評(píng)估別人的 Agent 架構(gòu)時(shí)最先看的幾點(diǎn)。接下來(lái)就進(jìn)入理想形態(tài)的分層拆解。2. 理想形態(tài)拆解一個(gè) Agent 系統(tǒng)應(yīng)該有哪些層2.1 五要素目標(biāo)、規(guī)劃、記憶、工具、執(zhí)行我把一個(gè)合格的 Agent 系統(tǒng)抽象成五個(gè)要素目標(biāo)、規(guī)劃、記憶、工具、執(zhí)行。目標(biāo)是指系統(tǒng)必須理解用戶(hù)真正想達(dá)成的結(jié)果而不是停留在禮貌回復(fù)。比如用戶(hù)說(shuō)幫我把上周的周報(bào)整理出來(lái)發(fā)給 leader目標(biāo)不是生成一段周報(bào)文本而是創(chuàng)建版本、寫(xiě)入內(nèi)容、調(diào)起發(fā)送動(dòng)作這一條完整鏈路。規(guī)劃是把目標(biāo)拆成一串可執(zhí)行的步驟也就是 task planning模型需要知道做完第一步之后第二步依賴(lài)什么狀態(tài)。記憶是混合體既包含當(dāng)前對(duì)話(huà)的短期上下文也包含長(zhǎng)期存儲(chǔ)的知識(shí)和歷史摘要。工具是系統(tǒng)與外部世界交互的接口比如檢索庫(kù)、API、代碼解釋器。執(zhí)行是把規(guī)劃真正落地的過(guò)程包含權(quán)限控制、超時(shí)處理、結(jié)果回傳。這五個(gè)要素映射到架構(gòu)上自然就分成規(guī)劃編排層、記憶層、工具層、執(zhí)行層加上橫切整個(gè)系統(tǒng)的安全層和觀(guān)測(cè)層。你回頭看 LangChain 的 agent、tool、memory、callback 這些模塊其實(shí)就是這五大塊的工程化包裝。理解這層對(duì)應(yīng)關(guān)系之后你再去看任何框架都不會(huì)被它繞暈因?yàn)樗锌蚣鼙举|(zhì)上都在做同一件事讓模型在一個(gè)可控的循環(huán)里調(diào)用外部能力。2.2 記憶層短期窗口、長(zhǎng)期向量庫(kù)、工作記憶與摘要策略記憶是 Agent 工程里最大的坑沒(méi)有之一。LLM 的上下文窗口再大也扛不住多輪工具調(diào)用之后的信息堆疊。上下文一旦爆炸模型會(huì)開(kāi)始忽略早期的關(guān)鍵信息回復(fù)質(zhì)量直線(xiàn)下滑token 費(fèi)用也不可控。我的做法是把記憶拆成三層。第一層是短期記憶直接放在 message 列表里但必須做窗口裁剪。我一般只保留最近 3 到 5 輪原始消息更早的內(nèi)容交給第二層。第二層是長(zhǎng)期記憶用向量庫(kù)存歷史的語(yǔ)義摘要每個(gè)會(huì)話(huà)按時(shí)間切成若干塊每塊壓縮成摘要文本存進(jìn)去。第三層是工作記憶專(zhuān)門(mén)保存任務(wù)過(guò)程中的結(jié)構(gòu)化狀態(tài)比如訂單號(hào)、當(dāng)前步驟序號(hào)、已經(jīng)完成的工具列表。這類(lèi)數(shù)據(jù)絕對(duì)不要扔進(jìn)語(yǔ)義檢索里應(yīng)該單獨(dú)額度 KV 存儲(chǔ)用精確的鍵值去讀。實(shí)際調(diào)優(yōu)下來(lái)我發(fā)現(xiàn)摘要策略比向量庫(kù)更值錢(qián)。把長(zhǎng)時(shí)間對(duì)話(huà)每隔幾輪做一次壓縮摘要比把所有原文塞進(jìn)向量庫(kù)要經(jīng)濟(jì)得多也準(zhǔn)確得多。原因是 Agent 在每一步?jīng)Q策時(shí)真正需要的往往是上一階段我們完成到什么程度、結(jié)論是什么而不是全部原文。全文召回反而經(jīng)常召回到噪聲干擾模型判斷。這個(gè)經(jīng)驗(yàn)是我在一個(gè)連續(xù) 40 輪工具調(diào)用的任務(wù)里踩出來(lái)的那次之后我把對(duì)話(huà)摘要的觸發(fā)頻率從 20 輪調(diào)到了 10 輪失敗率明顯下降。摘要有它的必殺坑不能丟結(jié)構(gòu)化字段。任務(wù)編號(hào)、用戶(hù) ID、金額這類(lèi)字段一旦被壓縮掉模型后面就會(huì)失憶所以摘要模板里我會(huì)強(qiáng)制保留這些字段的位置。2.3 工具層與技能層Function Calling 和技能抽象工具層定義了 Agent 的能力邊界。沒(méi)有工具模型只能空談?dòng)辛斯ぞ吣Ｐ筒庞惺?。工程上一個(gè)工具的本質(zhì)是一份描述 一個(gè)可執(zhí)行函數(shù)描述是給模型看的函數(shù)是給執(zhí)行層調(diào)的。拿當(dāng)前主流的 function calling 來(lái)說(shuō)模型會(huì)在推理時(shí)輸出一個(gè)結(jié)構(gòu)化的 tool_calls 對(duì)象里面包含函數(shù)名和參數(shù)系統(tǒng)按參數(shù)真實(shí)調(diào)用外部系統(tǒng)再把結(jié)果返回給模型繼續(xù)推理。這里有幾個(gè)細(xì)節(jié)直接決定工具層好不好用。工具描述里必須寫(xiě)清楚什么時(shí)候用、什么時(shí)候別用比如一個(gè)搜索知識(shí)庫(kù)的工具描述要寫(xiě)明它只回答公司內(nèi)部文檔問(wèn)題不做通用問(wèn)答否則模型會(huì)把所有問(wèn)題都甩給它。參數(shù)定義最好用嚴(yán)格的 JSON Schema模型會(huì)照著 schema 填參數(shù)字段名寫(xiě)模糊了很容易得到空值。工具返回結(jié)果一定要截?cái)辔彝ǔＶ槐Ａ羟?2000 字符防止大段無(wú)關(guān)輸出污染后續(xù)推理同時(shí)也省 token。再往上一層是技能抽象這是現(xiàn)在越來(lái)越流行的做法。一個(gè)數(shù)據(jù)分析技能可能包含執(zhí)行 SQL、畫(huà)圖表、生成結(jié)論三個(gè)工具模型按技能粒度去選擇把原來(lái)幾百個(gè)小工具收斂成十幾個(gè)技能調(diào)用穩(wěn)定性和可維護(hù)性都會(huì)大幅提升。Claude 的 Agent Skills、OpenAI 的 Agents SDK 里的 skill 概念本質(zhì)上都是這個(gè)思路。這里也順便回答一個(gè)經(jīng)常被問(wèn)的問(wèn)題為什么有人用 Rust 做 Agent 框架因?yàn)?Rust 在高并發(fā)、低延遲的工具調(diào)度和沙箱隔離上有天然優(yōu)勢(shì)適合做底層的 Agent Harness。但對(duì)大多數(shù)業(yè)務(wù)團(tuán)隊(duì)來(lái)說(shuō)Python 生態(tài)的迭代速度仍然是第一位的語(yǔ)言選擇要看你的瓶頸在性能還是開(kāi)發(fā)效率。2.4 編排層ReAct 循環(huán)、Harness 與多 Agent 觸發(fā)條件編排層負(fù)責(zé)決策循環(huán)的具體執(zhí)行。最經(jīng)典的范式是 ReAct也就是 Reason Act。流程可以概括成模型思考下一步 - 輸出文本或工具調(diào)用 - 系統(tǒng)執(zhí)行工具 - 返回觀(guān)察結(jié)果 - 模型繼續(xù)思考 - 直到輸出最終答案或達(dá)到終止條件。很多框架里的 AgentExecutor、AgentRunner干的就是這個(gè)循環(huán)的封裝。它不是一個(gè)復(fù)雜的東西核心就是一個(gè) for 循環(huán)加終止條件判斷。真正要用心設(shè)計(jì)的是循環(huán)外面的約束也就是通常說(shuō)的 Agent Harness。Harness 像韁繩用來(lái)限制模型的自由度防止它在錯(cuò)誤的路徑上無(wú)限打轉(zhuǎn)。最基本的配置包括最大迭代輪數(shù)、單次工具調(diào)用超時(shí)、整體會(huì)話(huà)超時(shí)、人工中斷機(jī)制。我給絕大多數(shù)任務(wù)設(shè)置的默認(rèn)值是最多 12 輪、單工具 15 秒超時(shí)、整體任務(wù) 60 秒上限。沒(méi)有這些約束的 Agent要么在死循環(huán)里燒錢(qián)要么卡在一個(gè)外部調(diào)用上讓整個(gè)會(huì)話(huà)僵死。多 Agent 編排是單 Agent 跑通之后才需要考慮的事。為什么這么說(shuō)因?yàn)槎嘁馕吨鴽Q策路徑更多、狀態(tài)同步更難、調(diào)試復(fù)雜度指數(shù)上升。我只有在三種信號(hào)同時(shí)出現(xiàn)時(shí)才會(huì)上多 Agent任務(wù)有明顯專(zhuān)業(yè)分工比如一個(gè)研究型 Agent 和一個(gè)執(zhí)行型 Agent有并行處理多路信息的需求存在天然的角色對(duì)沖比如生成者與質(zhì)檢者。常見(jiàn)編排模式有 Supervisor 統(tǒng)一調(diào)度、Hierarchical 分層管理、Pipeline 鏈?zhǔn)搅鬓D(zhuǎn)、Debate 多角色討論。但我的初始默認(rèn)永遠(yuǎn)是先單 Agent 跑業(yè)務(wù)確定瓶頸是上下文混亂或者模型角色沖突再拆成多 Agent。一上來(lái)就上多 Agent 的團(tuán)隊(duì)往往是在用系統(tǒng)的復(fù)雜度換取架構(gòu)圖的漂亮。2.5 安全與沙箱層給 Agent 畫(huà)紅線(xiàn)的六個(gè)方向Agent 安全的特殊之處在于一個(gè)有自主性的軟件要去調(diào)外部系統(tǒng)而且是模型自己在做決策。因此安全設(shè)計(jì)不能靠約定要靠結(jié)構(gòu)。我總結(jié)了六個(gè)必做項(xiàng)。第一權(quán)限最小化。Agent 持有的 API Key 只給必要權(quán)限絕不能給數(shù)據(jù)庫(kù)全局權(quán)限這個(gè)聽(tīng)起來(lái)像廢話(huà)但我見(jiàn)過(guò)不止一次事故。第二命令沙箱。凡是模型要執(zhí)行的代碼一律丟進(jìn) Docker 或者輕量級(jí)虛擬機(jī)里跑網(wǎng)絡(luò)按需放行默認(rèn)拒絕出網(wǎng)。第三工具準(zhǔn)入白名單。工具層只放行已經(jīng)過(guò)審的 API沒(méi)有登記注冊(cè)的一律拒絕模型沒(méi)有權(quán)限調(diào)用未知接口。第四人工確認(rèn)節(jié)點(diǎn)。付款、發(fā)郵件、刪數(shù)據(jù)、創(chuàng)建對(duì)外工單這類(lèi)高副作用操作必須配置人工審批Agent 只能提交請(qǐng)求不能直接執(zhí)行。第五審計(jì)日志。每一步模型輸出、工具參數(shù)、返回結(jié)果、最終狀態(tài)全部落日志出問(wèn)題才有得回溯。第六限流與配額。對(duì)單會(huì)話(huà)、單用戶(hù)的 token 消耗和調(diào)用次數(shù)設(shè)上限超過(guò)直接熔斷。這些都是教訓(xùn)換來(lái)的。我經(jīng)歷過(guò)一個(gè)事故調(diào)試模式下Agent 在一個(gè)錯(cuò)誤循環(huán)里反復(fù)調(diào)分析工具一晚上燒掉了數(shù)千美元的 API 費(fèi)用原因就是沒(méi)配限流和最大輪數(shù)。從那以后這兩項(xiàng)成了所有 Agent 項(xiàng)目的默認(rèn)配置。安全層不用做得多花哨把紅線(xiàn)畫(huà)清楚系統(tǒng)才敢放開(kāi)手腳干活。3. 一次真實(shí)落地從選型到上線(xiàn)的全過(guò)程3.1 框架對(duì)比LangChain、Dify、CrewAI、自研到底怎么選框架選擇直接決定你的開(kāi)發(fā)節(jié)奏和調(diào)試體驗(yàn)。市面上常被提到的四個(gè)方案我全都實(shí)際用過(guò)做個(gè)直接對(duì)比方案優(yōu)點(diǎn)缺點(diǎn)適合場(chǎng)景LangChain生態(tài)最全、組件豐富、抽象靈活版本迭代快、抽象層厚、出問(wèn)題難查需要深度定制的業(yè)務(wù)Dify可視化編排、內(nèi)置 RAG、開(kāi)箱即用可編程性弱、復(fù)雜邏輯受限非工程團(tuán)隊(duì)快速驗(yàn)證CrewAI多 Agent 角色化清晰、上手快復(fù)雜編排和精細(xì)控制不夠多角色、輕邏輯任務(wù)自研編排 裸模型完全可控、調(diào)試直接、依賴(lài)最少工作量大、底層全要自己處理核心業(yè)務(wù)、長(zhǎng)期演進(jìn)我的結(jié)論比較直白如果你是小團(tuán)隊(duì)要做的是內(nèi)部工具直接走自研編排加官方模型 SDK別把核心邏輯外包給框架。如果你要給客戶(hù)快速出 DemoDify 是最快的路徑。如果團(tuán)隊(duì)已經(jīng)有了大模型基建LangChain 可以用但要有隨時(shí)自己寫(xiě)替代層的覺(jué)悟。CrewAI 適合 demo 性質(zhì)的多角色場(chǎng)景真上生產(chǎn)你會(huì)很快碰到它能力邊界。以我自己那次真實(shí)落地為例最終選擇了半自研路線(xiàn)底層模型通信自己封裝編排循環(huán)自己寫(xiě)工具接入自己管理向量庫(kù)和部分工具組件復(fù)用了開(kāi)源庫(kù)。這個(gè)選擇不是炫技純粹是可控性?xún)?yōu)先——框架的抽象層在排障時(shí)太費(fèi)時(shí)間。LangChain 這類(lèi)框架勝在組件多但也意味著你在查問(wèn)題時(shí)要在它的檢索器、回調(diào)、鏈?zhǔn)竭壿嬂锓芫貌蝗缱约旱?200 行循環(huán)看得清爽。3.2 落地需求與方案一個(gè)研發(fā)助手的完整目標(biāo)這次落地的產(chǎn)品是個(gè)內(nèi)部研發(fā)助手核心需求一句話(huà)讓研發(fā)團(tuán)隊(duì)用自然語(yǔ)言少開(kāi)幾個(gè)頁(yè)面。具體來(lái)說(shuō)它要能回答項(xiàng)目背景類(lèi)問(wèn)題能幫員工生成周報(bào)能創(chuàng)建內(nèi)部任務(wù)還能查詢(xún) CI 構(gòu)建狀態(tài)。注意這里刻意不做成萬(wàn)能 AGI只做高頻場(chǎng)景覆蓋目標(biāo)非常明確。系統(tǒng)的核心組件拆分如下。模型層通過(guò)統(tǒng)一網(wǎng)關(guān)調(diào)用不同廠(chǎng)商的模型默認(rèn)主力模型是可以支持復(fù)雜 function calling 的 Claude 系列也兼容 GPT 系列和國(guó)產(chǎn)模型統(tǒng)一封裝在 LLMClient 里服務(wù)上層無(wú)感知。路由層在第一輪做一次意圖分類(lèi)將輸入路由到知識(shí)問(wèn)答子路徑或任務(wù)助手子路徑避免一個(gè) Prompt 包打天下各自路徑的穩(wěn)定性能獨(dú)立調(diào)優(yōu)。工具集一共 6 個(gè)RAG 檢索、創(chuàng)建任務(wù) API、查 CI 狀態(tài)、查詢(xún)用戶(hù)信息、發(fā)送群消息、周報(bào)生成每個(gè)都是獨(dú)立函數(shù)。記憶層采用會(huì)話(huà)窗口裁剪加每 10 輪摘要壓縮入向量庫(kù)。編排層是 ReAct 循環(huán)最大 12 輪整體超時(shí) 60 秒創(chuàng)建任務(wù)這類(lèi)副作用操作必須人工確認(rèn)。部署層用 FastAPI 加 Docker Compose 單機(jī)部署Redis 做會(huì)話(huà)緩存。這個(gè)架構(gòu)最大的特點(diǎn)是簡(jiǎn)單每個(gè)模塊都能單獨(dú)測(cè)試。因?yàn)樗?jiǎn)單后來(lái)加功能才沒(méi)有被一堆框架抽象綁架想加一個(gè)工具就是寫(xiě)一個(gè)函數(shù)再加一份描述想換模型就是改一個(gè)網(wǎng)關(guān)配置。我建議所有中小團(tuán)隊(duì)的第一版都往這個(gè)方向靠先把閉環(huán)搭穩(wěn)。3.3 核心實(shí)現(xiàn)拆解工具 Schema、ReAct 循環(huán)、記憶與人工審批核心實(shí)現(xiàn)里最關(guān)鍵的是工具定義和調(diào)度循環(huán)。先看工具定義我用 Pydantic 的 JSON Schema 來(lái)定義創(chuàng)建任務(wù)接口from pydantic import BaseModel, Field class CreateTaskInput(BaseModel): title: str Field(..., description任務(wù)標(biāo)題總結(jié)用戶(hù)意圖) assignee: str Field(..., description負(fù)責(zé)人郵箱) due_days: int Field(2, description截止天數(shù)默認(rèn)2天) tools_schema [ { type: function, function: { name: create_task, description: 當(dāng)用戶(hù)需要?jiǎng)?chuàng)建內(nèi)部研發(fā)任務(wù)時(shí)使用不用于普通知識(shí)問(wèn)答。, parameters: CreateTaskInput.model_json_schema(), } } ]這一段看著簡(jiǎn)單但工具描述里的每一句話(huà)都直接影響模型是否在正確的時(shí)候調(diào)用它。我把不用于普通知識(shí)問(wèn)答寫(xiě)進(jìn)去就是因?yàn)橐婚_(kāi)始沒(méi)寫(xiě)知識(shí)問(wèn)答意圖也會(huì)調(diào)這個(gè)工具浪費(fèi)輪次。接下來(lái)是最核心的 ReAct 調(diào)度循環(huán)偽代碼級(jí)別的 Python你可以直接移植到任何語(yǔ)言async def run_agent(user_query, session_id): messages load_history(session_id) messages.append({role: user, content: user_query}) for step in range(MAX_STEPS): response await llm.chat_with_tools( messagesmessages, toolstools_schema, ) messages.append(response.to_message()) if response.tool_calls: for call in response.tool_calls: result await execute_tool(call, usersession_user) messages.append(tool_result_message(call.id, result)) if call.name in SIDE_EFFECT_TOOLS: await notify_human_approval(call, result) else: # 模型已給出最終回答終止循環(huán) return response.content return 已達(dá)到最大輪數(shù)請(qǐng)人工介入執(zhí)行順序值得你細(xì)看。副作用工具不會(huì)當(dāng)場(chǎng)落庫(kù)而是先進(jìn)入待審批狀態(tài)把已提交審批請(qǐng)等待返回給模型等人工確認(rèn)后再真正執(zhí)行。這樣模型可以繼續(xù)做后續(xù)步驟不會(huì)因?yàn)閷徟ㄋ勒麄€(gè)循環(huán)。execute_tool 內(nèi)部還包了一層統(tǒng)一的超時(shí)處理每個(gè)工具最多跑 15 秒超時(shí)返回錯(cuò)誤讓模型換條路徑走。這就是我在前面反復(fù)提的 Harness 思想不是限制模型能力而是保證它永遠(yuǎn)有退路。記憶接入代碼不復(fù)雜但容易寫(xiě)歪。會(huì)話(huà)讀取時(shí)我用最近 3 輪原始消息再加向量庫(kù)拉到的歷史摘要寫(xiě)入時(shí)每累積 10 輪觸發(fā)一次 summarize把前面的對(duì)話(huà)壓縮成一段 JSON存進(jìn) pgvector。記住我在 2.2 節(jié)強(qiáng)調(diào)的那句話(huà)摘要必須保留結(jié)構(gòu)化字段。任務(wù)編號(hào)、用戶(hù) ID、當(dāng)前審批狀態(tài)一旦丟了后續(xù)輪次的模型決策就是空中樓閣。3.4 評(píng)測(cè)集設(shè)計(jì)三個(gè)指標(biāo)、回放機(jī)制與迭代方式Agent 系統(tǒng)最難的不是寫(xiě)代碼而是證明它好用。傳統(tǒng)分類(lèi)任務(wù)的準(zhǔn)確率在這里不夠用因?yàn)?Agent 的輸出是過(guò)程性的模型可能最終答對(duì)了但過(guò)程中多調(diào)了 3 個(gè)沒(méi)必要的工具。我做了一套三層評(píng)測(cè)思路。第一層是任務(wù)完成率判斷最終結(jié)果是否達(dá)成用戶(hù)的真實(shí)目標(biāo)人工去打標(biāo)。第二層是工具調(diào)用正確率每步調(diào)用是否合理也由人去標(biāo)。第三層是無(wú)效循環(huán)率統(tǒng)計(jì)有多少輪是重復(fù)、卡死或者在兩個(gè)工具之間來(lái)回橫跳。配合一個(gè) 50 條任務(wù)的小評(píng)測(cè)集每條任務(wù)實(shí)錄完整的對(duì)話(huà)日志和工具日志每次迭代完跑一遍全量對(duì)比三個(gè)指標(biāo)的分?jǐn)?shù)變化。只有三個(gè)指標(biāo)同時(shí)提升我才敢說(shuō)這次改動(dòng)是正向的。更關(guān)鍵的是把評(píng)測(cè)做成視頻回放而不是分?jǐn)?shù)報(bào)告。我會(huì)寫(xiě)一個(gè)回放工具把 Agent 每一步輸入輸出全部渲染成時(shí)間線(xiàn)標(biāo)出哪一步選錯(cuò)了工具、哪一步浪費(fèi)了輪數(shù)、哪一步因?yàn)榉祷亟財(cái)嘈畔⒉蛔??；胤抛鐾昴銜?huì)驚訝地發(fā)現(xiàn)大部分失敗不是模型不行而是工具描述寫(xiě)反了、返回結(jié)果截太狠、或者記憶摘要丟了關(guān)鍵字段。把這三類(lèi)問(wèn)題修掉任務(wù)完成率普遍能從 60% 拉到 85% 以上。這個(gè)現(xiàn)象讓我形成了一個(gè)判斷Agent 調(diào)優(yōu)的精力分配大約七成在數(shù)據(jù)和工具側(cè)只有三成在模型提示詞上。4. 踩坑實(shí)錄高頻問(wèn)題與排查技巧4.1 高頻問(wèn)題速查表按癥狀定位病因整理一個(gè)高頻問(wèn)題速查表。這張表里的內(nèi)容全是我和周?chē)耐略诓煌?xiàng)目里真實(shí)踩過(guò)的癥狀常見(jiàn)原因排查方法模型反復(fù)調(diào)用同一個(gè)工具工具描述沒(méi)說(shuō)清邊界、返回結(jié)果信息不足檢查返回是否含成功標(biāo)志完善工具描述模型回答無(wú)法找到答案RAG 召回結(jié)果為空、結(jié)果被截?cái)嗖闄z索日志調(diào)整 chunk 大小和 TopK上下文長(zhǎng)度繼續(xù)超限沒(méi)有窗口裁剪、摘要沒(méi)定期觸發(fā)打開(kāi)滑動(dòng)窗口每 N 輪強(qiáng)制摘要Agent 長(zhǎng)時(shí)間不返回最大輪數(shù)過(guò)大、工具超時(shí)未處理調(diào)低輪數(shù)給每個(gè)工具加獨(dú)立 timeout多 Agent 互相推諉角色分工不清、公共狀態(tài)缺失強(qiáng)化角色邊界引入共享狀態(tài)黑板API 費(fèi)用異常暴增缺少配額與限流加全局 token 上限與預(yù)算告警有幾個(gè)點(diǎn)必須展開(kāi)強(qiáng)調(diào)。工具超時(shí)是最容易忽略的如果你的一個(gè)外部 HTTP 工具卡了 30 秒不返回模型會(huì)一直等整個(gè)會(huì)話(huà)就僵死在那里用戶(hù)那邊只看到一個(gè)永遠(yuǎn)不結(jié)束的 loading。所以執(zhí)行層寫(xiě)一個(gè)統(tǒng)一的 timeout 包一層比任何花哨優(yōu)化都管用。另一個(gè)點(diǎn)是 RAG 截?cái)喙ぞ叻祷亟o模型的內(nèi)容不是越多越好截?cái)嚅撝堤輹?huì)丟掉關(guān)鍵證據(jù)太寬又引入噪聲。我在這個(gè)項(xiàng)目里的經(jīng)驗(yàn)是先按 2000 字符截?cái)嗳缓蟾鶕?jù)回放日志逐步調(diào)整到 2500 到 3000每個(gè)知識(shí)域的差異還挺大。4.2 三個(gè)值得長(zhǎng)期投入的工程底座觀(guān)測(cè)、配置回滾、持續(xù)評(píng)測(cè)代碼跑通、指標(biāo)達(dá)標(biāo)只是第一環(huán)。如果你打算把這個(gè) Agent 長(zhǎng)期養(yǎng)下去接下來(lái)的工作重心不是加功能而是把工程底座做厚。我推薦最先投入三個(gè)方向。第一個(gè)是觀(guān)測(cè)性。把每一次模型輸入輸出、token 消耗、工具調(diào)用參宿、延遲全部落到統(tǒng)一的 tracing 系統(tǒng)里。沒(méi)有觀(guān)測(cè)你排查問(wèn)題時(shí)只能靠猜第二次事故的定位時(shí)間至少翻倍。OpenTelemetry 生態(tài)已經(jīng)有成熟的 LLM tracing 方案FastAPI 中間件掛一下就能做到全鏈路。第二個(gè)是可回滾的配置。把 Agent 的 prompt、工具描述、記憶參數(shù)、RAG 參數(shù)全部抽成版本化配置文件上線(xiàn)后隨時(shí)能回滾到任意歷史版本。這能避免一個(gè)場(chǎng)景你想調(diào)一下 prompt 對(duì)線(xiàn)上的一次失敗回復(fù)結(jié)果改完 prompt 又引發(fā)了另 10 個(gè)回歸問(wèn)題手忙腳亂改代碼重發(fā)。第三是持續(xù)評(píng)測(cè)。把每個(gè)線(xiàn)上失敗 case 都收進(jìn)失敗樣本庫(kù)每次迭代都重新跑一遍全量評(píng)測(cè)防止修了 A 問(wèn)題又帶出 B 問(wèn)題的回歸。我自己從第一個(gè) Agent 生產(chǎn)項(xiàng)目開(kāi)始第一天就會(huì)把這三件骨架搭好。它不會(huì)讓你的第一個(gè) Demo 更快甚至前期有點(diǎn)繁瑣但它決定了這套東西能不能穩(wěn)定活過(guò)三個(gè)月而不是在上線(xiàn)后的第三周就變成沒(méi)人維護(hù)的玩具。4.3 想入行 Agent 的人該怎么學(xué)、怎么答面試最后聊點(diǎn)實(shí)際的。Agent 學(xué)習(xí)路線(xiàn)和面試題是最近的熱門(mén)但市面上真沒(méi)有標(biāo)準(zhǔn)教程。我建議按三層遞進(jìn)的方式補(bǔ)。第一層掌握 Prompt 工程和 Function Calling能用官方 SDK 寫(xiě)一個(gè)會(huì)調(diào)工具的原型。這一步篩掉一半人因?yàn)楹芏嗳酥粫?huì)聊天模板不會(huì)讓模型結(jié)構(gòu)化輸出工具參數(shù)。第二層理解 ReAct、Plan-and-Execute、Reflexion 這些推理范式并且能在代碼里實(shí)現(xiàn)一個(gè)最小循環(huán)思考、調(diào)用、觀(guān)察、再思考。這一步驗(yàn)證的是你是否有工程手感而不只是懂概念。第三層動(dòng)手部署一個(gè)帶記憶、帶沙箱、帶評(píng)測(cè)的完整系統(tǒng)把權(quán)限控制、超時(shí)、限流、觀(guān)測(cè)這些工程細(xì)節(jié)全部踩一遍。能走到第三層的人面試基本不用慌。面試被問(wèn)如何設(shè)計(jì)一個(gè) Agent 系統(tǒng)時(shí)不要上來(lái)背框架而是講方法論。你可以先講任務(wù)閉環(huán)拆解再講目標(biāo)、規(guī)劃、記憶、工具、執(zhí)行這五要素的分層取舍最后拋出一個(gè)真實(shí)案例的失敗與修正。面試官最想聽(tīng)的不是框架 API 名稱(chēng)而是你在踩坑中形成的判斷力比如為什么給工具加白名單、為什么摘要要保留結(jié)構(gòu)化字段、為什么評(píng)測(cè)要做回放式分析。這些細(xì)節(jié)才區(qū)分了用過(guò) Agent和做強(qiáng)過(guò) Agent。回到我自己這個(gè)項(xiàng)目上我越來(lái)越覺(jué)得 Agent 系統(tǒng)的上限由模型決定下限由工程決定。模型決定它能多聰明工程決定它在混亂真實(shí)世界里多穩(wěn)定。所謂混亂包括亂寫(xiě)的工具描述、超時(shí)的外部接口、丟字段的記憶摘要、缺失的審計(jì)日志。把這些細(xì)節(jié)一個(gè)一個(gè)磨平一個(gè)夠用且穩(wěn)定的 Agent 并不遙遠(yuǎn)。如果你讀完能少踩幾個(gè)坑這篇就算沒(méi)白寫(xiě)。