如果你最近在折騰Agent大概率遇到過這類場景讓AI幫你查某個GitHub倉庫的star數(shù)它直接開始編數(shù)據(jù)而不是去調(diào)用搜索接口。我一開始以為是模型不行換了幾個大模型都一樣。后來把系統(tǒng)里三十多個工具全部列出來才發(fā)現(xiàn)問題不在智商在于它根本不知道哪個工具可用、該用哪個。這其實(shí)就是觸達(dá)率太低的問題。我花了兩周做了個叫 Agent-Reach 的輕量框架專門解決Agent在工具、知識、協(xié)作伙伴三個層面的可達(dá)性。這篇文章就把整個設(shè)計過程和踩坑經(jīng)驗(yàn)拆開講希望能給正在做Agent落地的朋友一些實(shí)際參考。1. 先從一次翻車現(xiàn)場說起Agent 為什么找不到工具1.1 觸達(dá)率問題Agent 不是沒有工具而是不知道有工具先說一個我實(shí)測下來的數(shù)據(jù)。最初版本的系統(tǒng)里掛了32個工具包括GitHub搜索、天氣查詢、數(shù)據(jù)庫查詢、定時任務(wù)調(diào)度等等。表面上功能很全但真實(shí)任務(wù)執(zhí)行時工具調(diào)用成功率只有41%。我翻日志發(fā)現(xiàn)絕大多數(shù)失敗不是調(diào)用報錯而是Agent壓根沒發(fā)起調(diào)用直接憑訓(xùn)練數(shù)據(jù)里的記憶開始編答案。這里面有個經(jīng)常被忽略的事實(shí)大模型的能力邊界不在于它會不會調(diào)用工具而在于它是否知道現(xiàn)在有一個工具能幫我拿到更準(zhǔn)的信息。工具數(shù)量少的時候把全部工具描述塞進(jìn)System Prompt還能湊合。一旦超過20個模型就開始挑花了眼你讓它搜倉庫它可能調(diào)了搜索新聞的接口你讓它查天氣它反過來問你具體城市代碼。這不是模型變笨了是觸達(dá)鏈路的瓶頸到了。Agent每天面對的是動輒幾十上百個工具、海量的知識文檔、多個協(xié)作Agent如果它不能快速、準(zhǔn)確地定位到自己需要的那一個那再強(qiáng)的推理能力也會被浪費(fèi)。Agent-Reach這個名字里最重要的詞是Reach它解決的就是Agent能不能夠得著這件事。1.2 Agent-Reach 的整體定位與技術(shù)邊界做Agent-Reach之前我給自己劃了三條邊界這也是整個項目的地基。第一不重新發(fā)明Agent框架它只做能力觸達(dá)層可以嵌到LangChain、AutoGen、自研框架里第二不強(qiáng)行替代RAG知識可達(dá)性和工具可達(dá)性是兩個問題Agent-Reach優(yōu)先解決工具和Agent之間的可達(dá)性第三不要求底層模型必須是某個特定廠商設(shè)計上只依賴OpenAI兼容的Function Calling格式方便遷移。在這個定位下Agent-Reach實(shí)現(xiàn)了三個核心能力統(tǒng)一工具注冊表、語義檢索配路由、多智能體協(xié)調(diào)鏈路。聽起來有點(diǎn)抽象簡單翻譯一下工具注冊表解決有哪些能力的問題語義檢索解決給定任務(wù)該用哪個能力的問題多智能體路由解決自己能力不夠時該找誰的問題。這三個能力端到端串起來之后工具調(diào)用成功率從41%提到了82%雖然還談不上完美但體感上已經(jīng)是質(zhì)變。技術(shù)邊界想清楚太重要了。很多項目做著做著就膨脹了今天想加自主規(guī)劃明天想做記憶管理最后變成一個四不像的框架。我給自己定了一個原則Agent-Reach只負(fù)責(zé)把Agent伸出去的手接住至于伸哪只手、怎么思考那是Agent本體的事情。2. 三個關(guān)鍵設(shè)計決策以及背后的原因2.1 工具注冊表先解決有什么再解決怎么用Agent-Reach的第一個設(shè)計決策是給所有工具做一張統(tǒng)一的注冊表。你可能覺得這有什么好設(shè)計的把工具名和描述放在一個JSON數(shù)組里不就完了實(shí)際做起來根本不是那么回事。我見過最典型的反例是工具描述寫得像接口文檔一上來就是request/response結(jié)構(gòu)、鑒權(quán)方式、限流規(guī)則看起來非常專業(yè)但模型根本沒法根據(jù)這個做工具選擇。大模型做工具調(diào)用的本質(zhì)是一次語義匹配——它讀到的描述必須能跟用戶的意圖在語義空間里靠得足夠近。所以Agent-Reach的注冊表規(guī)范里有兩個強(qiáng)制要求每個工具必須有獨(dú)立的行為描述這工具到底做什么輸出什么結(jié)果和語義標(biāo)簽這個工具屬于哪一類能力。行為描述控制在60到80個中文字符以內(nèi)語義標(biāo)簽從固定的分類體系里選比如外部API、內(nèi)部服務(wù)、數(shù)據(jù)查詢、消息通知。這兩個字段在后續(xù)的語義檢索里扮演完全不同的角色行為描述用于給模型看語義標(biāo)簽用于給檢索器篩。注冊表是整個系統(tǒng)的地基后面所有檢索和路由都掛在它上面。這一層如果亂后面全都報廢。2.2 語義檢索層讓 Agent 用自然語言找到正確工具第二個關(guān)鍵決策是不再把所有工具描述塞進(jìn)每次請求的Prompt里而是改成按需動態(tài)加載。做法就是給注冊表里的每一條工具描述做向量化放進(jìn)向量數(shù)據(jù)庫等用戶請求進(jìn)來時先用Embedding檢索召回最相關(guān)的3到5個工具再把這些工具的完整信息動態(tài)拼進(jìn)Prompt。為什么要這樣做直接原因就是上下文窗口有限。我們用的上下文窗口是128K看著不小但幾十個工具的完整描述加上歷史對話很快就會把窗口撐爆。更關(guān)鍵的是我實(shí)測下來有一個規(guī)律工具描述在Prompt里占比越高模型調(diào)用工具的準(zhǔn)確率越低。它會把注意力分散到無關(guān)工具的字段上反而忽略了真正該調(diào)的那個。Agent-Reach的檢索鏈路用了一個針對Function Calling場景微調(diào)過的Embedding模型專門用來編碼工具描述。針對性調(diào)這一層的原因是我發(fā)現(xiàn)通用Embedding模型擅長編碼自然語言句子但工具描述是半結(jié)構(gòu)化的文本夾雜大量參數(shù)名和枚舉值直接套通用模型召回率會掉10個點(diǎn)左右。檢索層選型時我重點(diǎn)對比了三種方案純關(guān)鍵詞匹配BM25、通用向量檢索、微調(diào)后的向量檢索。BM25根本不行同樣是查倉庫star數(shù)用戶可能說成看看這個項目多火關(guān)鍵詞完全對不上。通用向量檢索能守住60%左右的召回勉強(qiáng)能用但不滿意。微調(diào)后的向量檢索在測試集上召回率能做到88%果斷選它。這個對比過程也讓我認(rèn)識到Embedding模型和數(shù)據(jù)的匹配度往往比模型本身的大小更重要。2.3 多智能體路由找不到工具時知道該找誰第三個設(shè)計決策是給Agent-Reach加了一層多智能體路由。這個需求來源于一個很實(shí)際的問題工具調(diào)用失敗以后Agent應(yīng)該怎么辦常見做法是讓Agent自己換個工具重試但對那種單個Agent能力邊界之外的任務(wù)換工具也沒用。比如主Agent只負(fù)責(zé)處理文本類任務(wù)用戶卻要求生成一張圖表正常情況下主Agent會硬著頭皮寫一段錯誤的繪圖代碼而不是把請求轉(zhuǎn)給專業(yè)繪圖Agent。需要有人幫它判斷這個任務(wù)不該我做應(yīng)該找誰做。Agent-Reach的路由層維護(hù)了一張能力路由表每個子Agent注冊自己的能力描述、負(fù)責(zé)任務(wù)類型、調(diào)用地址。主Agent收到任務(wù)后先做一次意圖分類把任務(wù)類型和能力路由表做匹配命中就直接轉(zhuǎn)發(fā)未命中再走語義檢索找工具。這種方式把工具觸達(dá)和伙伴觸達(dá)分開了職責(zé)更清晰。一個細(xì)節(jié)路由表匹配的閾值不能太激進(jìn)寧可把任務(wù)返回給主Agent兜底也不要強(qiáng)行轉(zhuǎn)給一個可能執(zhí)行錯的子Agent。我把路由置信度閾值調(diào)到了0.75低于這個值就交給兜底邏輯自己處理同時記錄一條未路由日志方便后續(xù)手動校準(zhǔn)。3. 核心模塊拆解與實(shí)現(xiàn)細(xì)節(jié)3.1 注冊表數(shù)據(jù)結(jié)構(gòu)一個可落地的 JSON Schema 設(shè)計前面說了注冊表很重要現(xiàn)在把它落到具體結(jié)構(gòu)上。Agent-Reach的每一條工具記錄長這樣{ tool_id: github_search_repo, name: GitHub倉庫搜索, behavior_desc: 按關(guān)鍵字搜索GitHub公開倉庫返回倉庫列表、star數(shù)、主要語言和簡介, semantic_tags: [external_api, code_search, github], endpoint: call_github_search_repo, input_schema: { type: object, properties: { query: {type: string, description: 搜索關(guān)鍵詞如 agent framework}, sort: {type: string, enum: [stars, best_match], default: best_match} }, required: [query] }, status: active, creation_time: 2025-01-12T10:30:00Z }這里有兩個字段需要特別說明。第一個是behavior_desc它只描述這個工具做了什么、返回什么不描述怎么傳參、有什么限制。為什么不把參數(shù)細(xì)節(jié)也放進(jìn)來因?yàn)閰?shù)細(xì)節(jié)是給模型執(zhí)行時看的放太早反而會干擾工具選擇階段的判斷。第二個是semantic_tags它走的是離散標(biāo)簽體系檢索時先按標(biāo)簽粗篩再算向量相似度細(xì)排相當(dāng)于一個二級漏斗能顯著降低誤召回。input_schema字段直接復(fù)用JSON Schema規(guī)范這樣可以無縫對接OpenAI Function Calling、LangChain的tool接口、以及Claude的tool use格式。我自己寫了一個適配腳本50行代碼就能把Agent-Reach注冊表轉(zhuǎn)換成各家框架要求的格式省去了大量重復(fù)造輪子的時間。3.2 檢索鏈路embedding 計算、召回與閾值調(diào)節(jié)注冊表有了接下來就是檢索鏈路。Agent-Reach的檢索流程分三步第一步把用戶請求文本和工具行為描述分別做向量化。請求文本用的是輕量級快速模型保證首屏延遲可控工具描述離線批量計算好存庫不占在線資源。第二步在向量數(shù)據(jù)庫里按相似度召回Top-K工具K默認(rèn)取5同時要求相似度得分不低于0.45低于0.45的直接丟棄寧缺毋濫。第三步把召回的5個工具加上工具名稱、參數(shù)Schema、行為描述拼裝成模型可讀的候選工具列表。這里有個經(jīng)驗(yàn)之談K值不要貪大。我試過K10結(jié)果模型反而開始猶豫在多個相似工具之間搖擺不定調(diào)用成功率從82%掉回76%。K3到5是當(dāng)前窗口和準(zhǔn)確率之間的甜點(diǎn)區(qū)。0.45這個閾值也不是拍腦袋定的我拿200條真實(shí)任務(wù)跑了一遍畫出召回率-準(zhǔn)確率曲線0.45剛好是兩者交叉點(diǎn)附近的位置。你在自己的場景里完全可以直接用這兩個數(shù)當(dāng)初始值但最好還是用自己的數(shù)據(jù)重新校準(zhǔn)一次。向量數(shù)據(jù)庫選型上我本地開發(fā)用Chroma部署到服務(wù)器換了FAISS加內(nèi)存索引。Chroma勝在零配置、能在筆記本上直接跑適合原型驗(yàn)證。FAISS在百萬級以下規(guī)模的向量上延遲幾乎為零而且純內(nèi)存計算沒有多余的網(wǎng)絡(luò)依賴。對Agent-Reach這種工具描述向量規(guī)模最多幾千條的場景用重型向量數(shù)據(jù)庫屬于殺雞用牛刀。3.3 路由與降級策略控制權(quán)轉(zhuǎn)移的完整流程多智能體路由模塊的完整流程我用文字描述一下因?yàn)榱鞒虉D更復(fù)雜而這塊邏輯的核心其實(shí)就三步。第一步意圖分類。主Agent接收任務(wù)后先用一個輕量分類模型判斷任務(wù)類型輸出一個指向能力域的編碼比如數(shù)據(jù)可視化代碼生成信息檢索。第二步路由匹配。拿意圖編碼去查能力路由表找到對應(yīng)子Agent匹配置信度超過0.75就轉(zhuǎn)發(fā)否則進(jìn)入降級流程。第三步降級處理。降級分兩檔第一檔是同樣的任務(wù)換個工具再試一次還是失敗就進(jìn)入第二檔第二檔是把任務(wù)退回給主Agent由主Agent做能力內(nèi)兜底實(shí)在處理不了就明確告訴用戶當(dāng)前無法完成該任務(wù)。降級流程是整個路由模塊里最容易踩坑的地方。我一開始沒做降級結(jié)果子Agent調(diào)用失敗后又把請求拋回主Agent主Agent又路由給同一個子Agent形成了一個死循環(huán)。后來在路由層加了手動熔斷開關(guān)同一個子Agent連續(xù)失敗3次該子Agent在接下來30秒內(nèi)不會被路由命中這個時間窗口足夠主Agent做出替代決策。多智能體場景里還有一個隱蔽問題子Agent執(zhí)行完任務(wù)后回復(fù)內(nèi)容需要被主Agent感知為已解決或未解決。我在路由協(xié)議的返回結(jié)構(gòu)里加了status字段和summary字段status標(biāo)記成功或失敗summary給主Agent一段簡潔的結(jié)果摘要這樣主Agent不用自己去翻原始響應(yīng)就能判斷下一步。4. 從零搭一個 Agent-Reach 最小原型4.1 環(huán)境準(zhǔn)備與依賴清單這部分是針對想自己動手復(fù)現(xiàn)的朋友。Agent-Reach原型需要準(zhǔn)備的環(huán)境如下Python 3.10以上推薦3.11性能更好且兼容pandas等常用庫。向量數(shù)據(jù)庫Chroma 0.4pip安裝即可本地開發(fā)不需要額外部署服務(wù)。一個小型Embedding模型這里推薦BAAI/bge-small-zh-v1.5理由有三個中文語義表現(xiàn)穩(wěn)定、模型體積只有約90MB、支持開源商用不用為授權(quán)問題折騰。一個大模型API只要是OpenAI兼容的Function Calling格式就行。安裝依賴的命令我直接給出來pip install chromadb sentence-transformers openai如果網(wǎng)絡(luò)環(huán)境不允許從HuggingFace下載模型可以把bge-small-zh-v1.5先下到本地再用本地路徑加載不影響后面的流程。說實(shí)話原型階段最怕的不是依賴多而是版本不兼容建議直接裝這三個包的最新版互相之間沒有深的依賴沖突。4.2 三個核心代碼模塊的實(shí)現(xiàn)與聯(lián)調(diào)代碼層面Agent-Reach最小原型要寫三個模塊注冊表管理、向量檢索、路由匹配。下面逐個過。注冊表管理模塊負(fù)責(zé)工具的增刪改查核心結(jié)構(gòu)是一個Python字典列表每個元素對應(yīng)3.1節(jié)里的JSON Schema。第一次實(shí)現(xiàn)時不要做數(shù)據(jù)庫持久化直接用內(nèi)存儲就行先把流程跑通再說。代碼大概長這樣from typing import List, Dict class ToolRegistry: def __init__(self): self._tools: Dict[str, dict] {} def register(self, tool: dict): tool_id tool[tool_id] if tool_id in self._tools: raise ValueError(ftool_id {tool_id} already exists) self._tools[tool_id] tool def get(self, tool_id: str) - dict: return self._tools.get(tool_id) def list_all(self) - List[dict]: return list(self._tools.values())向量檢索模塊是核心負(fù)責(zé)把工具描述編碼入庫再按用戶請求召回。我用Chroma作為存儲模型用bge-small-zh-v1.5from chromadb import Client from chromadb.utils import embedding_functions from sentence_transformers import SentenceTransformer model SentenceTransformer(BAAI/bge-small-zh-v1.5) client Client() collection client.get_or_create_collection( nameagent_tools, embedding_functionembedding_functions.SentenceTransformerEmbeddingFunction( model_nameBAAI/bge-small-zh-v1.5 ) ) def encode_tool(tool: dict): doc tool[behavior_desc] .join(tool[semantic_tags]) collection.add( ids[tool[tool_id]], documents[doc], metadatas[{name: tool[name]}] ) def search_tools(query: str, top_k: int 5, threshold: float 0.45): results collection.query(query_texts[query], n_resultstop_k) docs results[documents][0] distances results[distances][0] hit [] for i, doc in enumerate(docs): similarity 1.0 - distances[i] if similarity threshold: hit.append({doc: doc, similarity: similarity}) return hit先說明一下Chroma返回的是distance距離越小越相似我用了1.0 - distance把距離轉(zhuǎn)成相似度方便理解。實(shí)際項目中可以直接沿用distance但閾值判斷邏輯要跟著反著寫。第三個模塊是路由匹配我用一個簡單的意圖分類函數(shù)加路由表完成。路由表就是一個字典key是意圖類型value是子Agent信息ROUTE_TABLE { code_generation: { agent_id: coding_agent, description: 處理代碼生成和修改任務(wù), endpoint: dispatch:coding_agent, confidence: 0.9 }, data_visualization: { agent_id: chart_agent, description: 生成圖表和可視化報告, endpoint: dispatch:chart_agent, confidence: 0.85 } } def route_task(intent: str, task_text: str): if intent not in ROUTE_TABLE: return None entry ROUTE_TABLE[intent] # 置信度低于閾值就交給兜底 if entry[confidence] 0.75: return None return entry[endpoint]聯(lián)調(diào)的時候注意幾個點(diǎn)先單獨(dú)測檢索模塊再測路由模塊最后端到端跑一遍不要一上來就全鏈路調(diào)試出問題很難定位。我一開始圖省事三個模塊同時上線結(jié)果一個普通的數(shù)據(jù)格式錯誤折騰了一晚上才定位到得不償失。4.3 驗(yàn)證方法用 10 條測試任務(wù)評估觸達(dá)率寫完原型之后很多人會面臨一個問題怎么知道它真的有效我當(dāng)時設(shè)計了一套最簡單的驗(yàn)證方案準(zhǔn)備10條覆蓋不同場景的測試任務(wù)每條任務(wù)都明確對應(yīng)一個工具或子Agent。測試任務(wù)的示例查一下LangChain在GitHub上的star數(shù)、幫我把這段文字轉(zhuǎn)成摘要、查一下北京今天的氣溫、幫我寫一個Python腳本讀取CSV文件并生成柱狀圖、從訂單表里統(tǒng)計最近7天的銷售額。每條任務(wù)手工標(biāo)記期望用到的工具或子Agent然后跑Agent-Reach端到端流程統(tǒng)計是否正確觸達(dá)目標(biāo)能力的次數(shù)。我跑了三輪測試第一輪觸達(dá)率只有67%大部分失敗集中在查詢類任務(wù)意圖模糊上比如查一下這個項目的熱度到底應(yīng)該搜GitHub還是搜新聞Agent-Reach召回了搜索新聞的工具。這暴露了一個問題語義標(biāo)簽粒度太粗。我在新聞工具上加了hot_keyword_tracking標(biāo)簽在GitHub工具上加了repos_community_metrics標(biāo)簽讓兩個工具在向量空間里的距離更遠(yuǎn)第二輪觸達(dá)率就提到了78%。第三輪微調(diào)了行為描述去掉支持、可以進(jìn)行這類空泛詞匯第三輪到了82%。這個驗(yàn)證流程強(qiáng)烈建議你保留下來。項目上線后每加一個工具、每改一次提示詞都用同一套測試任務(wù)回歸一遍能避免很多隱性退化。我后來把測試任務(wù)擴(kuò)到了50條每次重構(gòu)之前先跑一遍基線心里有底才敢動手改代碼。5. 踩坑實(shí)錄高頻問題與排查思路5.1 工具描述越長召回越差隱藏的 token 陷阱這是我踩過最大的坑也最反直覺。一開始我覺得工具描述寫得越詳細(xì)越好畢竟模型多拿點(diǎn)信息才能判斷得準(zhǔn)。結(jié)果工具描述從60字?jǐn)U展到150字之后召回率反而掉了9個百分點(diǎn)。原因是多方面的向量化工具描述時細(xì)節(jié)太多會稀釋核心語義模型對這個工具是干嘛的這一類中心語義的感知會變?nèi)醺L的描述還會占據(jù)更多Prompt空間導(dǎo)致其他必要信息被擠掉。最后我把所有工具描述嚴(yán)格限制在80個字以內(nèi)核心內(nèi)容只講做什么返回什么召回率才回到正常水平。給所有正在做工具管理的朋友一個建議工具描述不是文檔是檢索索引詞。寫的時候想象用戶會用什么話提起這個功能然后把這些話原樣寫進(jìn)去遠(yuǎn)比堆參數(shù)和字段名有效。5.2 多智能體互相等待路由超時與死鎖處理多智能體場景比單Agent更容易出問題最典型的是互相等待。子Agent A給子Agent B發(fā)了一個任務(wù)B完成之后想把結(jié)果交給A但A正在等B的結(jié)果等B把結(jié)果發(fā)回去A已經(jīng)超時了于是A又重發(fā)任務(wù)B又開始處理結(jié)果B的處理隊列里積壓了一堆同一個任務(wù)。我遇到過一次線上事故系統(tǒng)里睡了20多個Agent任務(wù)全部卡在這種互相等待的狀態(tài)里。排查到最后根因是路由層沒有設(shè)置超時子Agent回調(diào)響應(yīng)等不到就無限期阻塞。解法是在路由層加一個全局任務(wù)超時默認(rèn)30秒超時后直接標(biāo)記該任務(wù)為失敗并釋放線程。同時要求所有子Agent的響應(yīng)必須攜帶request_id這樣主調(diào)度器能明確知道哪條消息對應(yīng)哪個任務(wù)即使消息亂序也不會錯配。5.3 外部工具不可用時的連鎖反應(yīng)降級與兜底策略最后一個高頻問題是外部API不穩(wěn)定導(dǎo)致的連鎖失敗。Agent-Reach調(diào)用的工具里有一大半是外部服務(wù)比如GitHub API、天氣API、數(shù)據(jù)庫服務(wù)這些服務(wù)總有不可用的時候。一開始外部API抖動Agent就瘋狂重試把限流額度打滿然后整個鏈路被拖垮。后來我加了兩層防線第一層是每個外部工具獨(dú)立配置超時和重試次數(shù)最多重試1次間隔100毫秒不允許無限重試第二層是工具狀態(tài)標(biāo)記同一工具連續(xù)失敗3次就標(biāo)記為degraded檢索時它的排序權(quán)重自動下調(diào)到接近零讓其他可用的替代工具有機(jī)會頂上。這套降級策略上線后外部服務(wù)波動期間的整體任務(wù)完成率從51%提到了73%雖然部分任務(wù)因?yàn)橐蕾嚨腁PI掛掉確實(shí)沒法完成但至少沒有讓一個問題拖垮全部任務(wù)。另外記住一點(diǎn)降級策略要能手動觸發(fā)出故障時運(yùn)維能一鍵調(diào)整參數(shù)不要在代碼里把閾值寫死不然后面想調(diào)都調(diào)不了。寫這篇總結(jié)的時候我正好又在調(diào)一個新Agent的聯(lián)調(diào)配置?；叵脒@兩周的經(jīng)歷最大的感受是Agent的推理能力固然重要但觸達(dá)能力決定了它能不能把智商用出來。如果你也在做類似的東西我建議先從工具注冊表的規(guī)范做起這一步看起來不起眼但體感影響最大。最后分享一個小技巧給每個工具寫行為描述時我會刻意用結(jié)果導(dǎo)向的句式比如返回搜索到的倉庫列表和star數(shù)而不是支持搜索倉庫功能實(shí)測下來這種描述對模型的召回命中率提升非常明顯你可以直接試一試。