1. 項(xiàng)目定位Agent-Reach 解決什么問題1.1 名詞拆解Reach 到底指什么先把這個名字拆開看。Agent 最近一年幾乎被說爛了但Reach這個詞值得琢磨。我在做這個項(xiàng)目之前翻來覆去想了很久最后確定下來這里說的不是代理服務(wù)器里的 agent也不是觸達(dá)用戶里的觸達(dá)而是讓一個大模型驅(qū)動的智能體真正把能力伸到業(yè)務(wù)現(xiàn)場——也就是夠得著實(shí)際系統(tǒng)的那一步。什么叫做夠得著舉個例子。你用 ChatGPT 聊天它能幫你寫一段 Python 代碼但如果你讓它讀一下服務(wù)器上 /data/logs 目錄下最新的錯誤日志整理成一份報告發(fā)到群里它就抓瞎了。不是模型不夠聰明而是它根本沒有手去操作文件系統(tǒng)、沒有權(quán)限去調(diào)接口、沒有通道去發(fā)消息。Agent-Reach 要解決的就是給大模型裝上一只夠得著的手。我見過太多號稱智能體平臺的項(xiàng)目演示的時候很漂亮一問能接我們內(nèi)部系統(tǒng)嗎就卡住了。要么工具注冊流程重到讓人絕望要么只支持某一家云廠商的模型要么跑兩步就上下文爆炸。這類東西不是給開發(fā)人員用的是給 PPT 用的。我在做 Agent-Reach 之前定了幾條硬規(guī)矩模型無關(guān)國產(chǎn)開源模型和商業(yè) API 都能接工具接入必須簡單到一個文件搞定整個鏈路可觀測出了問題能看到是哪一步崩的不依賴重型基礎(chǔ)設(shè)施一臺普通機(jī)器就能跑這個項(xiàng)目適合誰適合那些已經(jīng)在用大模型 API 做單點(diǎn)能力但想更進(jìn)一步把模型接入實(shí)際業(yè)務(wù)流程的人。不管你是后端開發(fā)、算法工程師還是運(yùn)維想搞個自動化助手這篇文章里講的思路和代碼都可以直接改吧改吧拿去用。1.2 目標(biāo)不是又一個框架而是跑通全鏈路說實(shí)話LangChain、AutoGen 這些框架已經(jīng)很多了Agent 相關(guān)的開源項(xiàng)目更是扎堆。Agent-Reach 如果只是一個封裝好的調(diào)用工具那沒有存在的必要。我做這個項(xiàng)目的核心出發(fā)點(diǎn)是把一條鏈路完整跑通任務(wù)進(jìn)來 → 模型理解 → 拆解步驟 → 挑選工具 → 執(zhí)行操作 → 觀察結(jié)果 → 決定下一步 → 輸出最終結(jié)論這條鏈路里每一步都有坑。模型可能選錯工具工具可能返回超時參數(shù)可能對不上執(zhí)行可能產(chǎn)生副作用。Agent-Reach 的核心不是某一步做得多么驚艷而是把整條鏈路整合得足夠穩(wěn)并且每一步都留下日志和審計(jì)線索。現(xiàn)狀是大部分團(tuán)隊(duì)還在單輪調(diào)用階段寫個 prompt調(diào)一次 API拿結(jié)果。稍微往前走半步就發(fā)現(xiàn)模型返回不穩(wěn)定、工具多了以后容易選錯、循環(huán)執(zhí)行容易失控。Agent-Reach 的定位不是一個研究性質(zhì)的 demo而是一個生產(chǎn)環(huán)境能跑的工具箱。后面我會把每一層的設(shè)計(jì)思路和代碼都鋪開講清楚。2. 整體設(shè)計(jì)思路與模塊劃分2.1 為什么我不直接選現(xiàn)成的編排框架在動工之前我實(shí)測過市面上幾個主流框架說實(shí)話各有優(yōu)勢但我最終還是決定自己寫一個輕量實(shí)現(xiàn)。原因有幾點(diǎn)比較現(xiàn)實(shí)第一所謂編排框架其實(shí)解決得最多的場景是從零開始把 agent 搭起來但對于要把 agent 嵌進(jìn)自家業(yè)務(wù)的團(tuán)隊(duì)來說最大的成本在于工具適配和數(shù)據(jù)流轉(zhuǎn)而不是怎么把模型聊起來?？蚣芴胤炊K事。第二很多框架的執(zhí)行邏輯是黑盒。模型內(nèi)部在干什么、每一步選擇了什么工具、為什么這么選缺少清晰可查的日志。我調(diào)過一段時間之后發(fā)現(xiàn)沒有可觀測性的 agent 根本沒法維護(hù)。生產(chǎn)環(huán)境里出一次錯你想定位是模型指令理解錯了、工具入?yún)⒏袷藉e了、還是執(zhí)行環(huán)境缺權(quán)限如果日志不完整光靠猜就能折騰一整天。第三大多數(shù)框架對工具的描述格式要求特別死板。好一點(diǎn)的用 JSON Schema差點(diǎn)的是自己發(fā)明一套 DSL。如果團(tuán)隊(duì)里有多個業(yè)務(wù)方都要接入工具學(xué)習(xí)成本和踩坑成本就被拉高了。所以 Agent-Reach 的設(shè)計(jì)原則就三條薄封裝、全日志、工具定義盡量用標(biāo)準(zhǔn)格式。我寧可多寫幾個適配器也不愿意把所有東西都捆在一個框架里。2.2 四個模塊各管一段整個項(xiàng)目分成四個模塊每一層都有獨(dú)立職責(zé)模型接入層統(tǒng)一封裝不同大模型的調(diào)用方式。不管你是接 OpenAI 兼容接口、通義千問、DeepSeek還是本地部署的 Qwen、GLM都可以通過一套接口切換。底層的響應(yīng)格式差異、超時處理、錯誤重試都在這一層磨平。工具注冊層這是 Agent 能不能夠得著業(yè)務(wù)的關(guān)鍵。每個工具本質(zhì)上就是一個函數(shù)帶一段描述和一個參數(shù) Schema。Agent 根據(jù)任務(wù)需求從注冊表里挑工具就像人翻通訊錄找聯(lián)系人一樣。決策執(zhí)行層負(fù)責(zé)跑思考-行動-觀察循環(huán)。模型先想下一步該做什么然后選擇工具、生成參數(shù)、執(zhí)行調(diào)用拿到結(jié)果后再判斷任務(wù)是否完成。這一層需要精細(xì)設(shè)計(jì)不然容易陷入死循環(huán)或花冤枉錢。觀測審計(jì)層每輪循環(huán)的輸入輸出、工具調(diào)用、耗時、Token 消耗全部落日志。這個層我一開始覺得無所謂后來做過幾個復(fù)雜任務(wù)后才發(fā)現(xiàn)沒有它你根本沒法排查問題。這四個模塊合起來就是一個能用的大模型執(zhí)行終端。換個角度理解它像一個接線板大模型是插座工具是電器Agent-Reach 負(fù)責(zé)把插頭對準(zhǔn)插孔并且盯著電流是不是正常流動。3. 模型接入層的核心細(xì)節(jié)3.1 統(tǒng)一接口解決了什么痛點(diǎn)市面上的大模型 API 形態(tài)五花八門。有的只支持消息補(bǔ)全有的提供流式輸出有的函數(shù)調(diào)用格式不一樣有的返回字段叫content有的叫text。如果業(yè)務(wù)代碼直接調(diào)各家 SDK后期換模型等于重寫一遍調(diào)用邏輯。Agent-Reach 的模型接入層做了一個統(tǒng)一的LLMClient接口核心只暴露兩個方法class LLMClient(ABC): abstractmethod def chat(self, messages: list[dict], tools: list[dict] | None None, **kwargs) - LLMResult: 發(fā)送消息可選附帶工具列表 pass abstractmethod def parse_tool_call(self, response: LLMResult) - ToolCall | None: 從模型響應(yīng)中解析出工具調(diào)用請求 pass調(diào)用方不關(guān)心底層用的是哪一家模型只需要拿著消息列表和工具描述發(fā)給chat然后從返回結(jié)果里取文本或工具調(diào)用。各家模型的差異都寫在適配器里新接一個模型就寫一個適配器改一行配置就能切換。這個設(shè)計(jì)給我后續(xù)接入更多模型省了很多時間。有個關(guān)鍵點(diǎn)要提醒一下不同模型的工具調(diào)用格式未必一致哪怕都聲稱支持 OpenAI 兼容格式。有些模型內(nèi)部做了一層轉(zhuǎn)換傳進(jìn)去的 tool 描述和模型實(shí)際認(rèn)為的格式會有一點(diǎn)偏差返回的字段也可能存在細(xì)微差異。千萬不要想當(dāng)然以為兼容格式就等于完全一樣每個模型換上來之后一定要先跑幾個帶工具調(diào)用的測試用例把返回結(jié)果打出來肉眼觀察一遍。3.2 流式輸出要不要支持我在第一版里直接忽略了流式輸出只做一次性非流式調(diào)用。原因是 Agent 執(zhí)行任務(wù)時通常需要拿到完整的結(jié)構(gòu)化結(jié)果再決策流式輸出對體驗(yàn)幫助不大反而把代碼復(fù)雜度搞上去了。但如果你的場景要求邊生成邊展示就必須考慮流式。我在 Agent-Reach 里預(yù)留了streamTrue的開關(guān)但決策循環(huán)默認(rèn)不開啟。這里給你一個參數(shù)選擇的參考場景流式非流式用戶等待最終結(jié)果可用推薦agent 多輪工具調(diào)用不推薦推薦對話式生成長文推薦可選后臺批量任務(wù)不需要推薦就我個人的經(jīng)驗(yàn)來看Agent 編排鏈路里流量消耗大頭在思考的過程這部分用戶并不關(guān)心快慢反而更在意結(jié)果是否正確。先用非流式把邏輯跑穩(wěn)后面真有展示需求再加流式是比較務(wù)實(shí)的路線。3.3 超時與重試機(jī)制模型接口不穩(wěn)定是常態(tài)尤其是自部署的模型偶爾一個請求能卡兩三分鐘。在 Agent 循環(huán)里一次工具調(diào)用的等待時間會被放大因?yàn)楹竺孢€掛著好幾輪循環(huán)。我的做法是給chat設(shè)置兩個層次的時間控制連接超時 10 秒讀取超時 120 秒模型小的話可以縮到 60 秒重試邏輯采用指數(shù)退避第一次重試等 2 秒第二次 4 秒第三次 8 秒最多重試 3 次。如果再失敗就把異常拋給決策循環(huán)讓 Agent 自己判斷是換模型、換工具還是直接放棄。不要試圖在底層無限重試那會把問題掩蓋掉。4. 工具注冊層讓 Agent 能操作真實(shí)系統(tǒng)4.1 工具的本質(zhì)就是一個函數(shù)加一段說明書工具層是整個 Agent-Reach 里最有實(shí)際價值的部分。我理解的工具本質(zhì)上就是能被大模型調(diào)用的函數(shù)。函數(shù)什么人寫的我們自己。大模型怎么知道該調(diào)哪個靠我們提供的說明書。這個說明書要用模型能看懂的方式寫清楚幾件事這個工具是干什么的入?yún)⒂心男┟總€參數(shù)的類型和含義有沒有副作用比如會刪除數(shù)據(jù)、會發(fā)郵件這種要特別標(biāo)注返回值大概長什么樣我把工具定義設(shè)計(jì)成一個 Python 類注冊的時候自動從類型注解和 docstring 生成描述不需要單獨(dú)維護(hù)一份 JSON。這樣做的好處是業(yè)務(wù)代碼里改一下參數(shù)說明模型拿到的工具描述也會同步更新不會出現(xiàn)代碼改了配置忘了改的問題。示例定義register_tool def search_logs(keyword: str, hours: int 24) - list[dict]: 在日志目錄中搜索包含指定關(guān)鍵詞的日志條目。 Args: keyword: 要搜索的關(guān)鍵詞必填。 hours: 搜索最近多少小時的日志默認(rèn) 24 小時。 Returns: 匹配的日志列表每條包含時間戳、級別、消息。 ...注冊器會根據(jù)函數(shù)的__doc__和類型注解自動生成結(jié)構(gòu)化的工具描述。模型看到的就是一份適合它理解能力的工具目錄。4.2 工具描述寫得越具體模型越不容易選錯踩過這么多坑之后我最想跟你強(qiáng)調(diào)的就是工具選錯絕大多數(shù)時候不是因?yàn)槟Ｐ捅慷且驗(yàn)槟銢]把工具描述寫清楚。舉個例子。我一開始給查天氣工具寫的描述是獲取天氣信息結(jié)果模型在用戶要求明天要不要帶傘時居然去調(diào)用了一個發(fā)郵件的工具——因?yàn)樗X得提醒帶傘和發(fā)郵件提醒有關(guān)系。問題就出在描述太模糊。后來我把描述改成獲取指定城市當(dāng)天或未來幾天的天氣情況包括降水概率、溫度、風(fēng)力。當(dāng)用戶詢問出行、穿衣、帶傘建議時優(yōu)先調(diào)用本工具。準(zhǔn)確率立刻上去了。這個原則適用于所有工具把觸發(fā)條件寫進(jìn)描述里把邊界情況也寫進(jìn)去。另外工具的參數(shù)說明也很關(guān)鍵。模型會根據(jù)參數(shù)名和描述來填充值。如果參數(shù)叫date但你期望的是YYYY-MM-DD格式必須在描述里寫清楚。不然模型可能會給你傳一個明天或者2024-06-01 00:00:00之類的東西。4.3 工具權(quán)限與副作用控制不是所有工具都適合讓模型無條件調(diào)用的。如果一個工具能刪除數(shù)據(jù)、能轉(zhuǎn)賬、能對外發(fā)送消息那在沒有任何限制的情況下讓模型自由調(diào)用就是在給自己埋雷。我在 Agent-Reach 里給每個工具標(biāo)記了risk_levelL1 只讀查日志、查配置、搜索資料模型可直接調(diào)用L2 有副作用寫緩存、更新狀態(tài)、發(fā)通知需要二次確認(rèn)L3 高危險刪數(shù)據(jù)、改權(quán)限、大規(guī)模變更默認(rèn)禁止模型直接調(diào)用需要人工審核這個設(shè)計(jì)非常有用。實(shí)際跑起來你會發(fā)現(xiàn)模型的自主性越強(qiáng)越容易出現(xiàn)好心辦壞事的情況。比如我讓 Agent 幫我清理臨時文件它理解成刪除 /tmp 下所有文件如果沒有權(quán)限控制那這波操作就很酸爽了。5. 決策執(zhí)行層循環(huán)是怎么跑起來的5.1 核心循環(huán)思考、行動、觀察Agent 的決策循環(huán)并不神秘一句話就能說明白讓模型看完當(dāng)前狀態(tài)決定下一步動作執(zhí)行完看結(jié)果再決定下一步直到它認(rèn)為任務(wù)完成了。用偽代碼表達(dá)就是while not done and step max_steps: result llm.chat(messages, tools) if result.tool_call: # 執(zhí)行工具把結(jié)果追加到消息里 messages.append(tool_result) else: # 模型沒有調(diào)用工具視為給出最終回復(fù) done True這個循環(huán)看著簡單真正要跑穩(wěn)有幾個細(xì)節(jié)。第一個是max_steps。如果任務(wù)一直完不成模型會反復(fù)調(diào)用工具沒完沒了。我的默認(rèn)值是 8 步復(fù)雜任務(wù)可以調(diào)到 15但超過 15 步基本就該懷疑是 prompt 設(shè)計(jì)有問題了。第二個是把歷史消息全部留給模型看。工具調(diào)用的輸入、輸出都要拼接到上下文中。這會帶來一個問題Token 消耗會逐漸變大。你需要做上下文裁剪把太早的、不太相關(guān)的工具輸出壓縮掉。我通常保留最近 3-5 輪的完整對話更早的操作結(jié)果只保留一行摘要。5.2 如何處理模型返回不穩(wěn)定模型返回的工具調(diào)用參數(shù)不是每次都能直接拿來用。最常見的問題是缺參數(shù)、多傳參數(shù)、類型不對。比如工具需要user_id: int模型給你傳了一個字符串a(chǎn)bc123或者根本漏了這個字段。我的處理方式是在執(zhí)行工具前加一層參數(shù)校驗(yàn)和類型轉(zhuǎn)換。用 Pydantic 或類似工具做 Schema 校驗(yàn)不合格的參數(shù)嘗試轉(zhuǎn)型實(shí)在不行的就把它當(dāng)錯誤信息反饋給模型讓它重新生成參數(shù)。要讓模型知道剛才那次調(diào)用因?yàn)閰?shù)問題失敗了請重新給一份正確的參數(shù)往往模型就能糾正過來。這個反饋錯誤讓模型自己糾錯的機(jī)制非常強(qiáng)大比你硬寫一堆兼容代碼要省事得多。模型的自我糾錯能力比很多人想象的要強(qiáng)只是你需要給它足夠的反饋信息。5.3 并行調(diào)度怎么實(shí)現(xiàn)有些任務(wù)天然可以拆成多個獨(dú)立子任務(wù)。比如查一下三個城市明天的天氣匯總給我就沒必要一個城市一個城市串行調(diào)用。Agent-Reach 支持一個 step 內(nèi)觸發(fā)多個工具調(diào)用——模型可以一次返回兩個或三個獨(dú)立調(diào)用然后我用一個線程池并行執(zhí)行。from concurrent.futures import ThreadPoolExecutor def execute_tools(calls: list[ToolCall]) - list[ToolResult]: with ThreadPoolExecutor(max_workersmin(4, len(calls))) as executor: futures [executor.submit(execute_tool, call) for call in calls] return [f.result() for f in futures]并行雖然快但也有坑。一是模型把兩個有依賴關(guān)系的工具調(diào)用同時發(fā)出來比如它先調(diào)獲取用戶列表再調(diào)給每個用戶發(fā)通知如果并行執(zhí)行后面那個可能拿不到前面那個的結(jié)果。所以我做了個簡單判斷如果這些調(diào)用之間存在明顯的參數(shù)依賴關(guān)系就強(qiáng)制串行。這層判斷邏輯不復(fù)雜但能避免很多詭異的 bug。6. 實(shí)操環(huán)節(jié)從零搭一個 Agent-Reach 實(shí)例6.1 環(huán)境準(zhǔn)備與目錄結(jié)構(gòu)Agent-Reach 的運(yùn)行環(huán)境要求不高。我本地開發(fā)用一臺 8 核 16G 的機(jī)器模型接的是云端 API本地只跑決策和執(zhí)行邏輯。如果你要接本地模型那顯存分配又是另一個話題但就 Agent 編排層而言一臺普通開發(fā)機(jī)完全夠用。項(xiàng)目目錄結(jié)構(gòu)如下整體保持簡潔agent_reach/ ├── agent/ │ ├── __init__.py │ ├── core.py # 決策循環(huán)主邏輯 │ ├── llm.py # 模型接入層 │ ├── tools.py # 工具注冊與執(zhí)行 │ ├── registry.py # 工具注冊表 │ └── audit.py # 審計(jì)日志 ├── config/ │ └── config.yaml # 模型、參數(shù)配置 ├── tools/ │ ├── log_tools.py │ └── notify_tools.py └── main.py # 入口核心依賴只有三個openai兼容各家 API、pydantic參數(shù)校驗(yàn)、yaml配置解析。整個項(xiàng)目的第三方依賴控制在個位數(shù)這也是它能保持輕量的原因。6.2 核心代碼實(shí)現(xiàn)先看配置配置文件很直觀model: provider: openai_compatible base_url: https://your-api-endpoint.com/v1 api_key: sk-xxxx model_name: qwen-plus temperature: 0.2 agent: max_steps: 8 parallel: true max_parallel: 4 history_keep_rounds: 5 audit: log_dir: ./logstemperature我建議設(shè)置 0.2 左右。Agent 執(zhí)行任務(wù)時我們希望它穩(wěn)定、少發(fā)散而不是像聊天一樣腦洞大開。0.7 以上的溫度會讓工具選擇變得飄忽不定。核心循環(huán)代碼較長我把關(guān)鍵片段貼出來重點(diǎn)看循環(huán)控制async def run_agent(task: str, tools: list[Tool]) - str: messages [{role: user, content: task}] audit AuditSession(task) for step in range(max_steps): response await llm.chat(messages, tools) audit.log_step(step, response) # 模型沒有工具調(diào)用視為完成 if not response.tool_calls: return response.content # 執(zhí)行工具調(diào)用支持并行 results await execute_tool_calls(response.tool_calls) # 將結(jié)果追加回上下文 for call, result in zip(response.tool_calls, results): messages.append({ role: tool, tool_call_id: call.id, content: result.summary_text }) audit.log_tool_call(call, result) # 上下文壓縮 messages compress_history(messages) raise AgentLoopLimitError(f步驟超過 {max_steps} 次仍未完成)這里有幾個細(xì)節(jié)值得注意。我把工具執(zhí)行結(jié)果轉(zhuǎn)成summary_text再塞回上下文而不是直接塞原始返回。因?yàn)樵挤祷乜赡芊浅４蟊热缛罩静樵児ぞ呖赡芊祷貛浊袃?nèi)容。我會在工具層做一層摘要把最關(guān)鍵的信息提煉出來。日志工具返回時默認(rèn)只返回前 20 行、按級別統(tǒng)計(jì)的匯總、以及錯誤關(guān)鍵詞列表。模型需要細(xì)節(jié)時可以再次調(diào)用工具去查這樣既保證了信息不丟又控制了 Token 開銷。6.3 參數(shù)選擇背后的思考history_keep_rounds: 5這個值不是隨便定的。太短模型會忘記前面做過什么太長Token 浪費(fèi)嚴(yán)重而且工具輸出里的噪聲會影響模型判斷。5 輪是我實(shí)測下來準(zhǔn)確率和成本比較均衡的值。max_parallel: 4也不是越大越好。并行工具調(diào)用對模型的要求更高它需要同時為多個工具生成參數(shù)出錯率會上升。我試過 8 個并行結(jié)果模型經(jīng)常把兩個調(diào)用的參數(shù)搞混。后來限制 4 個以內(nèi)準(zhǔn)確率明顯回升。還有一個容易被忽略的配置audit的日志目錄。我強(qiáng)烈建議你把每一步的日志都保存下來。排查問題的時候翻日志比讓 Agent 復(fù)述發(fā)生了什么要靠譜得多。每一條日志我都會記錄輸入消息、模型原始響應(yīng)、解析后的工具調(diào)用、執(zhí)行結(jié)果、耗時。這個對后面做評測、迭代 prompt、調(diào)整參數(shù)都非常重要。7. 常見問題與排查技巧實(shí)錄7.1 問題速查表這一節(jié)是從實(shí)際跑 Agent-Reach 過程中沉淀下來的踩坑記錄。有些問題在網(wǎng)上搜不到答案只能自己慢慢試。整理成表方便你快速對照排查?，F(xiàn)象可能原因處理方式模型反復(fù)調(diào)用同一個工具但沒進(jìn)展工具返回的信息不足以下判斷檢查工具返回摘要補(bǔ)充關(guān)鍵信息或增加max_steps工具選錯用 A 工具做 B 的事工具描述太模糊重寫工具描述明確觸發(fā)條件和邊界場景模型生成的工具參數(shù)格式不對參數(shù) Schema 過于寬松增加參數(shù)描述、限制枚舉值、強(qiáng)制類型校驗(yàn)執(zhí)行到一半上下文超長工具返回內(nèi)容過大且未壓縮在工具層做摘要開啟上下文壓縮并行調(diào)用中兩個工具有依賴循環(huán)邏輯未做依賴檢測實(shí)現(xiàn)簡單的參數(shù)依賴檢查強(qiáng)制串行Agent 明明完成了任務(wù)還繼續(xù)跑模型沒有收到停止信號檢查最終回復(fù)是否使用了特殊的停止標(biāo)記在 prompt 里強(qiáng)調(diào)輸出規(guī)范7.2 我在排查中最常用的幾個手法如果你發(fā)現(xiàn) Agent 行為不對第一件事不是改 prompt而是打開審計(jì)日志完整看一遍模型每輪的思考軌跡和工具調(diào)用記錄。很多詭異行為其實(shí)都有跡可循只是你沒看日志之前完全猜不到。舉個例子。我之前遇到的問題Agent 經(jīng)常給出特別敷衍的回答比如任務(wù)完成但實(shí)際工作沒做。翻日志發(fā)現(xiàn)模型其實(shí)執(zhí)行了工具但工具結(jié)果返回的是空列表。模型判斷沒有數(shù)據(jù)所以完成了。問題出在日志查詢工具返回空列表時沒有說明沒有匹配結(jié)果可能關(guān)鍵詞太嚴(yán)格或時間范圍太短。模型不知道還有沒有其他可能就直接停了。我在工具返回里加了一句提示如果沒有結(jié)果請嘗試放寬關(guān)鍵詞或擴(kuò)大時間范圍再查一次這種行為立刻消失了。再分享一個技巧給模型提供人在環(huán)上的通道。不是所有任務(wù)都能全自動完成。當(dāng) Agent 遇到自己無法判斷的情況比如是否要刪除這 100 條記錄我讓它停下來清晰地說明情況然后人工確認(rèn)。這個機(jī)制看起來簡單但在實(shí)際使用中非常重要能避免很多不可挽回的操作。還有一點(diǎn)模型對我不知道的容忍度很低。它傾向于給一個看起來合理的答案而不是承認(rèn)自己不夠了解。所以你需要在 prompt 里明確告訴它遇到不確定的情況可以調(diào)用一個查詢參考文檔的工具或者直接請求人工介入。不要讓它硬編一個答案。7.3 值得養(yǎng)成的三個習(xí)慣第一每次迭代只改一個變量。不管是改 prompt、改工具描述、還是改 temperature一次只動一個然后跑同一批測試用例看差異。同時改兩個變量出了效果都不知道是哪個起的作用。第二建立回歸測試集。收集 10-20 個典型任務(wù)每次改完核心代碼就跑一遍。Agent 項(xiàng)目非常容易出現(xiàn)修好了一個問題又帶崩了另一個場景的情況。沒有回歸測試你會在不知不覺中被各種邊緣 case 折磨瘋掉。第三記錄 Token 消耗。每個任務(wù)跑完統(tǒng)計(jì)輸入輸出 Token 數(shù)、調(diào)用了幾次工具。這樣你能發(fā)現(xiàn)哪些任務(wù)經(jīng)常做無用功。我曾經(jīng)發(fā)現(xiàn)某個場景每次要跑 7 次工具調(diào)用優(yōu)化工具描述之后降到了 3 次成本直接砍半。不記錄就沒法優(yōu)化。8. 基于 Agent-Reach 的實(shí)際場景與擴(kuò)展方向?qū)崙?zhàn)場景說了這么多我用一個綜合案例來總結(jié)整個項(xiàng)目的價值。假設(shè)我在一個業(yè)務(wù)團(tuán)隊(duì)里負(fù)責(zé)運(yùn)維自動化。我接了一個需求每天早上生成的錯誤日志需要自動分析、歸類、發(fā)給相關(guān)負(fù)責(zé)人。用 Agent-Reach 做這件事鏈路非常清晰寫一個query_logs工具負(fù)責(zé)從日志系統(tǒng)里拉數(shù)據(jù)寫一個classify_error工具負(fù)責(zé)把錯誤分類寫一個send_notification工具負(fù)責(zé)發(fā)消息給 Agent 一個任務(wù)模板分析昨天的錯誤日志按類型統(tǒng)計(jì)給每個負(fù)責(zé)人發(fā)一條通知Agent 會自己去調(diào)工具、匯總數(shù)據(jù)、生成通知內(nèi)容。整個過程完全可觀測出問題能定位到具體步驟。這套體系的真正價值不在于省掉了多少人工而在于把專家經(jīng)驗(yàn)沉淀成了可復(fù)用、可擴(kuò)展的自動化流程。后面我在 Agent-Reach 上還做了幾個擴(kuò)展方向。一是給工具調(diào)用加了緩存層相同參數(shù)的工具調(diào)用在短時間內(nèi)直接返回緩存結(jié)果省 Token 也省時間。二是把審計(jì)日志接到了一套可視化看板上直接在界面上看每一步的流轉(zhuǎn)。三是給 Agent 加了一個計(jì)劃模式——先讓模型把任務(wù)拆成計(jì)劃步驟展示出來用戶確認(rèn)之后再執(zhí)行。這幾個擴(kuò)展都不復(fù)雜但實(shí)際使用體驗(yàn)提升非常明顯。在做 Agent-Reach 的過程中我最大的體會是Agent 能不能真正落地關(guān)鍵不在于模型強(qiáng)不強(qiáng)而在于你愿意花多少功夫去調(diào)工具、調(diào)描述、調(diào)循環(huán)邏輯。模型是大腦工具是手腳循環(huán)是神經(jīng)。這套系統(tǒng)要順滑地運(yùn)轉(zhuǎn)每一步都需要細(xì)致打磨。我也還在持續(xù)優(yōu)化后面有什么新發(fā)現(xiàn)再繼續(xù)分享。