計與實戰(zhàn)：從粒度劃分到動態(tài)裝載)
最近社區(qū)里聊得最多的就是把大模型從“能聊”變成“能干活”而這一切的落地關(guān)鍵就在agent-skills這四個字上。你可以把技能理解成Agent的操作手冊模型本身再聰明如果沒法穩(wěn)定調(diào)用工具、讀寫數(shù)據(jù)、執(zhí)行流程它依然只是個聊天機器人。我過去大半年一直在做技能庫的設(shè)計與落地從最初手寫十幾個if-else串聯(lián)工具函數(shù)到后來抽象出一套可注冊、可編排、可獨立測試的技能體系中間踩了不少坑也總結(jié)出一套直接能用的打法。這篇文章不聊虛的就講清楚技能體系到底是什么、怎么拆、怎么寫、怎么調(diào)以及在真實業(yè)務里會踩到哪些坑。agent-skills本質(zhì)上是一層“能力中間層”它把模型和業(yè)務工具解耦開。模型不需要知道每個接口的內(nèi)部實現(xiàn)只需要知道“什么場景下該調(diào)用哪個技能、傳什么參數(shù)”而技能本身負責把模型的意圖翻譯成可執(zhí)行的函數(shù)調(diào)用再把結(jié)果整理成模型能理解的結(jié)構(gòu)化返回。這套設(shè)計看著簡單真做起來從技能粒度劃分到參數(shù)Schema設(shè)計每一步都有講究。1. 內(nèi)容整體設(shè)計與思路拆解1.1 為什么Agent需要一套“技能”體系先看一個最原始的場景你讓Agent幫忙查天氣并安排行程。沒有技能體系時你會怎么做大概率是讓模型自由發(fā)揮希望它自己調(diào)用天氣接口、日歷接口。但實際上模型很可能把城市參數(shù)傳錯、把天氣數(shù)據(jù)里的溫度和風速字段搞混、甚至在用戶說“下午出門”時不知道應該查14點到18點的降水概率。這不是模型不聰明而是它缺少“操作的規(guī)矩”。技能體系的第一個作用是給模型的每次調(diào)用立規(guī)矩。每個技能都有明確的觸發(fā)條件、輸入?yún)?shù)約束、執(zhí)行流程和輸出格式。模型在決策時看到的不是一堆零散的接口文檔而是幾張結(jié)構(gòu)清晰的“技能卡片”它只需要做選擇題當前任務匹配哪個技能。這大大降低了模型的自由發(fā)揮空間也讓錯誤模式從隨機變成可預期。第二個作用是讓能力可以被沉淀和復用。項目做大了之后你會發(fā)現(xiàn)很多操作是跨場景重復出現(xiàn)的比如“解析用戶地址”“格式化金額”“檢查庫存狀態(tài)”。這些邏輯如果不抽象成技能就會分散在多個Prompt里改一處要動全局。抽象成技能之后它們就變成了獨立模塊任何新的Agent都可以通過“裝載技能”的方式獲得這些能力不需要重新寫一遍。第三個作用也是我后來才深刻體會到的技能體系是Agent安全性和可觀測性的最小抓手。每個技能都是一個受控的入口調(diào)用記錄可以被審計參數(shù)可以被校驗執(zhí)行結(jié)果可以被追蹤。想讓Agent只能做特定范圍內(nèi)的事情你不需要去約束模型的每一句話只需要控制它手上有什么技能、每個技能允許什么參數(shù)就夠了。1.2 技能粒度怎么定技能粒度是設(shè)計階段最糾結(jié)的問題。定太粗一個技能里塞了太多邏輯模型難以準確觸發(fā)參數(shù)組合爆炸定太細技能數(shù)量膨脹模型在決策時面對幾十個候選選擇困難LLM的上下文窗口也吃不消。我實踐下來比較穩(wěn)妥的粒度標準是一個技能最好只對應一個完整的用戶意圖原子操作。什么叫原子操作就是不需要用戶再補充額外信息、不需要依賴另一個技能結(jié)果就能完成的最小閉環(huán)。“查詢天氣”算原子操作“安排行程”就不算因為它需要先查天氣、再查路線、再排時間這應該是一個工作流Workflow由多個技能編排而成。舉個例子。我在一個電商客服Agent里最初設(shè)計了“處理售后”這個技能結(jié)果模型經(jīng)常不知道該傳order_id還是refund_id內(nèi)部邏輯又長又繞。后來拆成“查詢訂單”“提交退款申請”“查詢退款進度”三個技能準確率立刻上去了。原因很簡單技能內(nèi)部的判斷分支越少模型需要做的決策越少出錯的概率自然指數(shù)下降。還有一個經(jīng)驗值分享給你如果技能描述需要寫超過50個字才能講清楚觸發(fā)條件說明粒度多半粗了。技能描述應該像一個精準的電梯演講幾秒鐘就能讓模型明白我在什么時候該用你。這個標準我?guī)缀跤迷诹怂许椖可隙己莒`。2. 核心細節(jié)解析與實操要點2.1 技能聲明與參數(shù)設(shè)計技能聲明的格式直接決定了模型能不能讀懂你的技能?，F(xiàn)在主流Agent框架普遍采用類函數(shù)描述的方式一個技能聲明包含四部分技能名稱、功能描述、參數(shù)Schema、執(zhí)行目標。其中最重要的是參數(shù)Schema和功能描述這兩個地方寫不好后面全盤皆輸。先看參數(shù)Schema。大模型本身不擅長解讀嵌套過深的JSON結(jié)構(gòu)你給它一個包含三層嵌套、類型模糊的參數(shù)字段它大概率會傳錯。我在設(shè)計時堅持幾條原則盡量使用扁平結(jié)構(gòu)不要超過兩層嵌套。所有參數(shù)必須聲明類型和取值范圍比如city要明確是城市中文名而不是經(jīng)緯度date要明確是YYYY-MM-DD格式。必填參數(shù)控制在三個以內(nèi)超過三個模型漏傳的概率大幅上升。如果確實需要很多信息考慮拆成多個技能或者引導用戶說清楚后再觸發(fā)。參數(shù)名用業(yè)務語義直給的詞不要用縮寫。比如用delivery_address而不是da用preferred_time而不是pt。功能描述同樣大有講究。很多開發(fā)者喜歡把描述寫成“該技能用于處理查詢天氣的需求”實際上這是句廢話。好的描述應該包含觸發(fā)場景、前置條件、執(zhí)行結(jié)果、邊界說明。比如天氣查詢技能的描述至少明確當用戶詢問某城市當前天氣、未來天氣預報、氣溫、降水、風級等氣象信息時應調(diào)用本技能。用戶未指明城市時技能應使用上下文已確認的城市不得自行猜測默認城市。執(zhí)行后返回城市名、日期、天氣現(xiàn)象、最高最低氣溫、降水概率。注意那句“不得自行猜測默認城市”這類負面約束在描述里特別重要。模型天生傾向于“腦補”你明確劃出紅線它才能老老實實向你確認。2.2 技能描述與上下文注入的取舍技能描述寫得再完善如果全部塞進上下文一次要占掉幾千Token。模型上下文窗口有限幾十個技能全量注入雙方的預算都會爆炸直接在真實場景里會因為互相覆蓋而參數(shù)串臺。我實測過一組對照數(shù)據(jù)全量注入還是按策略注入同為查詢庫存與物流信息兩個技能后者在復雜場景參數(shù)準確性提升了大約兩到三成。原因也簡單按需注入讓模型在每個決策點只看到少量相關(guān)技能決策面窄反而更穩(wěn)?，F(xiàn)在我的做法是三段式路由第一段用一次輕量分類請求讓模型判斷當前請求屬于哪個技能域這個請求只注入技能名稱和一句話描述開銷極小。第二段根據(jù)分類結(jié)果只加載對應域內(nèi)兩到三個技能的完整描述、參數(shù)Schema和示例讓模型做具體決策。第三段如果分類置信度低或參數(shù)缺失額外注入一次“澄清引導”指令讓模型主動向用戶追問缺失字段而不是硬著頭皮瞎傳。這樣整體注入量從全量時的幾萬個Token壓縮到每次幾千Token響應速度提升非常明顯。尤其是做線上業(yè)務時每輪調(diào)用的延遲直接關(guān)系到用戶體驗這個優(yōu)化很值。2.3 技能命名和歸類規(guī)范命名這事看似是小問題實際在模型決策時影響很大。大模型對特征的識別是基于語義空間的相似度如果你的技能名稱和別的技能描述相互重疊它在觸發(fā)時就會徘徊不定。所以命名要遵循一個原則名稱本身就能獨立表達技能的獨特語義。我處理過一個典型的沖撞原來同時存在“查詢訂單進度”和“查詢物流信息”兩個技能模型經(jīng)常在兩者之間猶豫甚至出現(xiàn)查訂單時返回物流信息的情況。后來把名稱改成了“查詢訂單支付與處理狀態(tài)”和“查詢包裹配送軌跡”并同步調(diào)整了描述沖撞立刻緩解。因為新名稱在語義邊界上劃分得更清晰一個管訂單狀態(tài)本身一個管實物配送環(huán)節(jié)。歸類方面建議在技能聲明里增加category字段方便做技能域的聚合管理。比如電商域、出行域、營銷域這樣在做路由決策時可以直接按域去檢索效率會高很多。還有一個不易察覺的細節(jié)技能名稱不要用過于通用的動詞比如“查詢”“獲取”“處理”這類詞幾乎出現(xiàn)在所有技能里模型區(qū)分起來很費勁。盡量用名詞性短語把對象在名稱里點出來。3. 實操過程與核心環(huán)節(jié)實現(xiàn)3.1 搭建一個最小技能模塊理論說了不少下面來點實際的。我們先從一個“查庫存”技能看起這個技能足夠小也足夠通用。目標是讓Agent只憑一句“這個商品還有貨嗎”就能準確調(diào)用技能并拿到結(jié)構(gòu)化的庫存結(jié)果。# 最小技能模塊示例 { name: 商品庫存查詢, category: 訂單_庫存, description: 當用戶詢問指定商品是否有貨、當前庫存數(shù)量、可售狀態(tài)等情況時觸發(fā)。觸發(fā)前提為用戶已明確指出商品ID或提供可明確對應商品的鏈接/名稱。不得用猜測的商品ID查詢商品ID缺失時返回提示并要求用戶補充。, parameters: { type: object, properties: { sku_id: { type: string, description: 商品的SKU ID必須是系統(tǒng)內(nèi)存在的標識例如SKU20240101 } }, required: [sku_id] }, handler: fetch_stock_by_sku }這段聲明描述里我特意加了觸發(fā)前提并明確“不得用猜測的商品ID查詢”。這樣模型在用戶沒說具體商品時就不會自作主張地猜測后亂調(diào)而是主動追問。這是經(jīng)驗里最實用的一招把臨界命令寫在描述里。所謂臨界命令是指用戶輸入不滿足觸發(fā)條件時模型應該怎么辦。默認情況下模型可能會強行調(diào)用你不如提前替它想好路徑。然后是handler字段它指向一個實際的業(yè)務函數(shù)。這個函數(shù)只需要做一件事接收聲明里的參數(shù)去查數(shù)據(jù)庫返回結(jié)果。它不關(guān)心上下文也不處理對話邏輯保持純粹的執(zhí)行身份后續(xù)才能被各種上游復用。接著是結(jié)果返回格式我長期用的模板是{ status: ok, data: { sku_id: ..., available: true, stock: 23 } }。用available這類布爾值做第一層摘要data里放明細既能被后續(xù)流程讀取也可以直接拼裝成用戶可讀的答復。3.2 技能注冊與動態(tài)裝載技能模塊只是一個靜態(tài)聲明要讓Agent跑起來還需要把它們注冊到一個統(tǒng)一管理的技能倉庫里。我推薦的模式是每個技能對應一個文件按域建目錄啟動時全量掃描注冊。這樣新增技能不需要改任何主流程代碼塞個文件進去就能生效。# 技能倉庫的注冊與裝載邏輯偽碼示例 SKILL_REGISTRY {} def register_skill(skill_definition): key skill_definition[name] if key in SKILL_REGISTRY: raise DuplicatedSkillError(key) SKILL_REGISTRY[key] skill_definition def load_skills_from_directory(skills_path): for domain_dir in os.listdir(skills_path): for skill_file in glob.glob(f{skills_path}/{domain_dir}/*.json): with open(skill_file) as f: skill_definition json.load(f) skill_definition[category] domain_dir register_skill(skill_definition) def retrieve_skills(query, top_k2): # 基于嵌入檢索或簡單關(guān)鍵詞匹配召回最相關(guān)的技能 scored [] for skill in SKILL_REGISTRY.values(): score compute_semantic_similarity(query, skill[description]) scored.append((score, skill)) scored.sort(keylambda x: x[0], reverseTrue) return [skill for _, skill in scored[:top_k]]動態(tài)裝載的另一個好處是熱更新。線上業(yè)務往往需要臨時下線某個出問題的技能或者灰度測試一個新技能。在倉庫模式下只需要把對應文件改名或標記disabled在下次裝載時就不再生效。早期我把技能寫在Prompt模板里每次調(diào)整都要重新發(fā)布整個Agent服務一次迭代半小時起步。改成獨立文件注冊后改個描述、換個函數(shù)五分鐘就能生效開發(fā)和聯(lián)調(diào)效率完全是兩個量級。3.3 技能執(zhí)行的完整鏈路有了技能聲明和裝載機制還要打通從用戶請求到技能執(zhí)行的完整鏈路。我的鏈路分五步每一步都有明確的數(shù)據(jù)約定第一步用戶輸入標準化。把用戶原始語句統(tǒng)一轉(zhuǎn)成{ query: ..., history: [...] }結(jié)構(gòu)。第二步技能路由。用第一次模型調(diào)用或規(guī)則匹配選出最相關(guān)的技能域并加載技能描述。第三步參數(shù)提取。這一步是模型調(diào)用核心是把用戶語句映射成技能參數(shù)JSON。第四步參數(shù)校驗與執(zhí)行。校驗不通過就返回錯誤碼由框架決定是追問還是走兜底校驗通過則調(diào)用handler拿到結(jié)構(gòu)化結(jié)果。第五步結(jié)果轉(zhuǎn)述。把結(jié)構(gòu)化結(jié)果交給模型用口語化表述回復用戶。這里最容易出問題的是第三步。參數(shù)提取時模型容易受聊天歷史干擾比如用戶之前說過一個城市現(xiàn)在問別的事模型提取參數(shù)時可能錯誤帶入上一次的實體。我在做這一步時會在提取Prompt里顯式加一句僅基于當前用戶消息提取參數(shù)不要在歷史對話中推測信息。同時提取結(jié)果必須輸出嚴格的JSON任何多余的文字都會導致解析失敗所以我會在解析層加兜底如果解析失敗就啟用一個基于規(guī)則的實體識別模塊作為降級方案保證鏈路不至于中斷。4. 常見問題與排查技巧實錄4.1 模型“想不起來”用技能你明明把技能寫得清清楚楚但模型就是在該調(diào)用的時候不調(diào)用這幾乎每個做Agent開發(fā)的人都遇到過。排查時不要直接懷疑模型能力先看看你的檢索環(huán)節(jié)召回了什么。早期的調(diào)試經(jīng)歷里我遇到最多的情況是top_k設(shè)置太小真正相關(guān)的技能沒有被召回或者候選技能語義太接近模型在兩者之間徘徊之后干脆不調(diào)用了。給一個實用經(jīng)驗檢索結(jié)果返回給模型時不僅給技能描述還要給每個技能附上一到兩個典型觸發(fā)例句。比如庫存技能附帶“這個還有貨嗎”“現(xiàn)在下單幾天能發(fā)”這樣的例句模型看到例句后能更快理解這個技能對應什么樣的用戶表達觸發(fā)率明顯提升。這個技巧實踐下來效果很顯著屬于低成本高收益的優(yōu)化方向。還有一種情況是上下文污染。如果歷史消息里有大量無關(guān)的對話模型容易被帶偏忘了手邊有工具可用。我的做法是在每次路由決策前先裁剪歷史只保留與當前請求相關(guān)的對話片段并把“你有以下技能可用”這句話放在上下文最靠后的位置。讓指令靠近上下文尾部模型通常更容易注意到同時直接削減不必要的歷史噪聲。還有一個偏門但有效的思路如果模型始終不用某技能不妨檢查一下技能名稱本身是否過于抽象。我遇到過“獲取用戶偏好畫像”這種命名語義空間太大不夠直觀改成“讀取用戶歷史偏好標簽”并補充具體標簽示例后調(diào)用率一下子上來了。越是抽象的名字模型越不知道它到底能干什么寧可名字長一點也要把對象和動作說清楚好讓模型明白什么場景該參考它。4.2 參數(shù)幻覺與非法取值模型傳了不該傳的值這是比“不調(diào)用”更頭疼的問題。比如商品SKU明明不存在模型還能編一個出來日期格式不符合業(yè)務預期把“價格”字段傳成了字符串。要解決這個問題單一靠Prompt描述遠遠不夠必須做三層防御。第一層是Schema約束在參數(shù)Schema里定義好類型和枚舉值凡是不符合的直接過不了基礎(chǔ)校驗。第二層是業(yè)務校驗函數(shù)比如SKU是否真實存在于商品庫中日期是否在有效期內(nèi)這些要交給實際代碼去判斷不能依賴模型自覺。第三層是語義兜底如果校驗失敗框架自動觸發(fā)一次澄清追問讓用戶補充或確認而不是把錯誤參數(shù)一路傳遞下去。我特別想強調(diào)第二層。模型產(chǎn)生幻覺是概率性的你無法通過調(diào)Prompt讓它徹底不犯。但從“不可信”變?yōu)椤安豢蓤?zhí)行”框架層面就能攔截大批壞數(shù)據(jù)既避免臟數(shù)據(jù)污染后續(xù)業(yè)務也保護了業(yè)務流程不被帶偏。執(zhí)行器里我通常還會加一個超時和重試機制超時后返回一個明確的超時錯誤避免模型把舊的失敗記錄當作成功結(jié)果繼續(xù)向下游傳遞。4.3 技能沖突與優(yōu)先級處理當技能數(shù)量超過三十個沖突幾乎不可避免。常見沖突是不同域的兩個技能描述里都提到了“訂單”模型分不清該調(diào)哪個。這種情況下不要急著調(diào)整描述先檢查是不是技能粒度過粗或者復用邏輯沒抽象干凈必要時通過業(yè)務規(guī)則做一層路由偏好。我習慣在技能定義里加一個可選的priority字段規(guī)定在觸發(fā)器重疊時優(yōu)先使用哪個技能。但這個手段只能解決已知沖突解決不了模型自己判斷時左右搖擺的問題。更干凈的做法是把容易混淆的技能做一次歸并。比如把“查詢訂單支付與處理狀態(tài)”和“查詢包裹配送軌跡”統(tǒng)一到一個“訂單全鏈路查詢”技能下通過內(nèi)部的子步驟判斷用戶真正想看什么。這樣表面上少了一個技能實際上因為分工清晰整體穩(wěn)定性和準確率反而更高。另一個常見沖突來自共用參數(shù)的表達不一致。比如一個技能用order_id另一個技能用order_sn模型即使識別出該用訂單查詢也無法確認到底傳哪個字段。統(tǒng)一術(shù)語表在技能體系里是必需品所有跨技能引用的概念必須叫同一個名字。我在項目初期吃過這個虧兩個域各自開發(fā)等到聯(lián)調(diào)時才發(fā)現(xiàn)參數(shù)名對不上后來專門做了一次數(shù)據(jù)字典的統(tǒng)一這個問題才算徹底解決。5. 更多經(jīng)驗與擴展方向5.1 技能的一次性驗證與回歸測試技能體系做得越成熟就越需要一個自動化測試機制來兜底。每次新加或修改技能都不能只靠人工抽幾條數(shù)據(jù)試一下就上線。我采用的模式是把歷史真實請求與期望調(diào)用技能組成回歸集每次改動后跑一遍這些用例把“應該觸發(fā)哪個技能、提取哪些參數(shù)、返回什么格式”作為斷言標準智能體實際執(zhí)行結(jié)果與標準比對。這套回歸測試機制在長期迭代中價值非常大。因為技能的改動能引起幾十個既有場景的連鎖反應有時候只是改了一句描述某個邊緣case的觸發(fā)路徑就完全變了。沒有回歸測試傍身你根本不敢動老技能。而有了它改起來心里就有底測完再上線。還有一個實操細節(jié)每次跑回歸測試時把模型回答里關(guān)于技能選擇和參數(shù)提取的中間步驟記錄下來可以留存成一份決策軌跡。模型出錯時這份軌跡能直觀地看到它是如何走到錯誤結(jié)果的是檢索環(huán)節(jié)遺漏了技能描述還是參數(shù)提取時被歷史噪聲干擾大部分問題都能一眼定位到具體環(huán)節(jié)而不是對著黑盒反復猜原因。5.2 技能的可觀測性與數(shù)據(jù)回流技能上線之后日志里暴露出的數(shù)據(jù)要持續(xù)反哺優(yōu)化。我比較關(guān)注四個指標觸發(fā)準確率、參數(shù)提取通過率、執(zhí)行成功率、兜底觸發(fā)次數(shù)。前兩個直接反映模型對技能描述和Schema的理解程度第三個反映業(yè)務鏈路穩(wěn)定性第四個則能暴露出技能覆蓋的盲區(qū)。舉一個真實例子。某個客服Agent的退款技能上線后執(zhí)行成功率穩(wěn)定但觸發(fā)準確率偏低。查日志發(fā)現(xiàn)用戶說“退貨”時模型經(jīng)常觸發(fā)成“退款”把語義上相近的兩種行為搞混了。后來在技能描述里分別補充了最典型的用戶表達并給“退貨”技能加了觸發(fā)優(yōu)先級再跑回歸測試觸發(fā)準確率直接上了一個臺階。如果沒有這類數(shù)據(jù)回流機制這個問題可能要在線上潛伏好久而單靠日常人工體驗根本注意不到觸發(fā)準確率的細微變化。技能庫的數(shù)據(jù)回流還有一個用途就是反哺檢索模型。凡是發(fā)生過錯誤觸發(fā)或未觸發(fā)的樣本都值得人工復核后放進檢索訓練集。你的召回向量會越用越準技能路由的自然語言匹配能力也會隨之持續(xù)變強形成一個逐漸積累的收益。5.3 從技能到工作流單個技能解決的是“怎么執(zhí)行一個動作”但真實的業(yè)務場景往往是多個動作的連續(xù)編排。比如“處理售后”需要一個完整的工作流查詢訂單、判斷售后類型、生成處理方案、提交審核、通知用戶。這五個環(huán)節(jié)由五個技能完成但它們之間的銜接順序和狀態(tài)流轉(zhuǎn)已經(jīng)超出了單個技能的職責范圍。我的做法是引入輕量級的工作流編排層把技能當作工作流里的節(jié)點。每個節(jié)點定義輸入來源和輸出去向上一個技能的結(jié)構(gòu)化結(jié)果自動映射為下一個技能的參數(shù)。這樣既保證了技能可以被單獨復用又不至于讓一個技能承擔過多邏輯。你現(xiàn)在設(shè)計技能時不用一下子想得太深但當技能數(shù)量到達一定規(guī)模工作流編排幾乎必然是你下一步的演進方向。這里節(jié)奏最好踩得穩(wěn)一點先把每個技能守住把調(diào)用鏈跑通再考慮上工作流。我在實際操作中最大的感受是工作流如果建立在基礎(chǔ)不夠穩(wěn)的技能體系上調(diào)試成本會成倍上升所以基礎(chǔ)打磨值得多花時間。最后再分享一個調(diào)整節(jié)奏的小技巧當你把一套技能寫完之后不妨試著找個完全不懂背后系統(tǒng)的朋友試用一下你的Agent看用戶用日?？谡Z提出需求時系統(tǒng)是否能準確觸發(fā)對應技能。很多技能設(shè)計上的“死角”只有換了表達方式才能暴露出來。這種體驗式測試做上幾輪你打磨技能的方向感會清晰很多。 Agent技能體系設(shè)計與實戰(zhàn)：從粒度劃分到動態(tài)裝載
最近社區(qū)里聊得最多的就是把大模型從“能聊”變成“能干活”而這一切的落地關(guān)鍵就在agent-skills這四個字上。你可以把技能理解成Agent的操作手冊模型本身再聰明如果沒法穩(wěn)定調(diào)用工具、讀寫數(shù)據(jù)、執(zhí)行流程它依然只是個聊天機器人。我過去大半年一直在做技能庫的設(shè)計與落地從最初手寫十幾個if-else串聯(lián)工具函數(shù)到后來抽象出一套可注冊、可編排、可獨立測試的技能體系中間踩了不少坑也總結(jié)出一套直接能用的打法。這篇文章不聊虛的就講清楚技能體系到底是什么、怎么拆、怎么寫、怎么調(diào)以及在真實業(yè)務里會踩到哪些坑。agent-skills本質(zhì)上是一層“能力中間層”它把模型和業(yè)務工具解耦開。模型不需要知道每個接口的內(nèi)部實現(xiàn)只需要知道“什么場景下該調(diào)用哪個技能、傳什么參數(shù)”而技能本身負責把模型的意圖翻譯成可執(zhí)行的函數(shù)調(diào)用再把結(jié)果整理成模型能理解的結(jié)構(gòu)化返回。這套設(shè)計看著簡單真做起來從技能粒度劃分到參數(shù)Schema設(shè)計每一步都有講究。1. 內(nèi)容整體設(shè)計與思路拆解1.1 為什么Agent需要一套“技能”體系先看一個最原始的場景你讓Agent幫忙查天氣并安排行程。沒有技能體系時你會怎么做大概率是讓模型自由發(fā)揮希望它自己調(diào)用天氣接口、日歷接口。但實際上模型很可能把城市參數(shù)傳錯、把天氣數(shù)據(jù)里的溫度和風速字段搞混、甚至在用戶說“下午出門”時不知道應該查14點到18點的降水概率。這不是模型不聰明而是它缺少“操作的規(guī)矩”。技能體系的第一個作用是給模型的每次調(diào)用立規(guī)矩。每個技能都有明確的觸發(fā)條件、輸入?yún)?shù)約束、執(zhí)行流程和輸出格式。模型在決策時看到的不是一堆零散的接口文檔而是幾張結(jié)構(gòu)清晰的“技能卡片”它只需要做選擇題當前任務匹配哪個技能。這大大降低了模型的自由發(fā)揮空間也讓錯誤模式從隨機變成可預期。第二個作用是讓能力可以被沉淀和復用。項目做大了之后你會發(fā)現(xiàn)很多操作是跨場景重復出現(xiàn)的比如“解析用戶地址”“格式化金額”“檢查庫存狀態(tài)”。這些邏輯如果不抽象成技能就會分散在多個Prompt里改一處要動全局。抽象成技能之后它們就變成了獨立模塊任何新的Agent都可以通過“裝載技能”的方式獲得這些能力不需要重新寫一遍。第三個作用也是我后來才深刻體會到的技能體系是Agent安全性和可觀測性的最小抓手。每個技能都是一個受控的入口調(diào)用記錄可以被審計參數(shù)可以被校驗執(zhí)行結(jié)果可以被追蹤。想讓Agent只能做特定范圍內(nèi)的事情你不需要去約束模型的每一句話只需要控制它手上有什么技能、每個技能允許什么參數(shù)就夠了。1.2 技能粒度怎么定技能粒度是設(shè)計階段最糾結(jié)的問題。定太粗一個技能里塞了太多邏輯模型難以準確觸發(fā)參數(shù)組合爆炸定太細技能數(shù)量膨脹模型在決策時面對幾十個候選選擇困難LLM的上下文窗口也吃不消。我實踐下來比較穩(wěn)妥的粒度標準是一個技能最好只對應一個完整的用戶意圖原子操作。什么叫原子操作就是不需要用戶再補充額外信息、不需要依賴另一個技能結(jié)果就能完成的最小閉環(huán)。“查詢天氣”算原子操作“安排行程”就不算因為它需要先查天氣、再查路線、再排時間這應該是一個工作流Workflow由多個技能編排而成。舉個例子。我在一個電商客服Agent里最初設(shè)計了“處理售后”這個技能結(jié)果模型經(jīng)常不知道該傳order_id還是refund_id內(nèi)部邏輯又長又繞。后來拆成“查詢訂單”“提交退款申請”“查詢退款進度”三個技能準確率立刻上去了。原因很簡單技能內(nèi)部的判斷分支越少模型需要做的決策越少出錯的概率自然指數(shù)下降。還有一個經(jīng)驗值分享給你如果技能描述需要寫超過50個字才能講清楚觸發(fā)條件說明粒度多半粗了。技能描述應該像一個精準的電梯演講幾秒鐘就能讓模型明白我在什么時候該用你。這個標準我?guī)缀跤迷诹怂许椖可隙己莒`。2. 核心細節(jié)解析與實操要點2.1 技能聲明與參數(shù)設(shè)計技能聲明的格式直接決定了模型能不能讀懂你的技能?，F(xiàn)在主流Agent框架普遍采用類函數(shù)描述的方式一個技能聲明包含四部分技能名稱、功能描述、參數(shù)Schema、執(zhí)行目標。其中最重要的是參數(shù)Schema和功能描述這兩個地方寫不好后面全盤皆輸。先看參數(shù)Schema。大模型本身不擅長解讀嵌套過深的JSON結(jié)構(gòu)你給它一個包含三層嵌套、類型模糊的參數(shù)字段它大概率會傳錯。我在設(shè)計時堅持幾條原則盡量使用扁平結(jié)構(gòu)不要超過兩層嵌套。所有參數(shù)必須聲明類型和取值范圍比如city要明確是城市中文名而不是經(jīng)緯度date要明確是YYYY-MM-DD格式。必填參數(shù)控制在三個以內(nèi)超過三個模型漏傳的概率大幅上升。如果確實需要很多信息考慮拆成多個技能或者引導用戶說清楚后再觸發(fā)。參數(shù)名用業(yè)務語義直給的詞不要用縮寫。比如用delivery_address而不是da用preferred_time而不是pt。功能描述同樣大有講究。很多開發(fā)者喜歡把描述寫成“該技能用于處理查詢天氣的需求”實際上這是句廢話。好的描述應該包含觸發(fā)場景、前置條件、執(zhí)行結(jié)果、邊界說明。比如天氣查詢技能的描述至少明確當用戶詢問某城市當前天氣、未來天氣預報、氣溫、降水、風級等氣象信息時應調(diào)用本技能。用戶未指明城市時技能應使用上下文已確認的城市不得自行猜測默認城市。執(zhí)行后返回城市名、日期、天氣現(xiàn)象、最高最低氣溫、降水概率。注意那句“不得自行猜測默認城市”這類負面約束在描述里特別重要。模型天生傾向于“腦補”你明確劃出紅線它才能老老實實向你確認。2.2 技能描述與上下文注入的取舍技能描述寫得再完善如果全部塞進上下文一次要占掉幾千Token。模型上下文窗口有限幾十個技能全量注入雙方的預算都會爆炸直接在真實場景里會因為互相覆蓋而參數(shù)串臺。我實測過一組對照數(shù)據(jù)全量注入還是按策略注入同為查詢庫存與物流信息兩個技能后者在復雜場景參數(shù)準確性提升了大約兩到三成。原因也簡單按需注入讓模型在每個決策點只看到少量相關(guān)技能決策面窄反而更穩(wěn)?，F(xiàn)在我的做法是三段式路由第一段用一次輕量分類請求讓模型判斷當前請求屬于哪個技能域這個請求只注入技能名稱和一句話描述開銷極小。第二段根據(jù)分類結(jié)果只加載對應域內(nèi)兩到三個技能的完整描述、參數(shù)Schema和示例讓模型做具體決策。第三段如果分類置信度低或參數(shù)缺失額外注入一次“澄清引導”指令讓模型主動向用戶追問缺失字段而不是硬著頭皮瞎傳。這樣整體注入量從全量時的幾萬個Token壓縮到每次幾千Token響應速度提升非常明顯。尤其是做線上業(yè)務時每輪調(diào)用的延遲直接關(guān)系到用戶體驗這個優(yōu)化很值。2.3 技能命名和歸類規(guī)范命名這事看似是小問題實際在模型決策時影響很大。大模型對特征的識別是基于語義空間的相似度如果你的技能名稱和別的技能描述相互重疊它在觸發(fā)時就會徘徊不定。所以命名要遵循一個原則名稱本身就能獨立表達技能的獨特語義。我處理過一個典型的沖撞原來同時存在“查詢訂單進度”和“查詢物流信息”兩個技能模型經(jīng)常在兩者之間猶豫甚至出現(xiàn)查訂單時返回物流信息的情況。后來把名稱改成了“查詢訂單支付與處理狀態(tài)”和“查詢包裹配送軌跡”并同步調(diào)整了描述沖撞立刻緩解。因為新名稱在語義邊界上劃分得更清晰一個管訂單狀態(tài)本身一個管實物配送環(huán)節(jié)。歸類方面建議在技能聲明里增加category字段方便做技能域的聚合管理。比如電商域、出行域、營銷域這樣在做路由決策時可以直接按域去檢索效率會高很多。還有一個不易察覺的細節(jié)技能名稱不要用過于通用的動詞比如“查詢”“獲取”“處理”這類詞幾乎出現(xiàn)在所有技能里模型區(qū)分起來很費勁。盡量用名詞性短語把對象在名稱里點出來。3. 實操過程與核心環(huán)節(jié)實現(xiàn)3.1 搭建一個最小技能模塊理論說了不少下面來點實際的。我們先從一個“查庫存”技能看起這個技能足夠小也足夠通用。目標是讓Agent只憑一句“這個商品還有貨嗎”就能準確調(diào)用技能并拿到結(jié)構(gòu)化的庫存結(jié)果。# 最小技能模塊示例 { name: 商品庫存查詢, category: 訂單_庫存, description: 當用戶詢問指定商品是否有貨、當前庫存數(shù)量、可售狀態(tài)等情況時觸發(fā)。觸發(fā)前提為用戶已明確指出商品ID或提供可明確對應商品的鏈接/名稱。不得用猜測的商品ID查詢商品ID缺失時返回提示并要求用戶補充。, parameters: { type: object, properties: { sku_id: { type: string, description: 商品的SKU ID必須是系統(tǒng)內(nèi)存在的標識例如SKU20240101 } }, required: [sku_id] }, handler: fetch_stock_by_sku }這段聲明描述里我特意加了觸發(fā)前提并明確“不得用猜測的商品ID查詢”。這樣模型在用戶沒說具體商品時就不會自作主張地猜測后亂調(diào)而是主動追問。這是經(jīng)驗里最實用的一招把臨界命令寫在描述里。所謂臨界命令是指用戶輸入不滿足觸發(fā)條件時模型應該怎么辦。默認情況下模型可能會強行調(diào)用你不如提前替它想好路徑。然后是handler字段它指向一個實際的業(yè)務函數(shù)。這個函數(shù)只需要做一件事接收聲明里的參數(shù)去查數(shù)據(jù)庫返回結(jié)果。它不關(guān)心上下文也不處理對話邏輯保持純粹的執(zhí)行身份后續(xù)才能被各種上游復用。接著是結(jié)果返回格式我長期用的模板是{ status: ok, data: { sku_id: ..., available: true, stock: 23 } }。用available這類布爾值做第一層摘要data里放明細既能被后續(xù)流程讀取也可以直接拼裝成用戶可讀的答復。3.2 技能注冊與動態(tài)裝載技能模塊只是一個靜態(tài)聲明要讓Agent跑起來還需要把它們注冊到一個統(tǒng)一管理的技能倉庫里。我推薦的模式是每個技能對應一個文件按域建目錄啟動時全量掃描注冊。這樣新增技能不需要改任何主流程代碼塞個文件進去就能生效。# 技能倉庫的注冊與裝載邏輯偽碼示例 SKILL_REGISTRY {} def register_skill(skill_definition): key skill_definition[name] if key in SKILL_REGISTRY: raise DuplicatedSkillError(key) SKILL_REGISTRY[key] skill_definition def load_skills_from_directory(skills_path): for domain_dir in os.listdir(skills_path): for skill_file in glob.glob(f{skills_path}/{domain_dir}/*.json): with open(skill_file) as f: skill_definition json.load(f) skill_definition[category] domain_dir register_skill(skill_definition) def retrieve_skills(query, top_k2): # 基于嵌入檢索或簡單關(guān)鍵詞匹配召回最相關(guān)的技能 scored [] for skill in SKILL_REGISTRY.values(): score compute_semantic_similarity(query, skill[description]) scored.append((score, skill)) scored.sort(keylambda x: x[0], reverseTrue) return [skill for _, skill in scored[:top_k]]動態(tài)裝載的另一個好處是熱更新。線上業(yè)務往往需要臨時下線某個出問題的技能或者灰度測試一個新技能。在倉庫模式下只需要把對應文件改名或標記disabled在下次裝載時就不再生效。早期我把技能寫在Prompt模板里每次調(diào)整都要重新發(fā)布整個Agent服務一次迭代半小時起步。改成獨立文件注冊后改個描述、換個函數(shù)五分鐘就能生效開發(fā)和聯(lián)調(diào)效率完全是兩個量級。3.3 技能執(zhí)行的完整鏈路有了技能聲明和裝載機制還要打通從用戶請求到技能執(zhí)行的完整鏈路。我的鏈路分五步每一步都有明確的數(shù)據(jù)約定第一步用戶輸入標準化。把用戶原始語句統(tǒng)一轉(zhuǎn)成{ query: ..., history: [...] }結(jié)構(gòu)。第二步技能路由。用第一次模型調(diào)用或規(guī)則匹配選出最相關(guān)的技能域并加載技能描述。第三步參數(shù)提取。這一步是模型調(diào)用核心是把用戶語句映射成技能參數(shù)JSON。第四步參數(shù)校驗與執(zhí)行。校驗不通過就返回錯誤碼由框架決定是追問還是走兜底校驗通過則調(diào)用handler拿到結(jié)構(gòu)化結(jié)果。第五步結(jié)果轉(zhuǎn)述。把結(jié)構(gòu)化結(jié)果交給模型用口語化表述回復用戶。這里最容易出問題的是第三步。參數(shù)提取時模型容易受聊天歷史干擾比如用戶之前說過一個城市現(xiàn)在問別的事模型提取參數(shù)時可能錯誤帶入上一次的實體。我在做這一步時會在提取Prompt里顯式加一句僅基于當前用戶消息提取參數(shù)不要在歷史對話中推測信息。同時提取結(jié)果必須輸出嚴格的JSON任何多余的文字都會導致解析失敗所以我會在解析層加兜底如果解析失敗就啟用一個基于規(guī)則的實體識別模塊作為降級方案保證鏈路不至于中斷。4. 常見問題與排查技巧實錄4.1 模型“想不起來”用技能你明明把技能寫得清清楚楚但模型就是在該調(diào)用的時候不調(diào)用這幾乎每個做Agent開發(fā)的人都遇到過。排查時不要直接懷疑模型能力先看看你的檢索環(huán)節(jié)召回了什么。早期的調(diào)試經(jīng)歷里我遇到最多的情況是top_k設(shè)置太小真正相關(guān)的技能沒有被召回或者候選技能語義太接近模型在兩者之間徘徊之后干脆不調(diào)用了。給一個實用經(jīng)驗檢索結(jié)果返回給模型時不僅給技能描述還要給每個技能附上一到兩個典型觸發(fā)例句。比如庫存技能附帶“這個還有貨嗎”“現(xiàn)在下單幾天能發(fā)”這樣的例句模型看到例句后能更快理解這個技能對應什么樣的用戶表達觸發(fā)率明顯提升。這個技巧實踐下來效果很顯著屬于低成本高收益的優(yōu)化方向。還有一種情況是上下文污染。如果歷史消息里有大量無關(guān)的對話模型容易被帶偏忘了手邊有工具可用。我的做法是在每次路由決策前先裁剪歷史只保留與當前請求相關(guān)的對話片段并把“你有以下技能可用”這句話放在上下文最靠后的位置。讓指令靠近上下文尾部模型通常更容易注意到同時直接削減不必要的歷史噪聲。還有一個偏門但有效的思路如果模型始終不用某技能不妨檢查一下技能名稱本身是否過于抽象。我遇到過“獲取用戶偏好畫像”這種命名語義空間太大不夠直觀改成“讀取用戶歷史偏好標簽”并補充具體標簽示例后調(diào)用率一下子上來了。越是抽象的名字模型越不知道它到底能干什么寧可名字長一點也要把對象和動作說清楚好讓模型明白什么場景該參考它。4.2 參數(shù)幻覺與非法取值模型傳了不該傳的值這是比“不調(diào)用”更頭疼的問題。比如商品SKU明明不存在模型還能編一個出來日期格式不符合業(yè)務預期把“價格”字段傳成了字符串。要解決這個問題單一靠Prompt描述遠遠不夠必須做三層防御。第一層是Schema約束在參數(shù)Schema里定義好類型和枚舉值凡是不符合的直接過不了基礎(chǔ)校驗。第二層是業(yè)務校驗函數(shù)比如SKU是否真實存在于商品庫中日期是否在有效期內(nèi)這些要交給實際代碼去判斷不能依賴模型自覺。第三層是語義兜底如果校驗失敗框架自動觸發(fā)一次澄清追問讓用戶補充或確認而不是把錯誤參數(shù)一路傳遞下去。我特別想強調(diào)第二層。模型產(chǎn)生幻覺是概率性的你無法通過調(diào)Prompt讓它徹底不犯。但從“不可信”變?yōu)椤安豢蓤?zhí)行”框架層面就能攔截大批壞數(shù)據(jù)既避免臟數(shù)據(jù)污染后續(xù)業(yè)務也保護了業(yè)務流程不被帶偏。執(zhí)行器里我通常還會加一個超時和重試機制超時后返回一個明確的超時錯誤避免模型把舊的失敗記錄當作成功結(jié)果繼續(xù)向下游傳遞。4.3 技能沖突與優(yōu)先級處理當技能數(shù)量超過三十個沖突幾乎不可避免。常見沖突是不同域的兩個技能描述里都提到了“訂單”模型分不清該調(diào)哪個。這種情況下不要急著調(diào)整描述先檢查是不是技能粒度過粗或者復用邏輯沒抽象干凈必要時通過業(yè)務規(guī)則做一層路由偏好。我習慣在技能定義里加一個可選的priority字段規(guī)定在觸發(fā)器重疊時優(yōu)先使用哪個技能。但這個手段只能解決已知沖突解決不了模型自己判斷時左右搖擺的問題。更干凈的做法是把容易混淆的技能做一次歸并。比如把“查詢訂單支付與處理狀態(tài)”和“查詢包裹配送軌跡”統(tǒng)一到一個“訂單全鏈路查詢”技能下通過內(nèi)部的子步驟判斷用戶真正想看什么。這樣表面上少了一個技能實際上因為分工清晰整體穩(wěn)定性和準確率反而更高。另一個常見沖突來自共用參數(shù)的表達不一致。比如一個技能用order_id另一個技能用order_sn模型即使識別出該用訂單查詢也無法確認到底傳哪個字段。統(tǒng)一術(shù)語表在技能體系里是必需品所有跨技能引用的概念必須叫同一個名字。我在項目初期吃過這個虧兩個域各自開發(fā)等到聯(lián)調(diào)時才發(fā)現(xiàn)參數(shù)名對不上后來專門做了一次數(shù)據(jù)字典的統(tǒng)一這個問題才算徹底解決。5. 更多經(jīng)驗與擴展方向5.1 技能的一次性驗證與回歸測試技能體系做得越成熟就越需要一個自動化測試機制來兜底。每次新加或修改技能都不能只靠人工抽幾條數(shù)據(jù)試一下就上線。我采用的模式是把歷史真實請求與期望調(diào)用技能組成回歸集每次改動后跑一遍這些用例把“應該觸發(fā)哪個技能、提取哪些參數(shù)、返回什么格式”作為斷言標準智能體實際執(zhí)行結(jié)果與標準比對。這套回歸測試機制在長期迭代中價值非常大。因為技能的改動能引起幾十個既有場景的連鎖反應有時候只是改了一句描述某個邊緣case的觸發(fā)路徑就完全變了。沒有回歸測試傍身你根本不敢動老技能。而有了它改起來心里就有底測完再上線。還有一個實操細節(jié)每次跑回歸測試時把模型回答里關(guān)于技能選擇和參數(shù)提取的中間步驟記錄下來可以留存成一份決策軌跡。模型出錯時這份軌跡能直觀地看到它是如何走到錯誤結(jié)果的是檢索環(huán)節(jié)遺漏了技能描述還是參數(shù)提取時被歷史噪聲干擾大部分問題都能一眼定位到具體環(huán)節(jié)而不是對著黑盒反復猜原因。5.2 技能的可觀測性與數(shù)據(jù)回流技能上線之后日志里暴露出的數(shù)據(jù)要持續(xù)反哺優(yōu)化。我比較關(guān)注四個指標觸發(fā)準確率、參數(shù)提取通過率、執(zhí)行成功率、兜底觸發(fā)次數(shù)。前兩個直接反映模型對技能描述和Schema的理解程度第三個反映業(yè)務鏈路穩(wěn)定性第四個則能暴露出技能覆蓋的盲區(qū)。舉一個真實例子。某個客服Agent的退款技能上線后執(zhí)行成功率穩(wěn)定但觸發(fā)準確率偏低。查日志發(fā)現(xiàn)用戶說“退貨”時模型經(jīng)常觸發(fā)成“退款”把語義上相近的兩種行為搞混了。后來在技能描述里分別補充了最典型的用戶表達并給“退貨”技能加了觸發(fā)優(yōu)先級再跑回歸測試觸發(fā)準確率直接上了一個臺階。如果沒有這類數(shù)據(jù)回流機制這個問題可能要在線上潛伏好久而單靠日常人工體驗根本注意不到觸發(fā)準確率的細微變化。技能庫的數(shù)據(jù)回流還有一個用途就是反哺檢索模型。凡是發(fā)生過錯誤觸發(fā)或未觸發(fā)的樣本都值得人工復核后放進檢索訓練集。你的召回向量會越用越準技能路由的自然語言匹配能力也會隨之持續(xù)變強形成一個逐漸積累的收益。5.3 從技能到工作流單個技能解決的是“怎么執(zhí)行一個動作”但真實的業(yè)務場景往往是多個動作的連續(xù)編排。比如“處理售后”需要一個完整的工作流查詢訂單、判斷售后類型、生成處理方案、提交審核、通知用戶。這五個環(huán)節(jié)由五個技能完成但它們之間的銜接順序和狀態(tài)流轉(zhuǎn)已經(jīng)超出了單個技能的職責范圍。我的做法是引入輕量級的工作流編排層把技能當作工作流里的節(jié)點。每個節(jié)點定義輸入來源和輸出去向上一個技能的結(jié)構(gòu)化結(jié)果自動映射為下一個技能的參數(shù)。這樣既保證了技能可以被單獨復用又不至于讓一個技能承擔過多邏輯。你現(xiàn)在設(shè)計技能時不用一下子想得太深但當技能數(shù)量到達一定規(guī)模工作流編排幾乎必然是你下一步的演進方向。這里節(jié)奏最好踩得穩(wěn)一點先把每個技能守住把調(diào)用鏈跑通再考慮上工作流。我在實際操作中最大的感受是工作流如果建立在基礎(chǔ)不夠穩(wěn)的技能體系上調(diào)試成本會成倍上升所以基礎(chǔ)打磨值得多花時間。最后再分享一個調(diào)整節(jié)奏的小技巧當你把一套技能寫完之后不妨試著找個完全不懂背后系統(tǒng)的朋友試用一下你的Agent看用戶用日?？谡Z提出需求時系統(tǒng)是否能準確觸發(fā)對應技能。很多技能設(shè)計上的“死角”只有換了表達方式才能暴露出來。這種體驗式測試做上幾輪你打磨技能的方向感會清晰很多。