做AI Agent開發(fā)的朋友應(yīng)該都有這種體會(huì)剛把工具函數(shù)接入大模型時(shí)效果挺驚艷可一旦場(chǎng)景復(fù)雜起來(lái)代碼就變成一團(tuán)亂麻——幾十個(gè)函數(shù)堆在一起模型經(jīng)常選錯(cuò)目標(biāo)參數(shù)格式寫錯(cuò)一次就要返工一小時(shí)。我接觸agent-skills這個(gè)概念大概半年多前前后后在幾個(gè)不同的模擬項(xiàng)目X里試過(guò)好幾套方案今天把其中一套比較成熟的架構(gòu)思路整理出來(lái)希望能給正在做Agent落地的朋友一些參考。agent-skills說(shuō)白了就是給智能體準(zhǔn)備的一套“技能庫(kù)”。它跟單純的函數(shù)列表不太一樣重點(diǎn)是把一個(gè)能力按標(biāo)準(zhǔn)格式封裝起來(lái)包含技能的名稱、描述、輸入輸出Schema、執(zhí)行邏輯、依賴資源甚至可以包含一組完整的工具調(diào)用序列。Agent在運(yùn)行時(shí)會(huì)根據(jù)當(dāng)前任務(wù)主動(dòng)去技能庫(kù)中檢索和匹配選中最合適的技能來(lái)執(zhí)行。這樣一來(lái)Agent不再只是一個(gè)會(huì)說(shuō)話的回答機(jī)器而是變成了一個(gè)有工具箱、有操作規(guī)范、能持續(xù)沉淀能力的執(zhí)行者。這篇內(nèi)容適合誰(shuí)看正在做AI助手、自動(dòng)化助手、智能客服、工作流引擎的開發(fā)者都能用得上。哪怕你的Agent還沒上生產(chǎn)只是在學(xué)校內(nèi)部項(xiàng)目或企業(yè)內(nèi)部驗(yàn)證階段這套思路也能幫你把系統(tǒng)搭得更穩(wěn)。我會(huì)盡量把設(shè)計(jì)思路、踩坑過(guò)程和完整代碼骨架都寫出來(lái)希望能真正幫到你。1. 為什么Agent需要技能庫(kù)而不是純靠Prompt1.1 從“會(huì)調(diào)用工具”到“具備技能”的轉(zhuǎn)變很多人最開始做Agent的時(shí)候習(xí)慣把所有能力都塞進(jìn)System Prompt里比如“你可以使用以下工具get_weather、book_hotel……”然后讓模型自己去拼。這種做法在小規(guī)模、工具數(shù)量少于五個(gè)的時(shí)候是可以接受的我也這么做過(guò)圖省事。但一旦超過(guò)十個(gè)工具問(wèn)題就開始暴露Prompt太長(zhǎng)導(dǎo)致模型注意力分散描述寫得不仔細(xì)就會(huì)選錯(cuò)增加新工具還得頻繁改提示詞而且不同工具的輸入輸出風(fēng)格五花八門Agent內(nèi)部要針對(duì)每個(gè)工具寫適配代碼。這就是單純“工具接入”階段最大的痛點(diǎn)。技能庫(kù)的思路是把“工具”再往上升一層。工具是最小執(zhí)行單元比如一個(gè)查詢接口、一個(gè)計(jì)算函數(shù)技能則是一個(gè)“完整動(dòng)作”它可能只依賴一個(gè)工具也可能串聯(lián)好幾個(gè)工具并且自帶規(guī)則和邊界條件。比如“查詢天氣并給出穿衣建議”單看工具層需要至少兩個(gè)能力天氣查詢和知識(shí)推理。但作為技能它應(yīng)該是一個(gè)整體先查天氣再根據(jù)溫度范圍、降水概率組織建議文案。模型只需要做一次選擇執(zhí)行細(xì)節(jié)全部封裝在技能內(nèi)部。這個(gè)抽象層面的提升非常關(guān)鍵。它讓Agent的決策面變小了——不是讓模型去編排每一步工具調(diào)用而是讓模型在有限的技能菜單里做選擇。菜單里的每項(xiàng)技能都經(jīng)過(guò)測(cè)試和驗(yàn)證執(zhí)行結(jié)果可控。我在實(shí)際項(xiàng)目中體會(huì)最深的一點(diǎn)是Agent系統(tǒng)的可靠性往往不是靠模型聰明而是靠決策范圍收窄。模型需要做的判斷越少出錯(cuò)率就越低。1.2 技能庫(kù)到底解決了什么核心問(wèn)題技能庫(kù)不是花架子它解決的是三個(gè)核心問(wèn)題。第一是復(fù)用。同樣一個(gè)“內(nèi)容安全審核”技能可以在內(nèi)容生成Agent里面用也可以在用戶反饋處理Agent里面用只要接口定義一致?lián)Q一個(gè)Agent實(shí)例就能直接掛載。做過(guò)多個(gè)Agent的人應(yīng)該都有經(jīng)驗(yàn)如果沒有統(tǒng)一的技能層同一套邏輯就得在每個(gè)Agent里重新實(shí)現(xiàn)一遍維護(hù)成本直接翻倍。這里說(shuō)的復(fù)用還不只是代碼復(fù)用更重要的是能力沉淀。一個(gè)技能被驗(yàn)證有效它就能成為團(tuán)隊(duì)的基礎(chǔ)資產(chǎn)后面開發(fā)新Agent時(shí)可以直接調(diào)用不用每次從頭設(shè)計(jì)。第二是管理。技能庫(kù)把每個(gè)能力的版本、依賴、測(cè)試用例都固化下來(lái)能單獨(dú)升級(jí)、單獨(dú)回滾。我在某跨平臺(tái)系統(tǒng)里遇到過(guò)一種情況某個(gè)匯報(bào)生成技能改了一版Prompt之后其他Agent的對(duì)話質(zhì)量集體下降排查了半天才發(fā)現(xiàn)是因?yàn)榧寄軒?kù)是共享的有人直接改了原文件。后來(lái)改成版本隔離每個(gè)Agent鎖定技能的某個(gè)版本問(wèn)題才徹底解決。這個(gè)坑讓我意識(shí)到技能庫(kù)必須做版本管理不能只有一坨最新文件否則牽一發(fā)而動(dòng)全身。第三是可驗(yàn)證。技能庫(kù)里的技能是可以單獨(dú)測(cè)試的不需要跑到完整Agent鏈路里才能驗(yàn)證。這一點(diǎn)在工程實(shí)踐里非常有價(jià)值。我經(jīng)常用一套固定的測(cè)試用例去回歸技能庫(kù)改一行代碼就能知道會(huì)不會(huì)影響到其他調(diào)用方。這種確定性讓人很安心也是技能庫(kù)跟散亂工具函數(shù)最本質(zhì)的區(qū)別之一。1.3 技能、工具、插件、工作流的邊界很多人對(duì)這幾個(gè)概念是混著用的我在團(tuán)隊(duì)評(píng)審時(shí)也經(jīng)常被問(wèn)“這跟插件有什么區(qū)別”。我的理解是工具是最底層它不關(guān)心業(yè)務(wù)就是一個(gè)能完成某個(gè)原子操作的函數(shù)或接口比如“發(fā)送郵件”“解析PDF”。技能是工具的封裝它有明確的業(yè)務(wù)目標(biāo)和輸入輸出契約比如“生成會(huì)議紀(jì)要并發(fā)送給指定參會(huì)人”內(nèi)部可能用到了語(yǔ)音轉(zhuǎn)文字、摘要、格式化、發(fā)送郵件四個(gè)工具。插件是技能的集合和分發(fā)單元通常包含一組相關(guān)技能再加上自己的界面或配置入口可以整體安裝卸載有點(diǎn)像一個(gè)技能包。工作流則是技能之上的編排層它表達(dá)的是“先做A再做B如果條件C成立就做D”的流程邏輯偏業(yè)務(wù)層面。把這一層理清楚之后你會(huì)發(fā)現(xiàn)設(shè)計(jì)技能庫(kù)時(shí)不會(huì)糾結(jié)“這個(gè)能力該放在哪兒”。比如一個(gè)純粹的PDF解析功能它應(yīng)該是一個(gè)工具不占技能庫(kù)名額而“從PDF中提取表格并整理成結(jié)構(gòu)化數(shù)據(jù)”就是一個(gè)技能因?yàn)樗忻鞔_的目標(biāo)描述和輸出規(guī)范甚至可以內(nèi)部選擇用哪個(gè)解析工具。這種邊界感讓我在設(shè)計(jì)新Agent時(shí)省了很多不必要的爭(zhēng)論。2. 技能庫(kù)設(shè)計(jì)的三個(gè)核心原則2.1 原則一統(tǒng)一接口讓輸入輸出都有Schema約束技能庫(kù)如果想讓不同Agent都能調(diào)用第一件要做的事就是統(tǒng)一接口格式。最通用的做法是給每個(gè)技能定義輸入?yún)?shù)和輸出結(jié)果的JSON Schema用類型、必填、描述、默認(rèn)值來(lái)約束輸入用固定結(jié)構(gòu)描述輸出。這里有一個(gè)容易被忽視的點(diǎn)不僅輸入要校驗(yàn)輸出也要有結(jié)構(gòu)化的Schema。如果技能返回的是自由文本模型的后續(xù)決策就缺少確定性的抓手很難穩(wěn)定地做下一步操作。舉個(gè)例子一個(gè)“分析用戶評(píng)論情感”的技能輸出如果只是一個(gè)字符串“比較滿意”下游技能根本沒法做數(shù)值判斷。更好的輸出是{sentiment: positive, confidence: 0.93, summary: 用戶對(duì)物流速度滿意}這樣即使不依賴大模型普通代碼也能處理還能把置信度數(shù)值直接用在下游統(tǒng)計(jì)里。我覺得這一步是整個(gè)技能庫(kù)的地基。Schema定義得越清晰后面做參數(shù)校驗(yàn)、自動(dòng)補(bǔ)全、接口測(cè)試都會(huì)越順。我見過(guò)不少團(tuán)隊(duì)先寫執(zhí)行邏輯回頭補(bǔ)Schema結(jié)果發(fā)現(xiàn)邏輯里的輸入輸出跟契約對(duì)不上返工量大得嚇人。所以我的建議是任何技能的Schema設(shè)計(jì)都要跟執(zhí)行邏輯開發(fā)同步推進(jìn)哪怕先草草寫一版也要讓契約先立起來(lái)再圍繞它實(shí)現(xiàn)。2.2 原則二描述語(yǔ)料要寫給模型看不只給人看技能的描述字段往往決定了模型能不能在正確的時(shí)候選中這個(gè)技能。這里說(shuō)的描述不是功能文檔而是給大模型看的“使用說(shuō)明書”。它需要包含幾個(gè)關(guān)鍵信息這個(gè)技能是干什么的、適合在什么場(chǎng)景下用、什么情況下不要用、輸入輸出分別是什么。描述寫得太簡(jiǎn)單比如只寫“獲取天氣”模型很容易在需要穿衣建議的時(shí)候去調(diào)用天氣技能而不是去調(diào)用更高層的穿衣建議技能描述寫得太啰嗦又會(huì)稀釋模型注意力導(dǎo)致技能檢索效率下降。我常用的寫法是幾個(gè)固定的段落一句話總結(jié)然后寫適用場(chǎng)景再寫不適用場(chǎng)景最后給一個(gè)典型調(diào)用例子。句子盡量短動(dòng)詞明確避免模糊詞匯。比如一個(gè)“訂單取消”技能描述可以是“當(dāng)用戶要求取消尚未發(fā)貨的訂單時(shí)使用。不適用于已發(fā)貨訂單已發(fā)貨訂單請(qǐng)使用‘售后申請(qǐng)’技能。典型輸入訂單ID、取消原因?！睂?shí)測(cè)下來(lái)這種結(jié)構(gòu)化描述能讓技能選錯(cuò)率明顯下降。我還在元數(shù)據(jù)文件里加了一個(gè)examples字段里面放兩三條真實(shí)的輸入輸出對(duì)效果比單純寫描述更穩(wěn)定。之前看過(guò)一份評(píng)測(cè)報(bào)告說(shuō)模型對(duì)示例的敏感度其實(shí)高于對(duì)描述文字的敏感度這點(diǎn)我在實(shí)際項(xiàng)目中也深有體會(huì)。與其花大量時(shí)間打磨描述措辭不如先把高質(zhì)量示例補(bǔ)上。2.3 原則三技能粒度要收放有度技能粒度這個(gè)東西我一開始也控制不好走了不少?gòu)澛贰Ａ６忍?xì)比如寫了一個(gè)“發(fā)送HTTP請(qǐng)求”技能結(jié)果Agent每個(gè)動(dòng)作都要繞一圈又慢又瑣碎等于是把工具列表?yè)Q了個(gè)名字并沒有解決決策負(fù)擔(dān)的問(wèn)題。粒度太粗比如寫了一個(gè)“完成整個(gè)營(yíng)銷方案”技能模型幾乎沒法復(fù)用稍微換一個(gè)需求場(chǎng)景就失效了等于寫死了一個(gè)一次性業(yè)務(wù)腳本。我的經(jīng)驗(yàn)是利用“可復(fù)用邊界”來(lái)判斷如果一個(gè)技能能被兩個(gè)以上不同的任務(wù)用到粒度就是合適的如果只能被一個(gè)特定任務(wù)用到要么繼續(xù)拆分出通用子技能要么接受它就是一個(gè)獨(dú)立業(yè)務(wù)腳本不進(jìn)技能庫(kù)。寫技能的時(shí)候多問(wèn)自己一句除了當(dāng)前需求還有誰(shuí)會(huì)用到這個(gè)技能如果答案是沒人那就把它設(shè)計(jì)成通用技能的組合調(diào)用而不是單獨(dú)建一個(gè)獨(dú)占技能。還有一個(gè)實(shí)操技巧同一業(yè)務(wù)域里盡量保證技能水平一致。如果“生成文案”和“生成文案并配圖并定時(shí)發(fā)布”同時(shí)存在模型很容易混淆不知道該選哪個(gè)。我的建議是只保留粗粒度技能把細(xì)粒度能力作為內(nèi)部工具隱藏起來(lái)讓技能庫(kù)的條目總數(shù)保持在幾十個(gè)以內(nèi)。這樣模型選擇壓力小維護(hù)成本也低很多。3. 從零搭建一個(gè)最小可用的技能庫(kù)3.1 目錄結(jié)構(gòu)與技能元數(shù)據(jù)設(shè)計(jì)先看目錄結(jié)構(gòu)。我比較喜歡用扁平化加標(biāo)簽的方式而不是深層嵌套。每個(gè)技能占一個(gè)目錄目錄名就是技能ID里面至少包含元數(shù)據(jù)文件skill.yaml、執(zhí)行腳本exec.py和可選的依賴聲明文件。目錄結(jié)構(gòu)如下skills/ email_reply/ skill.yaml exec.py tests/ cases.json meeting_summary/ skill.yaml exec.py requirements.txt review_sentiment/ skill.yaml exec.py目錄名用snake_case或kebab-case都可以但全庫(kù)必須統(tǒng)一。我建議用snake_case方便Python類庫(kù)直接映射。這里順便說(shuō)一下技能ID一定不要隨便改因?yàn)镮D會(huì)被寫進(jìn)各種編排配置和接口日志里改名會(huì)導(dǎo)致歷史數(shù)據(jù)對(duì)不上。skill.yaml的核心字段可以這樣設(shè)計(jì)id: meeting_summary name: 會(huì)議紀(jì)要生成與要點(diǎn)整理 version: 1.2.0 description: | 當(dāng)用戶提供會(huì)議錄音或文字稿時(shí)使用能夠生成結(jié)構(gòu)化會(huì)議紀(jì)要包含議題、結(jié)論、待辦事項(xiàng)。 不適用于純閑聊或需要翻譯的內(nèi)容。 典型輸入會(huì)議文字稿或錄音文件路徑。 examples: - input: 會(huì)議記錄關(guān)于Q3目標(biāo)、預(yù)算…… output: 議題Q3目標(biāo)確認(rèn)結(jié)論預(yù)算需壓縮10% input_schema: type: object required: - transcript properties: transcript: type: string description: 會(huì)議文字稿內(nèi)容長(zhǎng)度不超過(guò)20000字 include_action_items: type: boolean description: 是否輸出待辦事項(xiàng)清單默認(rèn)為true output_schema: type: object required: - summary - action_items properties: summary: type: string action_items: type: array items: type: string dependencies: - llm_sdk - pydantic注意一點(diǎn)不要在skill.yaml里寫具體的執(zhí)行邏輯細(xì)節(jié)也不要放過(guò)于冗長(zhǎng)的Prompt模板那些東西歸類到exec.py或獨(dú)立的prompt文件里。元數(shù)據(jù)本身要保持輕量這樣模型和代碼讀取時(shí)才會(huì)快維護(hù)的人一眼也能看明白這個(gè)技能到底是干什么的。3.2 技能注冊(cè)與動(dòng)態(tài)加載技能庫(kù)在代碼層面要做的一個(gè)重要事情是動(dòng)態(tài)注冊(cè)。你不能在系統(tǒng)里寫死一個(gè)技能字典否則每次新增技能都要改主程序。更合理的做法是在進(jìn)程啟動(dòng)時(shí)掃描技能目錄讀取每個(gè)目錄的skill.yaml構(gòu)建索引然后按需加載執(zhí)行模塊。下面是一個(gè)用Python實(shí)現(xiàn)的簡(jiǎn)化加載器import yaml from pathlib import Path from importlib import import_util class SkillRegistry: def __init__(self, base_dir: str skills): self.base_dir Path(base_dir) self.skills {} self.modules {} def scan(self): for skill_dir in self.base_dir.iterdir(): meta_path skill_dir / skill.yaml if not meta_path.is_file(): continue with open(meta_path, r, encodingutf-8) as f: meta yaml.safe_load(f) skill_id meta.get(id, skill_dir.name) self.skills[skill_id] { meta: meta, dir: str(skill_dir), } def load(self, skill_id: str): if skill_id in self.modules: return self.modules[skill_id] spec import_util.spec_from_file_location( fskill_{skill_id}, Path(self.skills[skill_id][dir]) / exec.py, ) module import_util.module_from_spec(spec) spec.loader.exec_module(module) self.modules[skill_id] module return module def execute(self, skill_id: str, **kwargs): module self.load(skill_id) validate_input(self.skills[skill_id][meta], kwargs) result module.run(**kwargs) validate_output(self.skills[skill_id][meta], result) return result def list_skills(self): return [ {id: sid, name: meta[meta][name], description: meta[meta][description]} for sid, meta in self.skills.items() ]這個(gè)設(shè)計(jì)的關(guān)鍵點(diǎn)是元數(shù)據(jù)在啟動(dòng)時(shí)就全部加載執(zhí)行模塊在真正被選中后才動(dòng)態(tài)加載。這樣啟動(dòng)速度快內(nèi)存占用也低。另外validate_input和validate_output兩個(gè)函數(shù)一定不要跳過(guò)它們實(shí)際上是在執(zhí)行邊界上做契約校驗(yàn)?zāi)軘r截大量臟數(shù)據(jù)。我在一個(gè)項(xiàng)目里就靠這兩行校驗(yàn)函數(shù)擋住了模型傳錯(cuò)字段的情況不然錯(cuò)誤會(huì)一路傳導(dǎo)到下游排查起來(lái)痛苦得多。3.3 一個(gè)完整技能的編寫示例我們來(lái)實(shí)現(xiàn)一個(gè)比較有代表性的技能把一段產(chǎn)品反饋整理成結(jié)構(gòu)化問(wèn)題清單。這個(gè)技能在很多Agent場(chǎng)景里都通用比如客服系統(tǒng)、需求收集助手。先看技能元數(shù)據(jù)的輸入輸出契約再看exec.py的實(shí)現(xiàn)骨架。import re from typing import List, Optional from pydantic import BaseModel class FeedbackItem(BaseModel): category: str content: str priority: str medium class RunResult(BaseModel): items: List[FeedbackItem] raw_count: int def run(feedback_text: str, categories: Optional[List[str]] None) - dict: segments split_feedback(feedback_text) items [] for seg in segments: if len(seg.strip()) 5: continue category classify(seg, categories) priority estimate_priority(seg) items.append( FeedbackItem( categorycategory, contentseg.strip(), prioritypriority, ) ) return RunResult(itemsitems, raw_countlen(segments)).model_dump() def split_feedback(text: str) - List[str]: parts re.split(r[。!?.\n], text) return [p for p in parts if p.strip()] def classify(seg: str, categories: Optional[List[str]]) - str: if categories: for cat in categories: if cat in seg: return cat return 其他 def estimate_priority(seg: str) - str: if re.search(r崩潰|閃退|無(wú)法|嚴(yán)重|緊急|賠償, seg): return high if re.search(r建議|希望|可以優(yōu)化, seg): return low return medium這個(gè)技能實(shí)際運(yùn)行時(shí)Agent只需要傳feedback_text剩下的拆分、分類、優(yōu)先級(jí)估計(jì)全部在內(nèi)部完成輸出結(jié)果是結(jié)構(gòu)化JSON。這就是技能封裝的意義對(duì)外暴露的是簡(jiǎn)單契約對(duì)內(nèi)可以自由混合規(guī)則和模型調(diào)用。上面示例用的是純規(guī)則實(shí)現(xiàn)實(shí)際項(xiàng)目中如果分類準(zhǔn)確率不夠可以在classify函數(shù)里換成調(diào)用大模型接口但要注意把超時(shí)、重試、模型名等配置放在技能目錄下的config.json里由加載器統(tǒng)一注入不要散落在代碼里。3.4 執(zhí)行包裝與統(tǒng)一異常處理技能執(zhí)行時(shí)會(huì)遇到各種問(wèn)題網(wǎng)絡(luò)超時(shí)、模型接口報(bào)錯(cuò)、輸入字段缺失、輸出格式非法。如果不做統(tǒng)一包裝Agent主循環(huán)的異常處理會(huì)被各種技能錯(cuò)誤淹沒。我建議每個(gè)技能模塊統(tǒng)一暴露run作為入口而注冊(cè)中心在執(zhí)行時(shí)包一層異常處理和重試策略。重試策略要區(qū)分錯(cuò)誤類型網(wǎng)絡(luò)類錯(cuò)誤可以重試兩到三次業(yè)務(wù)校驗(yàn)類錯(cuò)誤不要重試直接返回參數(shù)錯(cuò)誤原因。可以在注冊(cè)中心里加一個(gè)簡(jiǎn)單的重試邏輯import time def execute_with_retry(self, skill_id: str, max_retries: int 2, **kwargs): last_error None for attempt in range(max_retries 1): try: return self.execute(skill_id, **kwargs) except NetworkError as exc: last_error exc time.sleep(1.5 * (attempt 1)) except (SchemaError, ValueError) as exc: raise RuntimeError(f技能參數(shù)錯(cuò)誤: {exc}) from exc raise RuntimeError(f技能執(zhí)行多次重試仍失敗: {last_error})這個(gè)方法看起來(lái)簡(jiǎn)單但在實(shí)際項(xiàng)目里非常管用。我在某實(shí)時(shí)數(shù)據(jù)處理Agent里用上這套后因?yàn)榈谌浇涌诓环€(wěn)定導(dǎo)致的會(huì)話中斷少了大概一半。記住一個(gè)原則技能內(nèi)部不要自己加無(wú)限重試重試邏輯放在統(tǒng)一層避免一個(gè)卡住的技能占住線程資源不放。另外錯(cuò)誤信息一定要寫得足夠詳細(xì)尤其是參數(shù)校驗(yàn)失敗時(shí)最好把期望格式和實(shí)際收到的值都列出來(lái)這樣模型自己才有可能在下一次調(diào)用前修正。4. 技能編排讓多個(gè)技能協(xié)作干活4.1 順序流水線怎么設(shè)計(jì)單個(gè)技能解決的是單點(diǎn)問(wèn)題但真實(shí)業(yè)務(wù)里往往需要把多個(gè)技能串起來(lái)。最基礎(chǔ)的是順序流水線。比如一個(gè)“輿情分析日?qǐng)?bào)”場(chǎng)景需要依次做數(shù)據(jù)抓取、文本清洗、情感分析、聚合統(tǒng)計(jì)、生成報(bào)告。如果拆成五個(gè)技能來(lái)做每次Agent都在大模型側(cè)決策下一步效率低且不穩(wěn)定。更好的做法是把這些技能放到一條編排配置里由編排層按固定順序執(zhí)行模型只需要在入口觸發(fā)一個(gè)“生成輿情日?qǐng)?bào)”的總控技能。編排配置可以是一份JSON{ id: report_workflow, trigger_skill: parse_user_request, steps: [ { skill: fetch_data, inputs: {source: {{request.source}}} }, { skill: text_clean, inputs: {documents: {{steps.fetch_data.output}}} }, { skill: sentiment_analysis, inputs: {texts: {{steps.text_clean.output}}} }, { skill: aggregate_stats, inputs: {items: {{steps.sentiment_analysis.output}}} }, { skill: generate_report, inputs: {stats: {{steps.aggregate_stats.output}}} } ] }這里的變量引用語(yǔ)法是{{steps.xxx.output}}本質(zhì)上就是讓編排引擎把上一步的輸出結(jié)構(gòu)體傳給下一步。實(shí)現(xiàn)這個(gè)機(jī)制并不復(fù)雜關(guān)鍵是要在每一步執(zhí)行后緩存output對(duì)象并提供一套模板替換能力。我自己用Python實(shí)現(xiàn)時(shí)只寫了一個(gè)簡(jiǎn)單的遞歸替換函數(shù)大概一百多行完全夠用。順序流水線的價(jià)值在于穩(wěn)定性固定流程不會(huì)受到模型發(fā)揮波動(dòng)的影響該先做的不會(huì)跳過(guò)去。它適合那些步驟明確、順序強(qiáng)依賴的業(yè)務(wù)比如數(shù)據(jù)處理類任務(wù)。4.2 條件路由與技能回退很多場(chǎng)景不是簡(jiǎn)單的順序線而是有分支的。比如“根據(jù)訂單狀態(tài)決定后續(xù)動(dòng)作”已發(fā)貨走物流查詢未發(fā)貨走改地址退款中走售后催辦。這套邏輯如果全部靠Agent自由發(fā)揮狀態(tài)判斷容易出錯(cuò)。我一般推薦把條件路由寫在編排層用顯式的if條件控制分支。條件路由的一個(gè)常見誤區(qū)是把JSON條件表達(dá)式寫得過(guò)于復(fù)雜實(shí)際上你只需要支持等于、不等于、包含、正則匹配這幾種基礎(chǔ)算子就夠用了。我統(tǒng)計(jì)過(guò)自己搭建的十幾個(gè)編排流程百分之九十的分支邏輯都能用這些基礎(chǔ)算子覆蓋。把條件寫清楚以后代碼調(diào)試起來(lái)非常直觀任何一個(gè)分支的走向都能提前預(yù)判到。另外技能回退也很重要。比如查詢訂單狀態(tài)失敗了是直接告訴用戶失敗還是嘗試調(diào)用備用接口如果在編排層給技能配置了fallback字段主技能拋異常時(shí)自動(dòng)切換到備選技能用戶側(cè)基本無(wú)感知。我在線上環(huán)境里遇到過(guò)主鏈路接口連續(xù)抖動(dòng)的情況如果沒有回退機(jī)制那段時(shí)間所有相關(guān)Agent都會(huì)跟著一起不可用加上回退之后影響范圍縮小了不少。4.3 技能間的數(shù)據(jù)契約與上下文傳遞多技能協(xié)作最大的坑就是數(shù)據(jù)格式不對(duì)齊。技能A輸出customer_id技能B期望的是user_id如果沒有統(tǒng)一的數(shù)據(jù)契約只能靠寫膠水代碼編排一復(fù)雜就維護(hù)不下去。我的做法是引入一個(gè)“技能上下文對(duì)象”在每個(gè)技能執(zhí)行前根據(jù)其input_schema自動(dòng)截取上下文里需要的字段。如果技能輸出字段名跟下一個(gè)技能不一致就在編排層配置一個(gè)顯式的字段映射{ skill: get_user_profile, inputs: {user_id: {{steps.query_order.output.customer_id}}} }把這種映射放到配置里而不是寫在代碼里好處是業(yè)務(wù)調(diào)整時(shí)不用改主程序。這個(gè)模式我用了一段時(shí)間后發(fā)現(xiàn)很多成熟的開源編排工具也是同樣的思路算是行業(yè)里的通用實(shí)踐。再提醒一點(diǎn)上下文傳遞時(shí)盡量傳遞值對(duì)象或ID而不是傳遞龐大的中間文本。我之前踩過(guò)幾次坑一個(gè)文本清洗技能把整篇大文檔往下傳結(jié)果后續(xù)技能越跑越慢一度以為是模型速度問(wèn)題最后發(fā)現(xiàn)是上下文里積累了太多冗余文本。后來(lái)我讓每個(gè)技能在輸出時(shí)主動(dòng)做一次字段精簡(jiǎn)只保留下游真正需要的數(shù)據(jù)整體token消耗和延遲都降下來(lái)了。5. 常見問(wèn)題與排查技巧實(shí)錄5.1 模型總選錯(cuò)技能怎么辦這是使用技能庫(kù)后最常遇到的問(wèn)題表現(xiàn)為該調(diào)用A技能的時(shí)候模型調(diào)用了B技能或者干脆回答“我沒有這個(gè)能力”。我排查時(shí)一般按三條線走。第一條看技能描述是否包含明確的“適用/不適用”邊界。如果只寫了一句話功能描述優(yōu)先補(bǔ)場(chǎng)景邊界和典型示例。第二條看技能ID和名稱是否太長(zhǎng)或者太抽象。比如某個(gè)技能叫“handle_order_exception”另一個(gè)叫“process_refund_request”模型很難區(qū)分改成“處理退款申請(qǐng)”“處理訂單異常”這種業(yè)務(wù)化名稱會(huì)更穩(wěn)妥。第三條檢查技能庫(kù)里是否存在語(yǔ)義高度重疊的條目比如同時(shí)有“生成摘要”和“總結(jié)要點(diǎn)”模型不知道選哪個(gè)那就合并或者刪掉一個(gè)。如果以上都做完了還是選錯(cuò)可以考慮在模型側(cè)的System Prompt里加一個(gè)簡(jiǎn)短的技能索引列出技能ID和一句話說(shuō)明讓模型在決策前先掃一眼菜單。我也見過(guò)一些項(xiàng)目用向量檢索先召回候選技能再把候選列表塞給模型做選擇效果不錯(cuò)但整體復(fù)雜度明顯更高適合技能條目超過(guò)五十個(gè)的情況。如果你的技能庫(kù)還比較小先把描述和示例質(zhì)量搞上去收益最大。5.2 技能Schema校驗(yàn)不過(guò)多半是類型和必填沒對(duì)齊跟大模型打交道輸入字段的格式問(wèn)題幾乎不可避免。模型自己生成的參數(shù)有時(shí)候會(huì)是字符串而不是數(shù)組有時(shí)候缺了必填字段。我的經(jīng)驗(yàn)是Schema校驗(yàn)失敗時(shí)一定要把原始錯(cuò)誤信息原樣返回給Agent讓它自己修正參數(shù)后重新調(diào)用。這里有個(gè)細(xì)節(jié)錯(cuò)誤信息里不要只寫“參數(shù)錯(cuò)誤”要寫明“缺少字段user_id字段tags期望類型是數(shù)組實(shí)際收到字符串”。大模型對(duì)清晰錯(cuò)誤信息的修正能力很強(qiáng)很多情況下一個(gè)來(lái)回就能自動(dòng)解決。如果反復(fù)修正還是不行多半是技能的描述里沒有寫清楚參數(shù)格式。此時(shí)要在description里加一句更具體的說(shuō)明比如“tags是一個(gè)字符串?dāng)?shù)組每一項(xiàng)是用戶的標(biāo)簽內(nèi)容”。這種提示比單純的Schema定義對(duì)模型更友好。我甚至?xí)ㄗh在元數(shù)據(jù)里放一個(gè)parameter_examples字段把每個(gè)參數(shù)的合法示例都寫出來(lái)這樣能在根本上降低模型生成錯(cuò)誤參數(shù)的概率。5.3 技能加載慢、內(nèi)存占用高技能庫(kù)條目多了以后進(jìn)程啟動(dòng)時(shí)掃描全部元數(shù)據(jù)一般也就幾十毫秒不至于有瓶頸。真正容易出問(wèn)題的是有些人在注冊(cè)中心里把每個(gè)技能的執(zhí)行模塊都在啟動(dòng)時(shí)就import這會(huì)拖慢啟動(dòng)速度還會(huì)占內(nèi)存。我的建議是采用懶加載也就是真正執(zhí)行一個(gè)技能時(shí)才import它。另外有些技能內(nèi)部依賴一些體積較大的庫(kù)比如PDF解析、圖像識(shí)別如果十個(gè)技能都依賴同一個(gè)庫(kù)加載器可以做一個(gè)模塊復(fù)用的緩存池不要讓每個(gè)技能重復(fù)掛一份同樣的依賴對(duì)象。還有一個(gè)隱藏問(wèn)題技能模塊里的全局狀態(tài)。如果某個(gè)技能在模塊內(nèi)定義了一個(gè)全局緩存字典多次執(zhí)行之后內(nèi)存會(huì)一直漲。排查時(shí)可以定期打印技能模塊對(duì)象的數(shù)量如果發(fā)現(xiàn)同一個(gè)技能被加載了兩份要檢查import路徑是否不一致。我之前就遇到過(guò)因?yàn)槟夸洿笮懖灰恢聦?dǎo)致模塊被重復(fù)加載的情況看起來(lái)是小問(wèn)題實(shí)際會(huì)讓內(nèi)存占用翻倍。5.4 技能更新后老Agent卻報(bào)錯(cuò)這個(gè)跟版本管理有關(guān)。技能庫(kù)是共享的你更新了技能文件所有引用它的Agent都會(huì)受影響。有些Agent依賴舊版本的輸出格式更新后自然就出問(wèn)題。我目前的做法是每個(gè)Agent實(shí)例在初始化時(shí)記錄自己依賴的技能版本集合注冊(cè)中心提供一個(gè)按版本隔離的獲取接口。元數(shù)據(jù)文件里加version字段同一份技能可以有多個(gè)版本目錄共存比如meeting_summary_v1、meeting_summary_v2。發(fā)布新版本時(shí)不要?jiǎng)h舊版本等所有Agent都遷移完成后再清理。這個(gè)流程看起來(lái)繁瑣但能避免不少線上事故。另外技能測(cè)試文件應(yīng)該跟技能同目錄存放每次改動(dòng)后跑一遍tests/cases.json里的用例確認(rèn)輸出Schema和示例數(shù)據(jù)都一致再考慮發(fā)布。我自己就因?yàn)橥祽刑^(guò)測(cè)試吃過(guò)虧那之后所有技能都強(qiáng)制要求附帶至少三個(gè)輸入輸出用例。特別是涉及大模型輸出的技能很容易出現(xiàn)結(jié)構(gòu)不穩(wěn)定只有靠固定用例回歸才能保證升級(jí)安全。5.5 調(diào)試技能庫(kù)的實(shí)用小工具最后分享一個(gè)調(diào)試技巧。我給技能庫(kù)加了一個(gè)“單技能命令行執(zhí)行器”可以直接在終端跑一個(gè)技能傳參并查看輸出不需要把整個(gè)Agent跑起來(lái)。python -m skill_runner run meeting_summary --transcript 會(huì)議內(nèi)容...這個(gè)工具本質(zhì)上就是注冊(cè)中心的一個(gè)薄封裝執(zhí)行時(shí)傳入技能ID和JSON參數(shù)最后格式化打印輸出。這樣調(diào)試效率會(huì)高很多尤其在排查某個(gè)技能單獨(dú)報(bào)錯(cuò)的時(shí)候不用再動(dòng)其他部分。我一度調(diào)試Agent鏈路要反復(fù)改Prompt和參數(shù)加上這個(gè)小工具后至少省了三分之一的時(shí)間。我建議每個(gè)團(tuán)隊(duì)做技能庫(kù)的時(shí)候都順手把這個(gè)工具加上成本很低日常收益卻很大。做技術(shù)選型的時(shí)候我一直喜歡那些能在真實(shí)場(chǎng)景里扛住壓力的方案而不是演示時(shí)看著炫酷的玩法。技能庫(kù)這套架構(gòu)在好幾個(gè)生產(chǎn)級(jí)Agent里幫我扛過(guò)了流量壓力也給后續(xù)擴(kuò)展留了空間。如果你剛開始接觸agent-skills不用急著把所有能力都封裝成技能先從兩三個(gè)高頻業(yè)務(wù)動(dòng)作入手把接口、描述、測(cè)試這三件事做扎實(shí)跑通之后再逐步擴(kuò)充會(huì)比一開始就鋪一個(gè)大而全的庫(kù)穩(wěn)妥得多。等你的技能庫(kù)真正被多個(gè)Agent復(fù)用時(shí)你會(huì)發(fā)現(xiàn)之前在設(shè)計(jì)和規(guī)范上花的時(shí)間都是值得的。