前幾天和一個(gè)做AI應(yīng)用的朋友聊天他吐槽說(shuō)現(xiàn)在接大模型接口寫(xiě)Agent最頭疼的不是模型能力不夠而是把“讓模型干活”這件事做得可靠。他團(tuán)隊(duì)里十幾個(gè)Agent每個(gè)都掛了一堆函數(shù)有的叫g(shù)et_weather有的叫fetch_user_info但換個(gè)場(chǎng)景、換個(gè)模型這些“技能”就很難復(fù)用。我聽(tīng)完第一反應(yīng)是這哥們兒缺的其實(shí)不是更多提示詞而是一套正經(jīng)的agent-skills工程化思路?！癮gent-skills”這個(gè)詞這兩年從Anthropic提出Agent Skills概念之后基本成了Agent工程化繞不開(kāi)的關(guān)鍵詞。說(shuō)白了它不是讓你去調(diào)某個(gè)現(xiàn)成的API而是指給Agent設(shè)計(jì)、封裝、管理一套“可復(fù)用能力單元”的方法論。你可以把它理解成給AI助手裝上一個(gè)個(gè)插件式的“專(zhuān)業(yè)技能包”讓它能根據(jù)具體任務(wù)自動(dòng)調(diào)用對(duì)應(yīng)的能力而不是每次都在系統(tǒng)提示詞里塞一大坨互相糾纏的指令。這篇文章我就把這些年在Agent技能系統(tǒng)上踩過(guò)的坑、沉淀下來(lái)的設(shè)計(jì)思路連同可以直接抄作業(yè)的框架代碼一次講清楚。不管你是剛接觸Agent開(kāi)發(fā)還是已經(jīng)在生產(chǎn)環(huán)境里磨了好幾個(gè)版本這篇文章應(yīng)該都能給你一些有用的東西。1. 為什么Agent需要一套“技能系統(tǒng)”而不是一堆工具函數(shù)先聊一個(gè)很本質(zhì)的問(wèn)題既然模型本身就支持function calling我們直接把函數(shù)注冊(cè)給模型不就行了嗎為什么還要搞一套“技能系統(tǒng)”實(shí)際做過(guò)的朋友應(yīng)該都知道函數(shù)調(diào)用和技能系統(tǒng)之間隔著一層“工程化”的距離。1.1 從“能用”到“好用”缺的是技能抽象層單純的函數(shù)調(diào)用解決的是“模型知道有哪些函數(shù)、參數(shù)怎么填”的問(wèn)題。但落到真實(shí)業(yè)務(wù)里你很快就會(huì)遇到幾個(gè)尷尬場(chǎng)面一個(gè)技能往往不是一個(gè)函數(shù)能搞定的需要多個(gè)函數(shù)按順序配合。比如“幫用戶(hù)分析一份PDF財(cái)報(bào)”至少涉及文件解析、數(shù)據(jù)抽取、指標(biāo)計(jì)算、報(bào)告生成四步。如果全拆成函數(shù)丟給模型它自己編排出來(lái)的流程大概率不穩(wěn)定。技能應(yīng)該有“記憶”和“配置”。同一個(gè)報(bào)表生成技能給財(cái)務(wù)部門(mén)和給運(yùn)營(yíng)部門(mén)用指標(biāo)口徑、輸出格式完全不一樣。函數(shù)做不到這種上下文感知。技能需要被復(fù)用、被分享、被版本管理。一個(gè)團(tuán)隊(duì)里不同Agent可能都要用到“發(fā)送郵件”這個(gè)能力。如果每個(gè)人各自寫(xiě)一個(gè)函數(shù)改一個(gè)邏輯就得全網(wǎng)通知完全是一團(tuán)亂麻。所以agent-skills的核心理念是把“模型與外部世界交互的最小能力單元”標(biāo)準(zhǔn)化、模塊化、可管理化。它不是函數(shù)的上位替代而是在函數(shù)和服務(wù)之上加了一層面向任務(wù)的“能力殼”。1.2 技能與大模型協(xié)作時(shí)的邊界劃分設(shè)計(jì)技能系統(tǒng)時(shí)我們得時(shí)刻想清楚哪些邏輯放模型那邊哪些邏輯放技能這邊。放錯(cuò)了結(jié)果就是要么模型瞎發(fā)揮要么技能臃腫得像個(gè)單體應(yīng)用。我的經(jīng)驗(yàn)是遵循一個(gè)原則凡是規(guī)則明確、有固定執(zhí)行路徑的盡量沉淀到技能內(nèi)部凡是需要理解、判斷、生成策略的留給模型去決策。拿“文件總結(jié)”舉例。文件格式識(shí)別、內(nèi)容分段提取、超長(zhǎng)文本切片這些是規(guī)則明確的必須在技能里做不能指望模型自己處理2萬(wàn)字的洗稿文件還能不丟上下文。但“從文件中找出核心觀點(diǎn)并輸出報(bào)告”這種就需要模型來(lái)判斷什么算“核心”技能把素材準(zhǔn)備好把決策權(quán)交給模型。再比如“聯(lián)網(wǎng)搜索”。技能內(nèi)部要處理搜索詞重構(gòu)、網(wǎng)頁(yè)抓取、正文提取、去重過(guò)濾這些統(tǒng)統(tǒng)是標(biāo)準(zhǔn)動(dòng)作。但“搜什么關(guān)鍵詞、看哪些鏈接、如何判斷信息可信度”就應(yīng)該讓模型基于當(dāng)前對(duì)話(huà)上下文來(lái)完成。邊界劃清楚了技能才會(huì)既穩(wěn)定又靈活。2. 技能系統(tǒng)的四大核心設(shè)計(jì)維度聊完“為什么”我們進(jìn)入正題看看一個(gè)生產(chǎn)可用的agent-skills框架到底要關(guān)注哪些設(shè)計(jì)維度。這里我會(huì)結(jié)合自己實(shí)際寫(xiě)過(guò)的框架來(lái)講盡量不說(shuō)虛的。2.1 接口標(biāo)準(zhǔn)讓技能像USB-C一樣即插即用技能系統(tǒng)的第一個(gè)核心問(wèn)題是接口怎么定。業(yè)界目前還沒(méi)有一個(gè)統(tǒng)一的Agent技能協(xié)議但一個(gè)合理的最小接口集通常包含這么幾個(gè)部分技能元信息名稱(chēng)、描述、版本、作者、依賴(lài)環(huán)境這些描述要夠清晰讓模型能準(zhǔn)確判斷“什么時(shí)候該用這個(gè)技能”。輸入/輸出契約結(jié)構(gòu)化定義技能接收什么參數(shù)、返回什么格式。這里建議用JSON Schema做輸入校驗(yàn)而不是相信任何調(diào)用方包括模型會(huì)規(guī)規(guī)矩矩傳參。執(zhí)行入口所有技能暴露一個(gè)統(tǒng)一的執(zhí)行方法比如Python里的async def run(context)或者def execute(params)這樣上層調(diào)度器可以統(tǒng)一調(diào)用不需要為每個(gè)技能寫(xiě)特判。生命周期鉤子初始化、校驗(yàn)、執(zhí)行、清理、錯(cuò)誤處理。這五個(gè)鉤子看著不起眼實(shí)際用起來(lái)能解決大量臟活累活。比如初始化時(shí)加載模型、連接數(shù)據(jù)庫(kù)清理時(shí)釋放資源錯(cuò)誤處理時(shí)做日志采集和降級(jí)。我自己在項(xiàng)目里用Pydantic定了一套基礎(chǔ)類(lèi)所有技能都繼承同一個(gè)基類(lèi)接口長(zhǎng)得像這樣簡(jiǎn)化版from pydantic import BaseModel, Field from abc import ABC, abstractmethod class SkillInput(BaseModel): pass class SkillOutput(BaseModel): pass class BaseSkill(ABC): name: str base_skill description: str Base skill description version: str 1.0.0 input_schema: type[SkillInput] SkillInput output_schema: type[SkillOutput] SkillOutput abstractmethod async def execute(self, params: SkillInput) - SkillOutput: ...這樣統(tǒng)一之后往下接Agent框架、往上掛服務(wù)層都很順因?yàn)橥鈱痈静辉诤跄銉?nèi)部干了啥只在乎你是不是實(shí)現(xiàn)了execute。2.2 技能注冊(cè)與發(fā)現(xiàn)模型怎么知道該用哪個(gè)技能接口標(biāo)準(zhǔn)化解決的是“怎么調(diào)用”接下來(lái)要解決“調(diào)用哪個(gè)”。模型在跑任務(wù)時(shí)不可能從幾百個(gè)技能里逐一篩選。所以技能系統(tǒng)需要一套注冊(cè)與發(fā)現(xiàn)機(jī)制。常見(jiàn)的做法是技能注冊(cè)中心Skill Registry。每個(gè)技能啟動(dòng)時(shí)向注冊(cè)中心登記自己的元信息注冊(cè)中心負(fù)責(zé)三件事維護(hù)一個(gè)“技能索引表”內(nèi)置技能ID、觸發(fā)條件、適用場(chǎng)景、輸入要求。根據(jù)Agent當(dāng)前的任務(wù)上下文做一次粗粒度的技能候選篩選。這一步可以用關(guān)鍵詞匹配也可以直接向量化后用語(yǔ)義檢索。將候選技能的名稱(chēng)和描述拼進(jìn)模型可訪(fǎng)問(wèn)的上下文里指導(dǎo)它精準(zhǔn)選擇。篩選這一步極其重要。如果不做粗篩把所有技能描述都塞給模型既浪費(fèi)token又會(huì)讓模型選擇困難甚至錯(cuò)誤使用。我見(jiàn)過(guò)一個(gè)案例Agent要執(zhí)行“查詢(xún)天氣”結(jié)果模型選了一個(gè)“股票行情分析”技能就是因?yàn)楹蜻x太多描述互相干擾。還有一個(gè)容易被忽略的點(diǎn)技能描述別寫(xiě)得太“文學(xué)化”。模型的語(yǔ)義理解能力再?gòu)?qiáng)你寫(xiě)“此技能旨在為用戶(hù)提供多元化全方位的信息獲取解決方案”它大概率搞不懂你在說(shuō)啥。直接寫(xiě)“按城市名查詢(xún)實(shí)時(shí)天氣支持國(guó)內(nèi)主要城市”這種大白話(huà)命中率反而高得多。2.3 技能上下文與狀態(tài)管理讓技能帶著“記憶”干活技能不能是無(wú)狀態(tài)的“純函數(shù)”否則在真實(shí)業(yè)務(wù)里會(huì)非常難用。比如一個(gè)“寫(xiě)周報(bào)”技能它需要知道用戶(hù)是誰(shuí)、過(guò)去七天做了什么、周報(bào)格式偏好是什么。這些信息從哪來(lái)不是每次調(diào)用都重新讓用戶(hù)填一遍而是技能系統(tǒng)要和Agent的上下文系統(tǒng)打通。這一塊我的設(shè)計(jì)思路是分三層全局上下文用戶(hù)身份、租戶(hù)配置、跨技能共享的偏好設(shè)置所有技能都能讀取。會(huì)話(huà)上下文當(dāng)前Agent會(huì)話(huà)內(nèi)的狀態(tài)比如對(duì)話(huà)歷史摘要、已經(jīng)執(zhí)行過(guò)的技能列表、中間產(chǎn)出物。技能私有狀態(tài)技能自己緩存的臨時(shí)數(shù)據(jù)比如一次長(zhǎng)任務(wù)中途的計(jì)算結(jié)果。實(shí)現(xiàn)上我通常會(huì)封裝一個(gè)SkillContext對(duì)象把它傳給每個(gè)技能的execute方法。這個(gè)對(duì)象內(nèi)部維護(hù)一個(gè)線(xiàn)程安全的內(nèi)存存儲(chǔ)同時(shí)支持序列化到Redis等外部存儲(chǔ)以便多實(shí)例部署時(shí)共享狀態(tài)。這里有一個(gè)經(jīng)驗(yàn)之談技能執(zhí)行過(guò)程中產(chǎn)生的中間數(shù)據(jù)盡量顯式寫(xiě)入上下文而不是藏在技能內(nèi)部的全局變量里。藏內(nèi)部變量的壞處是進(jìn)程一重啟就丟了而且多個(gè)技能并發(fā)跑的時(shí)候容易串?dāng)?shù)據(jù)。顯式寫(xiě)入上下文邏輯清晰還不容易踩并發(fā)坑。2.4 技能的可觀測(cè)性出問(wèn)題時(shí)別靠猜Agent系統(tǒng)是個(gè)天生的“黑盒”模型的行為有隨機(jī)性技能鏈路較長(zhǎng)一旦出問(wèn)題定位成本極高。所以技能系統(tǒng)從第一天起就要把可觀測(cè)性設(shè)計(jì)進(jìn)去等上線(xiàn)了再加通常已經(jīng)晚了。可觀測(cè)性至少要覆蓋四個(gè)維度日志每個(gè)技能執(zhí)行時(shí)記錄入?yún)?、出參、耗時(shí)、錯(cuò)誤堆棧。這個(gè)看起來(lái)基礎(chǔ)但很多團(tuán)隊(duì)連這個(gè)都沒(méi)做到出了問(wèn)題只能人肉翻日志。追蹤一條Agent任務(wù)會(huì)串起多個(gè)技能需要一個(gè)全局Trace ID貫穿始終把技能調(diào)用鏈串起來(lái)看。指標(biāo)技能的調(diào)用次數(shù)、成功率、平均耗時(shí)、p99耗時(shí)這些數(shù)據(jù)要持續(xù)采集用來(lái)判斷哪個(gè)技能需要優(yōu)化。評(píng)估技能產(chǎn)出的質(zhì)量評(píng)估。有些技能是純代碼邏輯輸出是確定性的好評(píng)估有些技能依賴(lài)模型生成輸出質(zhì)量波動(dòng)大就需要引入額外的評(píng)估機(jī)制比如用戶(hù)反饋打分、規(guī)則校驗(yàn)、定期抽樣人工評(píng)估。追蹤這塊我強(qiáng)烈建議選一個(gè)開(kāi)源方案比如OpenTelemetry的標(biāo)準(zhǔn)或者LangSmith這類(lèi)產(chǎn)品化的工具別自己造輪子。造輪子的坑在于初期看著省事等技能數(shù)量超過(guò)20個(gè)你會(huì)后悔的。3. 從零搭建一個(gè)最小可用的agent-skills框架講完了設(shè)計(jì)維度我們直接上手?jǐn)]一個(gè)最小但五臟俱全的skils框架。這個(gè)框架我實(shí)際在項(xiàng)目里用過(guò)簡(jiǎn)化版本地跑通后你完全可以往里面加數(shù)據(jù)庫(kù)、消息隊(duì)列、分布式調(diào)度把它擴(kuò)展成生產(chǎn)級(jí)。3.1 技能倉(cāng)庫(kù)結(jié)構(gòu)與基礎(chǔ)抽象先看倉(cāng)庫(kù)結(jié)構(gòu)。核心理念是一個(gè)技能一個(gè)目錄目錄內(nèi)自帶元信息、執(zhí)行邏輯和依賴(lài)聲明。這樣技能天然可復(fù)用、可分享新同學(xué)參與開(kāi)發(fā)也容易上手agent-skills/ ├── core/ │ ├── __init__.py │ ├── base.py # 技能基類(lèi)定義接口標(biāo)準(zhǔn) │ ├── registry.py # 技能注冊(cè)中心 │ ├── context.py # 技能上下文管理 │ └── exceptions.py # 統(tǒng)一異常體系 ├── skills/ │ ├── __init__.py │ ├── email_summary/ │ │ ├── skill.py # 技能主邏輯 │ │ ├── config.yaml # 技能配置 │ │ └── requirements.txt │ └── weather_query/ │ ├── skill.py │ ├── config.yaml │ └── requirements.txt ├── agent/ │ └── runner.py # 與模型交互的調(diào)度器 └── tests/ ├── test_registry.py └── test_email_summary.pybase.py里除了上面寫(xiě)過(guò)的基類(lèi)我還會(huì)加一個(gè)validate_input方法和一個(gè)preprocess鉤子。validate_input用JSON Schema做參數(shù)校驗(yàn)preprocess用來(lái)統(tǒng)一做鑒權(quán)、限流、資源準(zhǔn)備。這兩個(gè)方法非常實(shí)用能讓業(yè)務(wù)技能專(zhuān)注于自己的核心動(dòng)作class BaseSkill(ABC): 所有技能的抽象基類(lèi)定義生命周期和接口契約 name: str base_skill description: str version: str 1.0.0 tags: list[str] [] abstractmethod async def execute(self, params: SkillInput, context: SkillContext) - SkillOutput: 技能核心執(zhí)行邏輯子類(lèi)必須實(shí)現(xiàn) ... async def preprocess(self, params: SkillInput, context: SkillContext) - SkillInput: 執(zhí)行前的統(tǒng)一預(yù)處理如鑒權(quán)、限流 return params async def postprocess(self, result: SkillOutput, context: SkillContext) - SkillOutput: 執(zhí)行后的統(tǒng)一后處理如脫敏、格式化 return result async def cleanup(self, context: SkillContext) - None: 資源清理異常退出時(shí)也會(huì)被調(diào)用 ...3.2 技能注冊(cè)中心實(shí)現(xiàn)注冊(cè)中心是技能系統(tǒng)的“大腦”。我的實(shí)現(xiàn)里它維護(hù)兩套索引一套是按技能ID映射具體對(duì)象的字典一套是面向模型查詢(xún)的語(yǔ)義索引。后者我直接用了一個(gè)輕量級(jí)的詞向量匹配夠用不用動(dòng)不動(dòng)就上向量數(shù)據(jù)庫(kù)from typing import Optional, Type import inspect class SkillRegistry: 技能注冊(cè)中心負(fù)責(zé)登記、檢索和生命周期管理 def __init__(self): self._skills: dict[str, BaseSkill] {} self._semantic_index: dict[str, list[str]] {} # 技能ID - 關(guān)鍵詞列表 def register(self, skill: BaseSkill, keywords: list[str] | None None) - None: 注冊(cè)一個(gè)技能keywords是可選的觸發(fā)詞擴(kuò)展 if skill.name in self._skills: raise SkillConflictError(fskill {skill.name} already registered) self._skills[skill.name] skill self._semantic_index[skill.name] keywords or [] logger.info(fregistered skill: {skill.name} v{skill.version}) def discover(self, task_description: str, top_k: int 5) - list[BaseSkill]: 根據(jù)任務(wù)描述粗篩候選技能 candidates [] for name, skill in self._skills.items(): # 先用描述做粗過(guò)濾 score self._calc_match_score(task_description, skill.description) # 再加上關(guān)鍵詞擴(kuò)展命中 for kw in self._semantic_index[name]: if kw.lower() in task_description.lower(): score 0.5 candidates.append((score, skill)) candidates.sort(keylambda x: x[0], reverseTrue) return [s for _, s in candidates[:top_k] if _ 0] def get(self, skill_name: str) - Optional[BaseSkill]: return self._skills.get(skill_name) def _calc_match_score(self, task: str, description: str) - float: 輕量文本相似度實(shí)際項(xiàng)目里可換成embedding方案 task_set set(task.lower().replace(., ).split()) desc_set set(description.lower().split()) if not task_set or not desc_set: return 0.0 overlap len(task_set desc_set) return overlap * 2.0 / (len(task_set) len(desc_set))注冊(cè)中心的discover這里_calc_match_score是一個(gè)非常簡(jiǎn)化的詞重疊方案。實(shí)際生產(chǎn)環(huán)境我會(huì)推薦用sentence-transformer或者OpenAI的embedding接口生成描述向量再用余弦相似度檢索。不過(guò)本地demo階段詞重疊方案已經(jīng)能讓你看到完整流程的樣子了。3.3 Agent調(diào)度器讓模型在技能中間做決策有了注冊(cè)中心接下來(lái)寫(xiě)Agent調(diào)度器。這塊的核心是一個(gè)循環(huán)模型看任務(wù)決定調(diào)哪個(gè)技能技能執(zhí)行結(jié)果喂回模型模型決定下一步動(dòng)作。整個(gè)過(guò)程有點(diǎn)像帶工具的人類(lèi)員工干活想到什么查一下得到結(jié)果繼續(xù)想直到任務(wù)完成。from typing import Optional import json class AgentRunner: Agent調(diào)度器負(fù)責(zé)編排模型與技能的交互流程 def __init__(self, model_api, registry: SkillRegistry, max_steps: int 8): self.model_api model_api self.registry registry self.max_steps max_steps async def run(self, user_query: str) - str: messages [{role: user, content: user_query}] for step in range(self.max_steps): response await self.model_api.chat(messages) # 解析模型輸出判斷是要求調(diào)用技能還是已生成最終回復(fù) action self._parse_action(response) if action[type] reply: return action[content] if action[type] call_skill: skill_name action[skill_name] params action[params] skill self.registry.get(skill_name) if not skill: messages.append({ role: tool, name: skill_name, content: json.dumps({error: fskill {skill_name} not found}) }) continue result await skill.execute( paramsskill.input_schema(**params), contextSkillContext() ) # 把執(zhí)行結(jié)果塞回對(duì)話(huà)歷史 messages.append({ role: tool, name: skill_name, content: result.model_dump_json() }) return 達(dá)到最大步數(shù)任務(wù)未完成。也許需要拆分任務(wù)或調(diào)整技能配置。實(shí)際接入時(shí)模型API返回的action格式需要根據(jù)你用的模型調(diào)整。用原生tool-calling接口比如OpenAI的tools參數(shù)會(huì)更規(guī)范內(nèi)部邏輯從“解析模型自然語(yǔ)言輸出”變成“解析結(jié)構(gòu)化tool_call”省去很多字符串解析的麻煩。上面這個(gè)示例保留了“模型輸出-解析-執(zhí)行”的流程方便你理解全局。3.4 技能上下文與配置文件實(shí)現(xiàn)最后是context.py和技能配置文件。SkillContext要能在整個(gè)技能鏈路里透明傳遞。為了演示簡(jiǎn)單這里用一個(gè)進(jìn)程內(nèi)的數(shù)據(jù)存儲(chǔ)生產(chǎn)環(huán)境換成Redis或數(shù)據(jù)庫(kù)連接也一樣from dataclasses import dataclass, field from datetime import datetime from typing import Any import threading, uuid dataclass class SkillContext: 技能執(zhí)行的全局上下文承載狀態(tài)傳遞 trace_id: str field(default_factorylambda: uuid.uuid4().hex) session_id: str user_id: str created_at: str field(default_factorylambda: datetime.utcnow().isoformat()) def __post_init__(self): self._state: dict[str, Any] {} self._lock threading.Lock() def set(self, key: str, value: Any) - None: with self._lock: self._state[key] value def get(self, key: str, default: Any None) - Any: with self._lock: return self._state.get(key, default) def to_dict(self) - dict: 序列化用便于日志和追蹤 return { trace_id: self.trace_id, session_id: self.session_id, user_id: self.user_id, created_at: self.created_at, state: self._state, }到這里一個(gè)最小可用的技能框架就能跑起來(lái)了。我本地測(cè)試時(shí)用上面這套結(jié)構(gòu)注冊(cè)了3個(gè)技能然后接一個(gè)開(kāi)源模型API讓它執(zhí)行“查詢(xún)北京的天氣并總結(jié)成一句提醒帶傘的話(huà)”這種復(fù)合任務(wù)。模型先調(diào)weather_query拿到結(jié)果后又調(diào)用text_summary生成最終回復(fù)整個(gè)鏈路走得相當(dāng)順。你可以試著在這個(gè)基礎(chǔ)上加技能進(jìn)去感受一下“能力單元被復(fù)用”的快樂(lè)。4. 實(shí)戰(zhàn)中的坑與排查技巧框架寫(xiě)出來(lái)是一回事跑起來(lái)不出問(wèn)題又是另一回事。這里我把自己在技能系統(tǒng)上踩過(guò)的坑整理成了一份速查希望能幫你少走彎路。4.1 技能參數(shù)校驗(yàn)不可靠模型傳參容易“自由發(fā)揮”模型生成JSON參數(shù)時(shí)偶爾會(huì)出現(xiàn)字段缺失、類(lèi)型錯(cuò)誤、枚舉值亂填的情況。如果你在技能內(nèi)部不校驗(yàn)直接取參數(shù)運(yùn)算輕則白跑一次重則把臟數(shù)據(jù)寫(xiě)進(jìn)數(shù)據(jù)庫(kù)。我的做法是三層防線(xiàn)第一層模型出口做一次結(jié)構(gòu)校驗(yàn)用tools接口自帶的strict模式或JSON Schema校驗(yàn)。第二層技能入口再校驗(yàn)一遍復(fù)用SkillInput的Pydantic能力。第三層技能內(nèi)部訪(fǎng)問(wèn)關(guān)鍵字段時(shí)用context.get加默認(rèn)值不要直接下標(biāo)訪(fǎng)問(wèn)。三個(gè)地方重復(fù)寫(xiě)校驗(yàn)確實(shí)有點(diǎn)繁瑣但它能擋住90%的異常讓技能的穩(wěn)定性上一個(gè)臺(tái)階。生產(chǎn)系統(tǒng)里出錯(cuò)成本的次序是運(yùn)行時(shí)拿臟數(shù)據(jù)最貴執(zhí)行前發(fā)現(xiàn)錯(cuò)誤較貴模型側(cè)攔截最便宜。所以不管你多懶第二層一定要保留。4.2 模型診斷技能調(diào)用失敗時(shí)別急著懷疑模型先查技能本身遇到Agent技能執(zhí)行報(bào)錯(cuò)第一反應(yīng)不應(yīng)該是“大模型是不是抽風(fēng)了”而是先看技能日志和追蹤信息。大概率是這幾個(gè)原因技能入?yún)⒉环项A(yù)期、依賴(lài)的第三方服務(wù)超時(shí)、技能內(nèi)部狀態(tài)被并發(fā)寫(xiě)壞了、技能描述與實(shí)際行為不一致導(dǎo)致模型錯(cuò)誤調(diào)用。我特別想提“技能描述與實(shí)際行為不一致”這個(gè)坑。有一次我寫(xiě)了一個(gè)“search_knowledge_base”技能內(nèi)部實(shí)現(xiàn)其實(shí)只能查文檔庫(kù)但描述里沒(méi)寫(xiě)清楚結(jié)果模型拿它去查用戶(hù)權(quán)限返回一堆無(wú)關(guān)內(nèi)容整個(gè)任務(wù)鏈路都偏了。后來(lái)我把描述改成“query internal documentation by keywords, returns document titles and snippets”行為才正常。你寫(xiě)技能描述時(shí)要站在模型的“閱讀理解視角”去審視而不是站在開(kāi)發(fā)者視角覺(jué)得“這不顯然嗎”。4.3 狀態(tài)泄漏多個(gè)Agent會(huì)話(huà)互相串?dāng)?shù)據(jù)技能里如果用了類(lèi)級(jí)變量或者模塊級(jí)單例來(lái)存臨時(shí)狀態(tài)在并發(fā)場(chǎng)景下A用戶(hù)的請(qǐng)求很可能會(huì)讀到B用戶(hù)的數(shù)據(jù)。這類(lèi)問(wèn)題最難排查因?yàn)閳?bào)錯(cuò)可能完全隨機(jī)。排查思路一旦出現(xiàn)這種偶發(fā)數(shù)據(jù)錯(cuò)亂先檢查技能里有沒(méi)有非必要的全局可變狀態(tài)再把SkillContext的set/get打點(diǎn)追蹤數(shù)據(jù)寫(xiě)入方和讀取方的會(huì)話(huà)ID。根治辦法是技能內(nèi)部盡量無(wú)狀態(tài)所有可變數(shù)據(jù)統(tǒng)一放上下文并且上下文要綁定會(huì)話(huà)ID。這里附一張我實(shí)際踩坑時(shí)整理的排查表癥狀最可能原因排查入口推薦做法技能偶爾返回空結(jié)果入?yún)⑿ｒ?yàn)不嚴(yán)模型傳入空值查看日志里的入?yún)⒖煺誗killInput加必填校驗(yàn)和默認(rèn)值并發(fā)時(shí)數(shù)據(jù)錯(cuò)亂技能內(nèi)部存在全局可變狀態(tài)檢查類(lèi)變量和模塊級(jí)變量狀態(tài)全部移入SkillContext模型頻繁調(diào)用錯(cuò)誤技能技能描述含糊或過(guò)于寬泛查看discover階段的候選排名重寫(xiě)描述增加觸發(fā)詞縮小邊界技能報(bào)超時(shí)依賴(lài)服務(wù)慢或技能無(wú)超時(shí)控制查看追蹤中的依賴(lài)耗時(shí)為外部調(diào)用統(tǒng)一設(shè)置超時(shí)和重試技能鏈路過(guò)長(zhǎng)模型記不住中間結(jié)果沒(méi)有把中間結(jié)果及時(shí)壓回對(duì)話(huà)上下文查看最終推理消息的上下文長(zhǎng)度適時(shí)對(duì)中間結(jié)果做摘要清理無(wú)用內(nèi)容4.4 超時(shí)與重試策略不能一刀切技能里調(diào)外部API、數(shù)據(jù)庫(kù)、模型接口每一個(gè)外部依賴(lài)都要有獨(dú)立的超時(shí)配置。千萬(wàn)不要只設(shè)一個(gè)全局默認(rèn)超時(shí)理由是不同依賴(lài)的健康狀態(tài)差異很大。比如連接本地Redis超時(shí)100毫秒都嫌多調(diào)第三方網(wǎng)頁(yè)搜索API3秒都可能不夠。我的習(xí)慣是在技能配置里加一個(gè)timeout字段每個(gè)技能按自身依賴(lài)特性聲明。重試策略同理非冪等操作比如“發(fā)送郵件”這種只允許發(fā)一次的千萬(wàn)別自動(dòng)重試否則用戶(hù)會(huì)收到三封一模一樣的郵件。區(qū)分冪等和非冪等操作是設(shè)計(jì)重試邏輯時(shí)的基本原則。4.5 日志別只打“成功”失敗時(shí)要留全現(xiàn)場(chǎng)最怕看到這樣的日志2025-01-10 11:22:33,456 ERROR skill failed完了沒(méi)參數(shù)、沒(méi)異常類(lèi)型、沒(méi)traceback等于啥也沒(méi)記。建議錯(cuò)誤日志至少包含技能名稱(chēng)、版本、本次執(zhí)行的trace_id、完整入?yún)⒚撁艉?、異常堆棧。入?yún)⒗锶绻婕皞€(gè)人敏感信息要先做脫敏再落日志。這個(gè)補(bǔ)丁看起來(lái)簡(jiǎn)單排查問(wèn)題時(shí)能救命的。5. 技能系統(tǒng)的進(jìn)階擴(kuò)展方向如果你已經(jīng)跑通了基礎(chǔ)框架接下來(lái)想往生產(chǎn)級(jí)走有這么幾個(gè)方向值得投入。5.1 技能自省與自動(dòng)生成讓Agent自己豐富技能庫(kù)高級(jí)玩家已經(jīng)在嘗試讓Agent在運(yùn)行過(guò)程中發(fā)現(xiàn)“能力缺口”然后自動(dòng)生成新技能來(lái)補(bǔ)上。實(shí)現(xiàn)路徑大致是當(dāng)Agent發(fā)現(xiàn)沒(méi)有技能能處理當(dāng)前任務(wù)時(shí)把任務(wù)保存到一個(gè)“未覆蓋需求池”定期用大模型分析這批需求生成候選技能的骨架代碼和描述再交給人工審核通過(guò)后入庫(kù)。這樣技能庫(kù)會(huì)像一個(gè)活體組織一樣隨業(yè)務(wù)需要自動(dòng)生長(zhǎng)。不過(guò)這條路的坑在于自動(dòng)生成的代碼質(zhì)量和安全性不可控需要非常嚴(yán)格的審核機(jī)制和沙箱隔離不是小團(tuán)隊(duì)能輕易駕馭的。5.2 技能組合編排把基礎(chǔ)技能拼成復(fù)雜工作流單個(gè)技能解決單一問(wèn)題復(fù)雜任務(wù)需要多個(gè)技能協(xié)同。進(jìn)階做法是引入“技能編排層”用DSL或圖結(jié)構(gòu)定義技能之間的依賴(lài)和執(zhí)行順序。比如“生成經(jīng)營(yíng)分析日?qǐng)?bào)”技能內(nèi)部會(huì)編排拉取數(shù)據(jù)data_fetch- 數(shù)據(jù)清洗data_clean- 指標(biāo)計(jì)算metric_calc- 報(bào)告生成report_gen。有了編排層我們就能對(duì)整條鏈路做更精細(xì)的控制比如某一步失敗時(shí)是重試還是走降級(jí)方案某兩步之間要不要做數(shù)據(jù)一致性校驗(yàn)。編排層的設(shè)計(jì)可以借鑒工作流引擎的成熟方案比如Temporal、Airflow但注意別做得過(guò)重Agent的技能編排要快進(jìn)快出。5.3 技能評(píng)測(cè)與持續(xù)優(yōu)化把技能當(dāng)成產(chǎn)品來(lái)運(yùn)營(yíng)技能上線(xiàn)不是終點(diǎn)而是要持續(xù)追蹤它的真實(shí)效果定期迭代。我建議每個(gè)技能上線(xiàn)時(shí)都跑一輪離線(xiàn)基準(zhǔn)測(cè)試用固定的測(cè)試集記錄技能的正確率、耗時(shí)、成本線(xiàn)上運(yùn)行后每天看指標(biāo)波動(dòng)每周選幾個(gè)低分案例人工復(fù)盤(pán)分析是模型問(wèn)題還是技能問(wèn)題還是數(shù)據(jù)問(wèn)題。這塊可以參考傳統(tǒng)MLOps的思路數(shù)據(jù)版本管理、模型版本管理、AB實(shí)驗(yàn)、灰度發(fā)布全都遷移到技能系統(tǒng)上來(lái)。技能系統(tǒng)的生命周期管理能力和模型一樣重要只是很多人意識(shí)得比較晚。我之前在一個(gè)客戶(hù)項(xiàng)目里就靠這個(gè)思路把一個(gè)文檔解析技能從最初的72%準(zhǔn)確率迭代到第三個(gè)月穩(wěn)定在94%靠的就是持續(xù)采集失敗樣本、補(bǔ)充邊界case、優(yōu)化技能內(nèi)部的預(yù)處理邏輯。這已經(jīng)不是在“寫(xiě)代碼”了而是在“運(yùn)營(yíng)技能資產(chǎn)”。寫(xiě)在最后的實(shí)際操作體會(huì)技能系統(tǒng)這個(gè)東西看著技術(shù)門(mén)檻好像不高但真正把一個(gè)技能體系從無(wú)到有搭起來(lái)、再跑穩(wěn)過(guò)程中會(huì)遇到特別多書(shū)本上不講的細(xì)節(jié)。我復(fù)盤(pán)了一下最值錢(qián)的體驗(yàn)有三件事第一接口規(guī)范化越早做越好。寧可一開(kāi)始多花兩天把技能基類(lèi)和注冊(cè)機(jī)制設(shè)計(jì)好也別圖快先寫(xiě)業(yè)務(wù)技能。一旦業(yè)務(wù)技能多了再回頭統(tǒng)一接口那個(gè)成本會(huì)是初期的好幾倍。第二技能描述就是給模型看的“產(chǎn)品說(shuō)明書(shū)”值得花時(shí)間打磨。同一個(gè)技能描述寫(xiě)得好和寫(xiě)得差在Agent任務(wù)上的成功率能有兩位數(shù)的差距。寫(xiě)完之后拿幾個(gè)典型任務(wù)跑一遍測(cè)試看看模型到底會(huì)不會(huì)選對(duì)這比看文檔寫(xiě)得多漂亮重要得多。第三可觀測(cè)性是對(duì)Agent系統(tǒng)最大的善意。Agent任務(wù)天然帶隨機(jī)性和長(zhǎng)鏈路沒(méi)有日志、追蹤和指標(biāo)這三件套出問(wèn)題時(shí)你會(huì)變成盲人摸象。所以每次在企業(yè)里推行Agent方案我都會(huì)先說(shuō)一句先把觀測(cè)鋪好再談業(yè)務(wù)指標(biāo)?，F(xiàn)在這個(gè)框架我已經(jīng)在幾個(gè)線(xiàn)下項(xiàng)目里跑過(guò)企業(yè)內(nèi)部知識(shí)庫(kù)問(wèn)答、工單自動(dòng)分揀、報(bào)表生成助手都從這套技能系統(tǒng)里獲益不少。如果你也在設(shè)計(jì)自己的Agent技能體系或者已經(jīng)在用類(lèi)似方案歡迎在評(píng)論區(qū)聊聊你的實(shí)踐心得一起把這塊的方法論再打磨得更扎實(shí)一點(diǎn)。