如果你也調(diào)過智能體大概率見過這種割裂感大模型嘴上功夫一流真讓它去讀寫文件、查數(shù)據(jù)、發(fā)請求它就當場“禮貌無能”只會說“我可以幫你但需要你手動操作”。去年我自己搭了一套叫 agent-skills 的技能庫項目專門治這個毛病。它不靠某個特定框架而是一套把大模型的意圖識別能力翻譯成“可執(zhí)行技能調(diào)用”的標準做法。這篇文章我會把當初做這個技能庫的設(shè)計思路、目錄結(jié)構(gòu)、核心代碼骨架、多Agent復(fù)用的方案全都拆開講包括我踩過的坑。如果你正在做Agent、準備接工具調(diào)用、或者糾結(jié)怎么讓自己的智能體能真正“干活”這篇文章應(yīng)該比看一堆概念教程有用。1. 先說清楚agent-skills 到底解決什么問題1.1 一個常見的翻車現(xiàn)場Agent 死活不干活我接手過一個內(nèi)部需求讓大模型讀某個數(shù)據(jù)文件按固定模板生成匯總報告然后把報告寫到指定目錄。最開始同事直接打開帶對話界面的Agent讓它“看一下文件然后生成一份周報”。結(jié)果模型每次回答都是“我可以幫你總結(jié)”可文件它始終沒讀對生成的內(nèi)容也是對話窗口里的一段文字而不是實際落盤的文件。這就暴露了當前大模型的本質(zhì)它擅長理解意圖、生成文本但天生不適合執(zhí)行精確的、有副作用的動作。模型不是不知道“寫文件”是什么而是它沒有穩(wěn)定的“手”去調(diào)文件系統(tǒng)。你讓它連續(xù)做兩次文件操作哪怕參數(shù)一模一樣也可能一次成功、一次漏掉。這種不穩(wěn)定性靠“prompt寫得更好”很難徹底解決真正可靠的辦法是給模型配一套確定性的技能調(diào)用通道。agent-skills 出場的時機就在這里把每個具體動作比如“讀取文件”“寫文件”“發(fā)HTTP請求”“查數(shù)據(jù)庫”“發(fā)郵件”封裝成獨立的小模塊并在模塊頂部寫清楚“什么時候用、參數(shù)是什么、返回什么樣”。大模型不需要親手執(zhí)行代碼它只需要從技能清單里挑一個、把參數(shù)填對剩下的事情由本地函數(shù)完成。1.2 技能庫的本質(zhì)把“會”變成“能做”很多人區(qū)分不了“會”和“能做”。模型讀完你的技能描述能復(fù)述功能這不難難的是在真實任務(wù)里穩(wěn)定觸發(fā)對應(yīng)動作、傳對參數(shù)、處理好返回結(jié)果。技能庫本質(zhì)上就是在這兩層中間加一道“標準化接縫”。每個技能完成一個原子動作。什么叫原子就是一次調(diào)用只做一件事別把“讀取文件解析內(nèi)容寫入數(shù)據(jù)庫”寫成一個技能。這樣做的好處有三個第一模型容易理解觸發(fā)條件清晰第二方便復(fù)用多個Agent都能調(diào)用同一個技能第三便于排查問題哪個技能出錯直接把范圍縮到那一個模塊。我用 agent-skills 這個名稱也是想強調(diào)“技能”而不是“插件”。插件往往綁定宿主系統(tǒng)技能則更像一個能力單元有名字、有描述、有輸入輸出契約、有版本可以獨立發(fā)布和更新。換一個模型、換一個Agent框架技能定義本身不用大改。1.3 為什么叫 agent-skills而不是 plugins不是故意造詞。plugin 的隱含假設(shè)是“被宿主程序加載”而 skill 的隱含假設(shè)是“被Agent按需發(fā)現(xiàn)”。一個Agent系統(tǒng)可能同時對接文檔處理、API調(diào)用、數(shù)據(jù)分析等能力如果只做插件能力之間容易耦合成一鍋粥。但技能庫把能力拆成彼此獨立的“可檢索條目”模型選技能時更像是“搜索”而不是“調(diào)用加載器”。這個區(qū)別直接決定了設(shè)計方式。插件通常要考慮框架生命周期、生命周期鉤子、界面集成技能則只需要考慮三點怎么描述、怎么執(zhí)行、怎么返回。描述決定了模型會不會選中它執(zhí)行決定了能不能跑通返回決定了模型下一步怎么走。后面的設(shè)計基本都是圍繞這三件事展開的。2. 技能庫的整體設(shè)計目錄、描述、參數(shù)與返回值2.1 目錄結(jié)構(gòu)與命名規(guī)范我的技能庫在文件層面就是一個文件夾里面每個子目錄對應(yīng)一個技能。目錄名就是技能ID全局唯一。整體長這樣skills/ ├── send_email/ │ ├── SKILL.md │ ├── skill.py │ └── requirements.txt ├── query_order/ │ ├── SKILL.md │ ├── skill.py │ └── requirements.txt ├── upload_file/ │ ├── SKILL.md │ ├── skill.py │ └── requirements.txt └── calculate_date_diff/ ├── SKILL.md └── skill.py命名規(guī)范是我踩過很多次坑之后定下來的技能ID用動詞開頭全部小寫、下劃線分隔。比如send_emailquery_order不要用emailService或者file-handling這種既有大小寫又有連字符的寫法。原因是模型在一個候選列表里做選擇時對“動詞開頭”的短名字有天然的語義偏向一眼能看出“這技能是干什么的”。如果技能ID本身就模棱兩可模型就容易挑錯。我試過把技能叫data_processing結(jié)果用戶說“幫我整理一下表格”時模型好幾次選了這個技能實際它連入?yún)⑹鞘裁炊颊f不清最后還得靠描述補。2.2 SKILL.md 描述文件長什么樣每個技能目錄里必須有一個SKILL.md。這個文件主要不是給人看的是給模型看的。模型靠讀它來決定“當前需求要不要調(diào)用這個技能”所以里面的字字句句都很關(guān)鍵。我的做法是使用 YAML front-matter 加簡短說明。下面是一個例子--- name: send_email version: 1.2.0 description: 發(fā)送一封純文本郵件。適合通知、告警、報告發(fā)送等場景。 input: 收件人地址、郵件主題、正文。 output: 返回郵件唯一ID發(fā)送失敗時返回錯誤信息。 when_to_use: 用戶明確要求發(fā)送郵件、提醒、告警或者需要把生成結(jié)果發(fā)給某人時。 when_not_to_use: 用戶只是討論郵件內(nèi)容或者要求發(fā)送附件的場景需要看附件處理技能。 permission: [network, smtp] author: internal --- ## Usage 發(fā)送一封文本郵件到指定地址。 ## Examples 用戶說給 xxxexample.com 發(fā)一封郵件主題是“周報”正文是“已完成本周工作”。 調(diào)用參數(shù){to: xxxexample.com, subject: 周報, body: 已完成本周工作}你可能會覺得描述帶when_not_to_use太啰嗦但這一步很有必要。模型在沒有限制時很容易“強行調(diào)用”技能比如用戶明明只是問“郵件服務(wù)現(xiàn)在通不通”模型卻可能真的去發(fā)一封測試郵件。把“什么時候不該用”寫清楚能明顯降低誤調(diào)用率。description原則上不要超過200字。太長了既占上下文又會讓模型抓不住重點。我實測下來一段100到150字、含觸發(fā)場景和輸入輸出的描述效果最好。2.3 參數(shù)契約讓模型像填表一樣調(diào)用技能技能描述是給模型做“要不要選我”的決策那參數(shù)定義就是給模型做“怎么填表”的決策。這塊必須用結(jié)構(gòu)化Schema不能靠自然語言描述來約束。我習(xí)慣在每個技能目錄放一個schema.json里面寫清楚參數(shù)類型、是否必填、取值范圍甚至示例值。例如send_email的參數(shù)定義{ type: object, properties: { to: { type: string, format: email, description: 收件人郵箱地址多個地址用逗號分隔 }, subject: { type: string, maxLength: 100, description: 郵件主題盡量簡短 }, body: { type: string, description: 郵件正文 } }, required: [to, subject] }真正執(zhí)行前我會先用這個Schema校驗?zāi)Ｐ蜕傻腏SON。比如模型可能把subject寫成 null或者漏掉to校驗階段直接攔截不會進入執(zhí)行函數(shù)。這么做不僅安全也能讓你快速發(fā)現(xiàn)問題次數(shù)多的字段反過來優(yōu)化描述。還有一個容易忽略的點字段名盡量用通用的小寫單詞不要用帶特殊意義的縮寫。模型如果看不懂rcpt_addr這種內(nèi)部叫法它就可能瞎猜。我后來全部改成tosubjectbody這種一看就懂的字段調(diào)用成功率明顯上升。2.4 返回值格式的約束讓結(jié)果可被后續(xù)Agent處理技能執(zhí)行完Model 還要讀返回值決定下一步。如果每個技能的返回格式都不一樣模型就亂了。所以我在 agent-skills 里統(tǒng)一了返回值格式所有技能都必須返回下面這個結(jié)構(gòu){ ok: true, data: { mail_id: a1b2c3, sent_at: 2025-01-01 10:00:00 }, error: null }失敗時返回{ ok: false, data: null, error: { code: SMTP_CONN_FAILED, message: 無法連接到郵件服務(wù)器請檢查網(wǎng)絡(luò)配置 } }為什么這么設(shè)計因為模型在決定“是否再調(diào)用下一個技能”“是否要把錯誤反饋給用戶”時需要快速識別狀態(tài)。如果每個技能成功時返回一個字符串失敗時拋個異常模型處理異常非常困難。統(tǒng)一返回值之后Agent的后續(xù)策略寫起來也簡單oktrue繼續(xù)下一個動作okfalse讀取error.message決定是否需要重新調(diào)用或告知用戶。經(jīng)驗是error.message一定要寫成“人能看懂、模型也能直接引用”的話不要寫internal error code 503。因為模型很可能原封不動地把這條信息轉(zhuǎn)述給用戶用戶看到“503”多半一臉懵。3. 核心實現(xiàn)技能注冊、加載與動態(tài)路由3.1 注冊機制聲明文件怎么進庫技能庫的注冊方式有兩種一種是“顯式注冊”在代碼里寫register(send_email)另一種是“隱式掃描”啟動時掃目錄自動發(fā)現(xiàn)。我最終選了隱式掃描主進程代碼不用改新增技能就是“丟一個文件夾進去”這么簡單。但純掃描目錄還不夠因為技能類型五花八門有Python函數(shù)有HTTP請求也有本地腳本。所以我實現(xiàn)了一個極簡注冊表用裝飾器把執(zhí)行函數(shù)綁定到技能名上# registry.py _SKILLS {} def register(name, version): 注冊一個技能到全局技能表。 def wrapper(func): _SKILLS[name] {func: func, version: version} return func return wrapper然后技能模塊內(nèi)部可以這樣寫# skill.py import registry registry.register(send_email, 1.2.0) def send_email(params: dict) - dict: 執(zhí)行發(fā)送郵件的真正邏輯。 # ... 郵件發(fā)送代碼 return {ok: True, data: {mail_id: ...}, error: None}注冊表本身不負責(zé)技能描述描述還是放在SKILL.md和schema.json里。裝飾器只需要記錄哪個函數(shù)對應(yīng)哪個技能ID真正加載時再去讀描述文件。3.2 加載器掃描目錄、解析描述、綁定執(zhí)行函數(shù)加載器我寫成一個SkillManager類它做四件事掃描skills/下所有子目錄讀取每個目錄里的SKILL.md、schema.json導(dǎo)入目錄里的skill.py拿到注冊表里對應(yīng)的執(zhí)行函數(shù)組裝成完整的技能對象放進內(nèi)存列表。示例邏輯import os import json class SkillManager: def __init__(self, skills_rootskills): self.skills_root skills_root self.skills [] def load_all(self): for skill_dir in os.listdir(self.skills_root): path os.path.join(self.skills_root, skill_dir) if not os.path.isdir(path): continue self._load_skill(path) return self.skills def _load_skill(self, path): name os.path.basename(path) skill_md_path os.path.join(path, SKILL.md) schema_path os.path.join(path, schema.json) if not os.path.exists(skill_md_path): return # 解析 SKILL.md 頭部信息簡單起見用字符串處理或 PyYAML # 讀取 schema schema {} if os.path.exists(schema_path): with open(schema_path, r, encodingutf-8) as f: schema json.load(f) # 這里執(zhí)行目錄里的 skill.py并捕獲注冊表項 # 此處略實際會 importlib 動態(tài)導(dǎo)入 self.skills.append({ name: name, description: parsed_description, schema: schema, exec_func: func_ref, })這里有個我一開始沒注意的坑動態(tài)導(dǎo)入時技能里的skill.py應(yīng)該用importlib導(dǎo)入并且要給每個技能一個獨立命名空間避免兩個技能都叫skill.py時互相覆蓋。用importlib.import_module(f{path}.skill)會讓模塊緩存混亂我最后是直接用文件路徑的哈希生成模塊名雖然丑但穩(wěn)定。3.3 動態(tài)路由模型怎么從小技能列表里選對技能技能加載完后核心問題就是用戶說了一句自然語言系統(tǒng)怎么知道該調(diào)哪個技能這里我不建議一上來就讓整個技能列表直接在模型調(diào)用接口里生成工具列表。技能少可以一旦超過二三十個上下文占用大模型的選擇準確率也會下降。我的方案分兩層第一層是“粗篩”。用文本向量的方式把用戶輸入和每個技能的 description 做相似度匹配取 topK 候選K一般在5到10之間。這一步不需要大模型參與用本地向量庫或者簡單的詞頻計算都能實現(xiàn)。第二層是“精排”。把 topK 候選技能的完整描述包括參數(shù)schema發(fā)給大模型讓它從候選里挑出真正匹配的技能并輸出調(diào)用參數(shù)。精排這一步才用到大模型的語義理解能力。這個“先粗篩后精排”的好處非常明顯上下文從幾百個技能的描述壓縮到幾個候選技能調(diào)用速度更快、模型不容易犯選擇困難癥。我早期圖省事把所有技能直接塞進prompt結(jié)果技能到100個左右時模型經(jīng)常在幾個相似技能里“舉棋不定”偶爾還會選一個明顯不相關(guān)的。3.4 權(quán)限與隔離技能越權(quán)怎么辦技能庫最大的風(fēng)險是執(zhí)行危險動作。比如某個技能可以刪文件、發(fā)外部請求、執(zhí)行 shell 命令如果只靠模型判斷“這個該不該調(diào)”等于把鑰匙交給一個容易犯迷糊的人遲早出事。我在 agent-skills 里給每個技能打上權(quán)限標簽并在執(zhí)行前做檢查。比如send_email標注permission: network, smtpdelete_file標注permission: filesystem然后在運行時設(shè)定一套策略如果當前Agent沒有被授予某個權(quán)限就算模型選擇了技能系統(tǒng)也會拒絕執(zhí)行并返回PERMISSION_DENIED。對更底層的隔離我給高危技能加了沙箱機制。簡單做法是讓技能跑在一個受限的臨時目錄里用完就清理再進一步可以用subprocess隔離進程限制可執(zhí)行文件路徑。這些措施不用一開始全做但至少要保留一個“默認拒絕高危操作”的開關(guān)否則別人拿到你的技能庫再配一個自主權(quán)限過大的Agent風(fēng)險會很大。4. 多Agent共享從單個Agent到技能市場4.1 多Agent場景下為什么需要集中式技能庫如果你只是跑一個Demo技能目錄放在本地就夠。但如果系統(tǒng)里有多個Agent分別處理客服、數(shù)據(jù)分析、自動化運維你再回頭看就會發(fā)現(xiàn)問題每個Agent都在重復(fù)造輪子。A Agent 寫了一個query_orderB Agent 又開始抄一份改改然后兩邊行為不一致修一個 bug 還要各處同步。我在項目中期做了一次重構(gòu)把技能庫從“本地文件夾”升級成“集中管理”。所有技能統(tǒng)一放在一個服務(wù)里各Agent通過接口獲取技能描述、提交調(diào)用請求。這樣每個技能只有一份實現(xiàn)更新一次所有Agent立即生效。集中式還有個額外好處可以統(tǒng)一記錄調(diào)用日志。誰調(diào)了哪個技能、傳了什么參數(shù)、返回是否成功都集中到一個日志系統(tǒng)里。后面排查“是不是技能本身壞了還是模型選錯了技能”會省很多力氣。4.2 技能兼容層同一個技能服務(wù)多個模型不同大模型對工具調(diào)用的格式千奇百怪。有的模型支持原生 function calling有的只支持在 prompt 里給一段 JSON 示例還有的需要用 XML 描述工具。如果每個模型都重寫一遍技能庫的適配層那會累死人。我在技能庫和模型之間加了一個兼容層。兼容層內(nèi)部維護一份統(tǒng)一的技能描述格式然后根據(jù)不同模型的目標格式做轉(zhuǎn)譯。比如對支持 function calling 的模型把技能名、描述、schema 轉(zhuǎn)成該模型的 function 列表對不支持 function calling 的模型把技能列表轉(zhuǎn)成一個Available skills:的文本塊讓模型在回復(fù)里夾帶一段{skill: ..., params: {...}}再解析出來。這個兼容層讓同一個技能庫可以同時服務(wù)多個Agent也降低了以后換模型的成本。好處是真實存在的我有一次把某Agent的基礎(chǔ)模型從A換到B整個過程只改了兼容層里的一個適配器技能庫本身完全沒動。4.3 技能版本號與灰度發(fā)布的實戰(zhàn)取舍技能集中之后版本管理就成了不可回避的問題。假設(shè)query_order之前返回的訂單金額字段叫amount新版改成total_amount所有依賴它的Agent都會受影響。如果沒做版本控制改一個字段可能會炸掉整個流程。我會在每個技能對象里帶version并在Agent初始化時聲明自己需要的版本范圍。集中服務(wù)更新技能時可以保留舊版本一段時間新調(diào)用走新版本舊調(diào)用繼續(xù)用舊版本直到確認沒有異常再下掉舊版本。這一套思路本質(zhì)上就是灰度發(fā)布沒必要一開始做得很重只需要在技能服務(wù)里加一個路由策略按Agent ID或流量比例選擇不同版本。我踩過的最痛的一個坑是技能返回結(jié)構(gòu)小改但沒有同步改所有下游腳本結(jié)果某個Agent后續(xù)流程里讀舊字段得到 null 以后又去調(diào)了另一個技能最后生成了完全錯誤的報告。自那之后我養(yǎng)成習(xí)慣技能返回結(jié)構(gòu)變更時必須發(fā)布為新的minor版本不允許原地改字段名。5. 實操落地我給 agent-skills 寫的骨架代碼5.1 最小化技能定義示例下面是一份能直接跑通最小閉環(huán)的骨架。假設(shè)我們要做一個read_file技能功能是讀取指定文本文件的原始內(nèi)容。目錄結(jié)構(gòu)skills/ └── read_file/ ├── SKILL.md ├── schema.json └── skill.pySKILL.md--- name: read_file version: 1.0.0 description: 讀取本地文本文件內(nèi)容。適合查看日志、讀取配置、加載文檔等場景。 input: 文件路徑。 output: 文件內(nèi)容如果文件不存在或無法讀取返回明確錯誤。 when_to_use: 用戶要求查看某文件內(nèi)容或者后續(xù)操作需要讀取文件數(shù)據(jù)時。 when_not_to_use: 用戶只是提到文件名但未要求讀取時不要擅自調(diào)用。 permission: [filesystem] --- 讀取一個本地文件的純文本內(nèi)容。schema.json{ type: object, properties: { path: { type: string, description: 要讀取的文件的絕對路徑 } }, required: [path] }skill.pyimport registry registry.register(read_file, 1.0.0) def read_file(params: dict) - dict: path params.get(path) if not path: return {ok: False, data: None, error: {code: MISSING_PATH, message: 缺少參數(shù)path}} try: with open(path, r, encodingutf-8) as f: content f.read() except FileNotFoundError: return {ok: False, data: None, error: {code: FILE_NOT_FOUND, message: f文件不存在: {path}}} except PermissionError: return {ok: False, data: None, error: {code: PERMISSION_DENIED, message: 沒有權(quán)限讀取該文件}} return {ok: True, data: {content: content[:20000]}, error: None}注意我在返回值里把內(nèi)容截斷到20000字。這是為了避免技能返回超長文本撐爆模型上下文。真正需要完整內(nèi)容時可以追加一個max_length參數(shù)超出部分讓模型分頁讀取。5.2 加載與執(zhí)行完整流程技能庫管理器需要提供兩個核心方法list_skills和execute。前者讓上層Agent獲取技能描述列表后者按技能名執(zhí)行。# skill_manager.py class SkillManager: def __init__(self): self.skills {} # ... 加載過程省略 def list_skills(self): return [ { name: name, description: skill[description], schema: skill[schema], version: skill[version], } for name, skill in self.skills.items() ] def execute(self, name, params, timeout10): skill self.skills.get(name) if not skill: return {ok: False, data: None, error: {code: SKILL_NOT_FOUND, message: f未找到技能: {name}}} # 參數(shù)校驗 # 調(diào)用執(zhí)行函數(shù)并做超時處理 return skill[func](params)執(zhí)行時用一個超時裝飾器避免技能內(nèi)部發(fā)生死循環(huán)或網(wǎng)絡(luò)阻塞。最簡單的方式是threading.Thread加result_queue或者用concurrent.futures.ThreadPoolExecutor。我實際寫的是一個run_with_timeout工具代碼不長但能在技能掛死時讓Agent繼續(xù)響應(yīng)。5.3 讓它跑起來一個簡單的調(diào)用示例把所有東西串起來以后使用流程大致是這樣manager SkillManager() manager.load_all() # 假設(shè)模型經(jīng)過粗篩和精排后決定調(diào)用 read_file result manager.execute(read_file, {path: /tmp/demo.txt}) print(result)輸出{ok: True, data: {content: hello, agent}, error: None}這個流程雖然樸素但已經(jīng)覆蓋了技能庫最核心的閉環(huán)描述驅(qū)動模型選技能、參數(shù)校驗、執(zhí)行、統(tǒng)一返回。后續(xù)要接任何Agent框架只需要在框架側(cè)把“模型輸出中的技能名參數(shù)”交給manager.execute就行。我建議先跑通這個最小版本再慢慢加向量檢索、多Agent共享和權(quán)限控制。不要一上來就把架構(gòu)搞得特別復(fù)雜否則還沒體會到技能庫的便利先被各種抽象層繞暈了。6. 常見問題與排查技巧實錄6.1 “模型就是調(diào)用不到某個技能”怎么排查這是我在群里見到最多的問題。模型明明能看到技能列表但就是不選某個技能。我排查的順序一般是這樣先看技能描述里有沒有寫到明確的觸發(fā)場景。比如用戶說“幫我看看昨晚的日志”技能描述如果只寫“讀取日志文件”并且沒有提到“昨天”“查看”這類詞模型就很容易漏掉。解決辦法是用真實對話語料去調(diào)描述把用戶最常說的幾種說法直接寫進去。再看粗篩層有沒有把這個技能送進候選。如果用的是向量相似度技能描述和用戶輸入語義差別太大topK可能就不包含它。這種情況可以在粗篩時把“技能名”和“技能關(guān)鍵詞”也加入索引不僅僅是描述文本。最后檢查是不是模型在精排階段被其它候選干擾了。如果兩個技能描述高度相似模型會難以抉擇。我一般把相似技能拆開要么合并要么在when_not_to_use里顯式區(qū)分。比如query_order和query_refund都涉及訂單就分別寫上“查詢退款信息時不要調(diào)用訂單查詢技能”。6.2 技能返回結(jié)果太啰嗦影響后續(xù)判斷另一個常見問題是技能返回了一個巨大的JSON模型讀取時占用大量上下文還可能導(dǎo)致后續(xù)調(diào)用參數(shù)填錯。典型場景是查數(shù)據(jù)庫技能把整表幾萬行都帶回來。解決辦法是“大結(jié)果落盤、小結(jié)果回傳”。我把查詢類技能的返回控制在一個極小的摘要里比如返回總行數(shù)、前幾條樣例、以及一個可以繼續(xù)讀取的臨時文件路徑。模型要更多數(shù)據(jù)時再調(diào)用另一個read_partial_result技能去取指定行。返回值設(shè)計原則是只返回模型“做下一步?jīng)Q策”所需的信息不要返回執(zhí)行者覺得“完整”的信息。模型不是給人看的它不需要欣賞完整數(shù)據(jù)它只需要知道“查詢成功、有12條結(jié)果、前3條是xxx”。6.3 技能穩(wěn)定性超時、并發(fā)與重試技能庫跑久了穩(wěn)定性問題會越來越多。我遇到過幾種情況技能內(nèi)部請求外部API超時Agent被卡住幾十秒。我后來給所有技能執(zhí)行都套了超時默認10秒超過就返回TIMEOUT。對重任務(wù)我會拆成“提交任務(wù)”和“查詢?nèi)蝿?wù)狀態(tài)”兩個技能避免長任務(wù)長時間占住Agent。并發(fā)調(diào)用時某些技能不是線程安全的。比如寫入同一個配置文件多個Agent同時調(diào)用就可能互相覆蓋。解決辦法是給技能加一把鎖同一時間只允許一個執(zhí)行或者把狀態(tài)類技能改成“寫臨時文件原子重命名”的方式最終一致地落盤。重試也要謹慎。如果技能不是冪等的比如發(fā)郵件、創(chuàng)建訂單重試會造成重復(fù)操作。我只對明顯冪等的技能開放自動重試其他技能一律讓用戶確認后重試。6.4 技能列表太長導(dǎo)致模型卡頓怎么辦技能庫最終會越攢越多我目前維護的庫已經(jīng)超過80個技能。如果每次調(diào)用都把80個技能的完整描述發(fā)給模型prompt直接膨脹而且模型決策質(zhì)量會下降。我采用的分層策略是第一層粗篩。先把技能描述做摘要索引只保留約50字的關(guān)鍵描述用輕量關(guān)鍵詞匹配或向量匹配篩出top10。第二層精排。把top10的完整描述和schema發(fā)給模型。第三層動態(tài)加載。真正確定調(diào)用某個技能時才把該技能的skill.py代碼加載進進程。大部分技能不需要常駐內(nèi)存。這一套下來我實測技能搜索和調(diào)用的整體延遲被壓縮到1秒以內(nèi)模型決策也更準。如果你的技能數(shù)量超過200我建議再按領(lǐng)域分桶比如support/、data/、ops/Agent默認只看到自己所在桶的技能需要跨桶再顯式檢索。7. 一些經(jīng)驗總結(jié)7.1 技能不要一開始就設(shè)計得過于抽象新手做技能庫時很容易想造一個“萬能技能”比如execute_code或run_script覺得這樣什么都能干。我一開始也這么想過結(jié)果是模型經(jīng)常把不該執(zhí)行的代碼也往這里塞既危險又不可控。后來我改成把能力拆得非常具體read_file就只讀文件write_file就只寫文件run_shell明確限制在白名單命令。雖然看起來笨但每個技能的職責(zé)清晰模型的選擇成功率一下子就上去了。技能庫的核心不是“少寫代碼”而是“讓大模型有可靠的手腳”。抽象層級太高相當于給模型發(fā)了一把萬能工具它反而不知道怎么用。7.2 技能描述要寫給人看也要寫給模型看寫描述別只站在開發(fā)者角度要站在模型的角度。我每次新增技能都會先不看代碼只把description和幾個示例扔給模型問它“如果用戶說這句話你會調(diào)用這個技能嗎”。如果模型說“不確定”說明描述還要改。另外我強烈建議在描述里放一到兩個“用戶說原話”到“參數(shù)填值”的映射示例。大模型在 few-shot 場景下填參準確率會明顯提升。比如calculate_date_diff的描述里寫示例用戶說“從今天到下周五還有幾天”參數(shù)填 {start_date: 今天, end_date: 下周五}注意示例里的參數(shù)值可以保留自然語言讓兼容層去解析模型不需要自己把“下周五”轉(zhuǎn)換成年月日。這樣能降低模型的計算負擔。7.3 保留一條手工執(zhí)行通道方便回滾最后分享一個非常重要的習(xí)慣技能庫絕對不能只有“模型自動調(diào)用”這一條路。我在實際運維中經(jīng)常遇到模型選錯了技能導(dǎo)致數(shù)據(jù)被誤改的情況。這時候如果只能跟著模型走排查會非常痛苦。我在技能庫里加了一個命令行工具可以直接手動執(zhí)行某個技能并傳參python cli.py execute read_file --param {path: /tmp/demo.txt}調(diào)試時還可以用--dry-run只打印參數(shù)和技能信息不真正執(zhí)行。有了這條手工通道定位問題就快很多先手動跑一次技能確認執(zhí)行函數(shù)沒問題再去查模型為什么沒選對。很多問題從一開始就能被隔離掉。如果你也在做Agent相關(guān)的項目我特別建議從我有一個最小技能庫開始哪怕只有兩三個技能把“描述、參數(shù)、返回、路由”這個閉環(huán)跑通再去考慮更多能力。你會發(fā)現(xiàn)大模型真正從“會聊天”變成“能干活”關(guān)鍵不在于模型本身而在于你給了它一套多可靠的“手腳”。