用管理實(shí)戰(zhàn))
去年年底在重構(gòu)一個(gè)內(nèi)部 AI 助手時(shí)我反復(fù)遇到同一個(gè)尷尬模型本身很聰明但它總是用錯(cuò)工具、漏傳參數(shù)甚至在不需要查詢(xún)時(shí)硬去搜索。后來(lái)我把所有工具調(diào)用收攏成一套獨(dú)立管理機(jī)制也就是現(xiàn)在這個(gè)名為 agent-skills 的技能注冊(cè)與調(diào)度體系才真正把會(huì)對(duì)話的模型變成會(huì)辦事的模型。這篇文章不聊空理論只講我實(shí)際怎么設(shè)計(jì)、怎么落地以及中間踩過(guò)的那些坑給準(zhǔn)備做 Agent 技能編排、工具庫(kù)管理、Function Calling 架構(gòu)的同學(xué)一個(gè)可參考的樣本。1. 為什么我會(huì)專(zhuān)門(mén)抽一層技能庫(kù)來(lái)管 Agent 的能力1.1 之前把所有工具寫(xiě)死在代碼里問(wèn)題有多嚴(yán)重最初做 Agent 原型時(shí)我的寫(xiě)法非常直接在系統(tǒng)提示詞里把所有工具描述寫(xiě)進(jìn)去然后代碼里放一堆 if-else 或者 match-case把模型返回的函數(shù)名映射到實(shí)際函數(shù)。這個(gè)方案在只有兩三個(gè)工具時(shí)很好用但一旦超過(guò)十個(gè)麻煩就接踵而至。首先是提示詞越來(lái)越長(zhǎng)每次調(diào)用都要攜帶全部工具描述token 消耗大而且模型對(duì)后邊的工具描述記憶明顯減弱。其次是新增一個(gè)工具要改多處代碼——注冊(cè)、描述、參數(shù)校驗(yàn)、異常處理漏一處就出 Bug。第三是工具之間會(huì)有交叉依賴(lài)比如搜索和抓取網(wǎng)頁(yè)經(jīng)常要組合使用但在硬編碼結(jié)構(gòu)里這種組合邏輯完全沒(méi)法復(fù)用。最后逼我動(dòng)手重構(gòu)的導(dǎo)火索是一次演示翻車(chē)模型明明應(yīng)該調(diào)用查數(shù)據(jù)庫(kù)技能卻因?yàn)槊枋隼镉袀€(gè)模糊詞誤選了搜索文件。那時(shí)候我意識(shí)到不能把工具當(dāng)散兵游勇得把它們變成一個(gè)結(jié)構(gòu)化的技能資產(chǎn)來(lái)治理。1.2 agent-skills 的設(shè)計(jì)目標(biāo)我需要的不是一個(gè)框架而是一套輕量級(jí)的規(guī)范。當(dāng)時(shí)列了幾個(gè)硬性要求每個(gè)技能有獨(dú)立、自描述的結(jié)構(gòu)包含名稱(chēng)、用途、參數(shù)校驗(yàn)規(guī)則、執(zhí)行體。技能注冊(cè)是聲明式的新增技能不需要改動(dòng)調(diào)度主邏輯。模型看到的技能目錄是動(dòng)態(tài)生成的可以根據(jù)對(duì)話上下文裁剪而不是一股腦全塞進(jìn)去。技能之間可以有顯式的依賴(lài)關(guān)系允許一個(gè)技能內(nèi)部調(diào)用另一個(gè)技能。這套規(guī)范我起名叫 agent-skills后面就是按這個(gè)思路一步步實(shí)裝的。它的本質(zhì)是把模型可以調(diào)用什么這件事從代碼中解耦出來(lái)變成可注冊(cè)、可發(fā)現(xiàn)、可度量、可淘汰的資源。1.3 和 Function Calling、插件體系的關(guān)系提一句容易混淆的概念。OpenAI 的 Function Calling 是模型輸出結(jié)構(gòu)化調(diào)用指令的能力LangChain 的 Tool 則是將函數(shù)包裝成模型可用形式的抽象。agent-skills 更接近一個(gè)技能管理層它位于模型和實(shí)際工具函數(shù)之間負(fù)責(zé)技能的登記、索引、描述生成、參數(shù)校驗(yàn)和調(diào)用編排。你可以理解成 Function Calling 是通信協(xié)議Tool 是單個(gè)接口而 agent-skills 是管理這些接口的注冊(cè)中心和調(diào)度器。這樣分層之后換一個(gè)底層模型、換一種 Function Calling 實(shí)現(xiàn)技能定義不用大改上層業(yè)務(wù)代碼也不受影響。2. 技能的標(biāo)準(zhǔn)結(jié)構(gòu)一個(gè)可被模型讀懂和執(zhí)行的單元2.1 核心組成身份、Schema、執(zhí)行體在 agent-skills 里我定義了一個(gè)技能的最小單元它必須有四個(gè)部分name機(jī)器可讀的技能標(biāo)識(shí)用 snake_case比如 web_search。description給模型看的人類(lèi)可讀說(shuō)明必須包含什么時(shí)候用、什么時(shí)候不要用。parameters參數(shù)結(jié)構(gòu)定義使用 Pydantic 模型自動(dòng)生成 JSON Schema。execute異步執(zhí)行函數(shù)負(fù)責(zé)完成具體動(dòng)作并返回結(jié)構(gòu)化結(jié)果。這個(gè)結(jié)構(gòu)參考了 OpenAPI 規(guī)范和 Anthropic 的 tool use 格式但為敏捷開(kāi)發(fā)做了一些簡(jiǎn)化。下面是實(shí)際代碼里 Skill 類(lèi)的核心片段。from typing import Any, Callable, Optional, Type from pydantic import BaseModel, create_model import json class Skill: def __init__( self, name: str, description: str, params_model: Type[BaseModel], execute: Callable[..., Any], category: str general, version: str 1.0.0, ): self.name name self.description description self.params_model params_model self.execute execute self.category category self.version version property def param_schema(self) - dict: # 由 Pydantic 模型直接生成 JSON Schema供模型側(cè)使用 return self.params_model.model_json_schema() async def run(self, **kwargs) - Any: # 入口處統(tǒng)一做參數(shù)校驗(yàn)失敗時(shí)給出可讀錯(cuò)誤信息 validated self.params_model(**kwargs) return await self.execute(**validated.model_dump())這里最容易被忽略的一點(diǎn)是參數(shù)校驗(yàn)不能放到執(zhí)行函數(shù)內(nèi)部做必須在技能入口統(tǒng)一做。因?yàn)槟Ｐ头祷氐膮?shù)經(jīng)常有缺漏、類(lèi)型錯(cuò)誤如果每個(gè)技能里各寫(xiě)各的校驗(yàn)很快就會(huì)出現(xiàn)同一個(gè)錯(cuò)誤在不同技能上報(bào)錯(cuò)格式不一致的情況。統(tǒng)一在 run 里做校驗(yàn)后續(xù)做日志審計(jì)、指標(biāo)收集都會(huì)方便很多。2.2 為什么要用 Pydantic 自動(dòng)生成 Schema而不是手寫(xiě) JSON我見(jiàn)過(guò)不少項(xiàng)目直接在代碼里手寫(xiě) JSON Schema比如{ type: object, properties: { query: {type: string, description: 搜索關(guān)鍵詞} }, required: [query] }第一次寫(xiě)沒(méi)問(wèn)題但技能有二十個(gè)以后字段一改手寫(xiě)的 JSON 經(jīng)常忘記同步。模型拿到的 Schema 和實(shí)際執(zhí)行函數(shù)對(duì)不上后果就是調(diào)用時(shí)報(bào)參數(shù)錯(cuò)誤甚至是更隱蔽的漏參。用 Pydantic 之后參數(shù)模型就是唯一事實(shí)來(lái)源。比如我定義搜索技能from pydantic import BaseModel, Field class WebSearchParams(BaseModel): query: str Field(description搜索關(guān)鍵詞盡量精確) max_results: int Field(3, ge1, le10, description返回結(jié)果數(shù)量) region: str Field(zh-CN, description搜索區(qū)域) async def web_search(query: str, max_results: int, region: str) - list[dict]: # 實(shí)際調(diào)用搜索 API ...param_schema會(huì)直接生成{ properties: { query: {description: 搜索關(guān)鍵詞盡量精確, title: Query, type: string}, max_results: {default: 3, description: 返回結(jié)果數(shù)量, maximum: 10, minimum: 1, type: integer}, region: {default: zh-CN, description: 搜索區(qū)域, type: string} }, required: [query], title: WebSearchParams, type: object }這樣寫(xiě)的好處不僅是少改一份文件更重要的是Pydantic 的 Field 約束ge、le、枚舉等會(huì)直接變成模型可讀的約束信息模型生成參數(shù)時(shí)會(huì)更少越界。實(shí)測(cè)下來(lái)參數(shù)非法導(dǎo)致的重試次數(shù)下降了約 40%。2.3 技能描述怎么寫(xiě)模型才聽(tīng)得懂這是整個(gè)技能庫(kù)里最軟但也最關(guān)鍵的部分。我發(fā)現(xiàn)很多團(tuán)隊(duì)把描述寫(xiě)成一句話簡(jiǎn)介比如執(zhí)行搜索模型根本選不準(zhǔn)。我的經(jīng)驗(yàn)是描述里必須寫(xiě)清使用場(chǎng)景和不要使用的場(chǎng)景而且要給出正反例。下面是我常用的一段描述使用場(chǎng)景當(dāng)用戶需要查詢(xún)實(shí)時(shí)信息、獲取最新新聞、查找某個(gè)機(jī)構(gòu)/人物/產(chǎn)品的當(dāng)前情況時(shí)。 不要使用如果用戶只是問(wèn)概念解釋、歷史知識(shí)且不要求最新信息請(qǐng)使用 knowledge_base 技能。這段描述直接把搜索技能和知識(shí)庫(kù)技能區(qū)分開(kāi)了。模型對(duì)什么時(shí)候不要用特別敏感因?yàn)榇罅空`選都發(fā)生在兩個(gè)技能邊界模糊時(shí)。后面我還會(huì)專(zhuān)門(mén)講怎么靠邊界描述來(lái)提升技能選擇的準(zhǔn)確率。3. 注冊(cè)中心與動(dòng)態(tài)發(fā)現(xiàn)讓新建技能像插線板一樣簡(jiǎn)單3.1 基于裝飾器的注冊(cè)機(jī)制有了技能定義下一步是把它們收集到一個(gè)注冊(cè)中心里。我用的方式是在模塊加載時(shí)通過(guò)裝飾器自動(dòng)注冊(cè)。先定義全局注冊(cè)表from typing import Dict from dataclasses import dataclass, field class SkillRegistry: def __init__(self): self._skills: Dict[str, Skill] {} def register(self, skill: Skill) - Skill: if skill.name in self._skills: raise ValueError(fSkill {skill.name} already registered) self._skills[skill.name] skill return skill def get(self, name: str) - Skill: return self._skills[name] def all(self) - list[Skill]: return list(self._skills.values()) registry SkillRegistry() def skill_skill( description: str, category: str general, version: str 1.0.0, ): def wrapper(params_model: Type[BaseModel], execute: Callable): skill Skill( nameexecute.__name__, descriptiondescription, params_modelparams_model, executeexecute, categorycategory, versionversion, ) registry.register(skill) return skill return wrapper具體使用如下skill_skill( description獲取指定城市的當(dāng)前天氣適合用戶詢(xún)問(wèn)天氣、溫度、降雨概率時(shí)。, categoryutility, ) class GetWeatherParams(BaseModel): city: str Field(description城市中文名) async def get_weather(city: str) - dict: ...裝飾器把函數(shù)名作為技能名參數(shù)類(lèi)作為 Schema 定義整個(gè)流程非常輕。新加一個(gè)技能時(shí)只有模塊被 import 進(jìn)來(lái)技能就會(huì)自動(dòng)進(jìn)入注冊(cè)表主調(diào)度邏輯完全不用改。這基本就是插件架構(gòu)的低配版但已經(jīng)能很好地滿足需求。3.2 為什么不用硬編碼列表很多人會(huì)問(wèn)項(xiàng)目不大直接在列表里寫(xiě)清楚不就行了我早期也這么做過(guò)但吃了幾次虧之后決定改用注冊(cè)中心。一次是多人協(xié)作時(shí)同事加了一個(gè)技能但導(dǎo)入了模塊卻忘記在列表里追加結(jié)果模型看不到這個(gè)技能。還有一次是寫(xiě)測(cè)試時(shí)需要隔離技能集合硬編碼列表讓測(cè)試非常別扭。改用注冊(cè)中心后測(cè)試時(shí)可以輕松構(gòu)造一個(gè)臨時(shí) Registry 并注入 mock 技能再也不用擔(dān)心污染公共列表。另外自動(dòng)掃描還有利于做按需加載。大項(xiàng)目里技能可能涉及重依賴(lài)比如 PDF 解析技能要導(dǎo)入一堆庫(kù)。我可以在技能模塊里做懶加載注冊(cè)階段只存描述和 Schema執(zhí)行時(shí)才真正 import 重依賴(lài)庫(kù)。這樣應(yīng)用啟動(dòng)速度和內(nèi)存占用都更可控。3.3 技能間依賴(lài)從重復(fù)實(shí)現(xiàn)到組合調(diào)用技能庫(kù)管理工具多了以后第二個(gè)高頻需求就是技能復(fù)用。比如天氣查詢(xún)和穿衣建議兩個(gè)技能后者應(yīng)該組合前者而不是重新實(shí)現(xiàn)一遍天氣邏輯。我采用的方式是在 Skill 執(zhí)行體里可以直接拿到注冊(cè)表實(shí)例async def dressing_advice(city: str, temp: float) - str: weather_skill registry.get(get_weather) weather await weather_skill.run(citycity) ...這樣調(diào)度核心不關(guān)心技能內(nèi)部怎么組織下游技能只需要知道自己依賴(lài)哪個(gè)技能名。但我會(huì)在技能描述里顯式聲明依賴(lài)比如本技能需要依賴(lài) get_weather 獲取實(shí)時(shí)溫度這樣模型選擇組合型技能時(shí)會(huì)更清楚它背后的成本。不過(guò)這里也要提醒一句技能間調(diào)用會(huì)增加一次模型調(diào)度延遲如果可以盡量在同一個(gè)執(zhí)行函數(shù)內(nèi)并行調(diào)用多個(gè)基礎(chǔ)技能而不是串行依賴(lài)。我后面會(huì)專(zhuān)門(mén)講性能優(yōu)化。4. 讓模型知道用什么技能技能選擇提示詞的組裝策略4.1 全量技能都塞進(jìn) Prompt 是最蠢的做法一開(kāi)始我天真地把所有技能的名字、描述、參數(shù)規(guī)則全部塞進(jìn) system prompt。技能數(shù)量只有五個(gè)的時(shí)候還行到十五個(gè)以后模型的選擇準(zhǔn)確率明顯下降token 消耗也讓人肉疼。后來(lái)我統(tǒng)計(jì)了一次完整對(duì)話的平均 token 消耗系統(tǒng)提示詞里技能描述占了 60% 以上而實(shí)際單輪對(duì)話中模型通常只需要兩三個(gè)技能。也就是說(shuō)絕大部分信息是冗余的反而干擾了模型的注意力。4.2 兩級(jí)索引先選技能再補(bǔ)詳情我的解法是兩級(jí)索引策略。第一級(jí)維護(hù)一個(gè)精簡(jiǎn)的技能目錄每個(gè)技能只保留 name、一句話簡(jiǎn)介、使用場(chǎng)景、參數(shù)約束摘要。這個(gè)目錄盡量控制在模型能一屏看完的規(guī)模目標(biāo)是讓模型快速定位候選技能。第二級(jí)當(dāng)模型在回復(fù)中表示需要調(diào)用技能 X時(shí)調(diào)度器再把技能 X 的完整參數(shù) Schema、詳細(xì)描述、示例注入到下一輪上下文里讓模型嚴(yán)格按 Schema 生成參數(shù)。具體實(shí)現(xiàn)上我在 system prompt 里放這樣的模板可用技能目錄 {skills_catalog} 如果你需要完成某個(gè)操作請(qǐng)先輸出要使用的技能名稱(chēng)以及對(duì)應(yīng)的參數(shù) JSON。def build_skills_catalog(skills: list[Skill]) - str: lines [] for s in skills: lines.append( f- {s.name}: {s.description.split(使用場(chǎng)景)[0].strip()} ) return \n.join(lines) def build_skill_detail(skill: Skill) - str: return ( f技能名稱(chēng): {skill.name}\n f完整描述: {skill.description}\n f參數(shù)Schema: {json.dumps(skill.param_schema, ensure_asciiFalse, indent2)}\n f請(qǐng)嚴(yán)格按照Schema生成參數(shù)。 )調(diào)用流程簡(jiǎn)化為模型閱讀技能目錄判斷需要哪個(gè)技能。模型輸出技能名和參數(shù)摘要也可以直接輸出空參數(shù)。調(diào)度器找到技能詳情拼接到下一輪 prompt。模型輸出最終結(jié)構(gòu)化參數(shù)。調(diào)度器校驗(yàn)并執(zhí)行技能。這個(gè)流程讓模型每次只需要關(guān)注一小段信息準(zhǔn)確率提高非常明顯。代價(jià)是多了一輪交互但很多場(chǎng)景下值得。后續(xù)也可以對(duì)高頻技能做緩存根據(jù)對(duì)話主題直接預(yù)加載幾個(gè)可疑技能減少試探輪次。4.3 上下文裁剪根據(jù)對(duì)話狀態(tài)動(dòng)態(tài)過(guò)濾技能目錄除了兩級(jí)索引動(dòng)態(tài)裁剪也很關(guān)鍵。我的實(shí)現(xiàn)里維護(hù)了一個(gè)context_tags也就是從當(dāng)前對(duì)話中抽取的場(chǎng)景標(biāo)簽比如天氣新聞SQL。然后在構(gòu)建目錄時(shí)根據(jù)標(biāo)簽過(guò)濾掉明顯不相關(guān)的技能。比如用戶問(wèn)今天天氣就沒(méi)必要把數(shù)據(jù)庫(kù)備份這種運(yùn)維技能展示給模型。這個(gè)能力依賴(lài)于對(duì)用戶意圖的初步判斷不一定要很精確只要能把候選集從二十個(gè)降到五六個(gè)模型選擇的準(zhǔn)確度就能上一個(gè)臺(tái)階。我建議用一次快速的輕量分類(lèi)來(lái)打標(biāo)簽而不是讓主 Agent 又做意圖識(shí)別又做技能選擇否則每輪推理成本會(huì)高得離譜。5. 實(shí)測(cè)我把這套技術(shù)寫(xiě)作助手跑起來(lái)之后5.1 場(chǎng)景設(shè)定與技能清單為了驗(yàn)證 agent-skills 不是玩具我做了一個(gè)相對(duì)完整的示例項(xiàng)目一個(gè)技術(shù)寫(xiě)作助手。它需要完成資料搜索、網(wǎng)頁(yè)內(nèi)容摘要、代碼示例獲取、稿件素材整理、保存到 Notion 數(shù)據(jù)庫(kù)這些任務(wù)。當(dāng)時(shí)注冊(cè)的技能包括技能名用途依賴(lài)web_search搜索最新技術(shù)資料無(wú)fetch_webpage抓取網(wǎng)頁(yè)正文并轉(zhuǎn)成純文本無(wú)extract_code從網(wǎng)頁(yè)正文中提取代碼塊fetch_webpagegenerate_summary調(diào)用大模型對(duì)文本生成摘要無(wú)save_to_notion將整理好的內(nèi)容保存到數(shù)據(jù)庫(kù)無(wú)5.2 效果對(duì)比技能選擇準(zhǔn)確率從 68% 提到 94%我準(zhǔn)備了一百條真實(shí)用戶問(wèn)句作為測(cè)試集覆蓋搜索、摘要、保存、組合任務(wù)等類(lèi)型。在沒(méi)做技能庫(kù)管理、所有工具硬編碼、描述也很簡(jiǎn)陋的情況下模型正確選擇技能的比例只有 68%也就是三成的情況下選出了錯(cuò)誤的工具。經(jīng)過(guò)技能結(jié)構(gòu)標(biāo)準(zhǔn)化、兩級(jí)索引、動(dòng)態(tài)裁剪和描述優(yōu)化之后同樣的一百條樣本技能選擇準(zhǔn)確率提升到了 94%。誤選主要發(fā)生在fetch_webpage和extract_code之間的調(diào)用順序上后來(lái)靠強(qiáng)化示例才壓下去。token 消耗方面也有明顯改善。沒(méi)優(yōu)化前每輪對(duì)話平均在系統(tǒng)提示詞上花費(fèi)約 1800 token優(yōu)化后因?yàn)橹蛔⑷肽夸浐捅匾募寄茉斍槠骄档?700 token 左右整體對(duì)話成本下降了約 60%。當(dāng)然這個(gè)數(shù)據(jù)跟具體技能數(shù)量和模型上下文能力有關(guān)系但方向是通用的。5.3 一個(gè)讓我意外的發(fā)現(xiàn)技能執(zhí)行結(jié)果也需要結(jié)構(gòu)化回填做到一半我發(fā)現(xiàn)技能執(zhí)行完返回的數(shù)據(jù)不能原樣丟給模型。直接返回一長(zhǎng)串網(wǎng)頁(yè)全文不僅浪費(fèi) token而且模型難以提取重點(diǎn)。后來(lái)我給技能加了一層format_result讓每個(gè)技能返回結(jié)構(gòu)化且精煉的結(jié)果摘要。比如搜索技能返回的不是完整結(jié)果列表而是每個(gè)結(jié)果的標(biāo)題、URL、時(shí)間、一句話摘要。這個(gè)改動(dòng)讓后續(xù)對(duì)話的上下文變得更干凈模型在引用資料時(shí)也更準(zhǔn)確。我建議給每個(gè)技能準(zhǔn)備一個(gè)result_summary方法或者至少對(duì)返回內(nèi)容做一個(gè) token 上限截?cái)?。這比在主提示詞里寫(xiě)請(qǐng)忽略無(wú)關(guān)內(nèi)容有效得多。6. 最容易翻車(chē)的三個(gè)細(xì)節(jié)與我的完整排查鏈路6.1 現(xiàn)象模型總把參數(shù)類(lèi)型搞錯(cuò)第一次上線時(shí)模型調(diào)用web_search時(shí)把max_results傳成了字符串 5。Pydantic 其實(shí)會(huì)自動(dòng)做類(lèi)型轉(zhuǎn)換但如果是字符串 abc 就會(huì)直接報(bào)錯(cuò)。本來(lái)我以為校驗(yàn)失敗會(huì)讓模型自己重試但發(fā)現(xiàn)模型報(bào)錯(cuò)后經(jīng)常不知道該改成什么。排查鏈路我先在日志里打印每次技能執(zhí)行的validated參數(shù)確認(rèn)錯(cuò)誤來(lái)源是類(lèi)型強(qiáng)制轉(zhuǎn)換失敗。然后檢查 Pydantic 的model_config發(fā)現(xiàn)沒(méi)有禁止字符串強(qiáng)轉(zhuǎn)成數(shù)字。調(diào)整參數(shù)模型增加strictTrue讓多余的類(lèi)型強(qiáng)迫轉(zhuǎn)換直接失敗反而讓模型更容易理解錯(cuò)誤信息。再給校驗(yàn)錯(cuò)誤設(shè)計(jì)了一條清晰的錯(cuò)誤提示包括出錯(cuò)字段、期望類(lèi)型、傳入值要求模型重新生成參數(shù)。這個(gè)鏈路最值得夸的一點(diǎn)是Pydantic 的嚴(yán)格模式一開(kāi)始就要開(kāi)。如果不嚴(yán)格很多隱性類(lèi)型問(wèn)題會(huì)在技能執(zhí)行階段才炸出來(lái)而且定位成本更高。6.2 現(xiàn)象兩個(gè)技能描述太像模型反復(fù)選錯(cuò)有一次模型在查天氣和查空氣質(zhì)量之間反復(fù)橫跳幾乎沒(méi)什么規(guī)律。我把兩個(gè)技能的完整描述拿出來(lái)逐字對(duì)比發(fā)現(xiàn)都寫(xiě)著用于查詢(xún)城市的當(dāng)前環(huán)境信息。這顯然不行。排查鏈路我寫(xiě)了一個(gè)小腳本對(duì)所有技能描述做兩兩相似度計(jì)算用簡(jiǎn)單的關(guān)鍵詞重疊度發(fā)現(xiàn)get_weather和get_air_quality的相似度最高。為每個(gè)技能重寫(xiě)了描述補(bǔ)充明確的邊界場(chǎng)景。比如空氣質(zhì)量技能必須提到AQI、PM2.5、污染天氣技能必須提到溫度、濕度、降雨。在測(cè)試集上加了兩條容易混淆的用例比如今天出門(mén)要不要戴口罩應(yīng)該選空氣質(zhì)量今天會(huì)不會(huì)下雨應(yīng)該選天氣。之后我把技能描述相似度檢查加入了 CI。每次提交代碼時(shí)自動(dòng)跑一遍如果發(fā)現(xiàn)兩個(gè)技能描述相似度過(guò)高就報(bào)警提示人工review。這個(gè)工具對(duì)團(tuán)隊(duì)協(xié)作特別有用。6.3 現(xiàn)象上下文里技能太多模型瞎選有段時(shí)間我的技能數(shù)量增加到二十多個(gè)即便做了目錄精簡(jiǎn)模型還是時(shí)不時(shí)選出一個(gè)跟當(dāng)前話題八竿子打不著的技能。排查鏈路我記錄了模型每次選擇的 log發(fā)現(xiàn)誤選大多發(fā)生在對(duì)話較長(zhǎng)的中后段。進(jìn)一步檢查發(fā)現(xiàn)前置對(duì)話把模型注意力帶偏了尤其是之前提到過(guò)某個(gè)技能模型容易慣性選擇。于是在構(gòu)建新一輪技能目錄時(shí)我顯式把當(dāng)前用戶問(wèn)題放在目錄之前讓模型先明確問(wèn)題再看技能。另外把技能目錄按類(lèi)別折疊默認(rèn)只展示用戶當(dāng)前場(chǎng)景可能相關(guān)的類(lèi)別收起無(wú)關(guān)類(lèi)別。改完以后長(zhǎng)對(duì)話中的誤選率明顯下降。這說(shuō)明技能選擇不是純靠模型理解能力輸入的結(jié)構(gòu)化程度對(duì)結(jié)果影響很大。7. 技能治理版本、評(píng)估與淘汰機(jī)制技能庫(kù)不是一勞永逸的。加了新技能可能擠壓舊技能的選擇空間改了一個(gè)技能的描述可能影響其他技能的邊界。我后來(lái)慢慢把這套東西當(dāng)成一個(gè)需要治理的代碼庫(kù)來(lái)對(duì)待。7.1 每個(gè)技能都要有版本和負(fù)責(zé)人我在 Skill 結(jié)構(gòu)里增加了author和version字段。雖然聽(tīng)起來(lái)不重要但在多人協(xié)作時(shí)版本標(biāo)簽?zāi)茏屓罩纠锏恼{(diào)用記錄對(duì)應(yīng)到一個(gè)明確的代碼版本。線上出問(wèn)題后git blame加version能快速定位是誰(shuí)改過(guò)、什么時(shí)候改的。7.2 建立技能選擇回歸集我強(qiáng)烈建議項(xiàng)目里至少準(zhǔn)備 50 到 100 條標(biāo)注好的意圖 - 技能 - 參數(shù)測(cè)試用例。每次修改技能定義后跑一遍回歸集統(tǒng)計(jì)技能選擇準(zhǔn)確率和參數(shù)生成準(zhǔn)確率。再進(jìn)一步可以給每個(gè)技能單獨(dú)維護(hù)一條技能熱度和技能錯(cuò)誤率。如果一個(gè)技能連續(xù)半個(gè)月沒(méi)被調(diào)用或者調(diào)用后頻頻報(bào)錯(cuò)就該考慮下線或重寫(xiě)描述。我用一張簡(jiǎn)單的表來(lái)跟蹤技能名調(diào)用次數(shù)成功率平均耗時(shí)最后調(diào)用時(shí)間web_search32092%1.2s2025-01-10extract_code2578%3.1s2025-01-08定期看這張表你能發(fā)現(xiàn)很多之前沒(méi)注意的問(wèn)題。比如extract_code調(diào)用次數(shù)少但成功率低說(shuō)明描述可能太窄或者依賴(lài)的fetch_webpage返回內(nèi)容不理想。這種數(shù)據(jù)驅(qū)動(dòng)的迭代比憑感覺(jué)改 prompt 高效得多。7.3 技能描述也要做 A/B 測(cè)試最后分享一個(gè)偏門(mén)但有效的經(jīng)驗(yàn)對(duì)高爭(zhēng)議的技能描述做 A/B 測(cè)試。同一時(shí)間讓一半流量看到描述 A一半看到描述 B統(tǒng)計(jì)技能選擇的準(zhǔn)確率、任務(wù)完成率。我自己測(cè)試過(guò)web_search描述里加不加不要使用約束結(jié)果加了之后誤選率下降了 12%。看似一句話的差別在幾十個(gè)技能并存時(shí)影響會(huì)被放大。如果你沒(méi)有完整 A/B 平臺(tái)至少可以在本地跑一個(gè)小樣本對(duì)比把兩個(gè)描述各跑二十條測(cè)試用例看看哪個(gè)更穩(wěn)。說(shuō)實(shí)話做到這一步agent-skills 已經(jīng)不再是一個(gè)簡(jiǎn)單的工具管理腳本而是一套關(guān)于如何讓模型可靠地使用工具的方法論。它的價(jià)值不在于某個(gè)具體的技能實(shí)現(xiàn)而在于你能把每個(gè)能力變化都變成可測(cè)試、可回滾、可觀測(cè)的過(guò)程。對(duì)我個(gè)人而言這套機(jī)制最直接的好處是我再也不怕業(yè)務(wù)方突然提再加一個(gè)技能的需求了——無(wú)非是寫(xiě)一個(gè)函數(shù)、配一個(gè)描述、跑一遍回歸集的事。 從Function Calling到技能編排：Agent工具調(diào)用管理實(shí)戰(zhàn)
去年年底在重構(gòu)一個(gè)內(nèi)部 AI 助手時(shí)我反復(fù)遇到同一個(gè)尷尬模型本身很聰明但它總是用錯(cuò)工具、漏傳參數(shù)甚至在不需要查詢(xún)時(shí)硬去搜索。后來(lái)我把所有工具調(diào)用收攏成一套獨(dú)立管理機(jī)制也就是現(xiàn)在這個(gè)名為 agent-skills 的技能注冊(cè)與調(diào)度體系才真正把會(huì)對(duì)話的模型變成會(huì)辦事的模型。這篇文章不聊空理論只講我實(shí)際怎么設(shè)計(jì)、怎么落地以及中間踩過(guò)的那些坑給準(zhǔn)備做 Agent 技能編排、工具庫(kù)管理、Function Calling 架構(gòu)的同學(xué)一個(gè)可參考的樣本。1. 為什么我會(huì)專(zhuān)門(mén)抽一層技能庫(kù)來(lái)管 Agent 的能力1.1 之前把所有工具寫(xiě)死在代碼里問(wèn)題有多嚴(yán)重最初做 Agent 原型時(shí)我的寫(xiě)法非常直接在系統(tǒng)提示詞里把所有工具描述寫(xiě)進(jìn)去然后代碼里放一堆 if-else 或者 match-case把模型返回的函數(shù)名映射到實(shí)際函數(shù)。這個(gè)方案在只有兩三個(gè)工具時(shí)很好用但一旦超過(guò)十個(gè)麻煩就接踵而至。首先是提示詞越來(lái)越長(zhǎng)每次調(diào)用都要攜帶全部工具描述token 消耗大而且模型對(duì)后邊的工具描述記憶明顯減弱。其次是新增一個(gè)工具要改多處代碼——注冊(cè)、描述、參數(shù)校驗(yàn)、異常處理漏一處就出 Bug。第三是工具之間會(huì)有交叉依賴(lài)比如搜索和抓取網(wǎng)頁(yè)經(jīng)常要組合使用但在硬編碼結(jié)構(gòu)里這種組合邏輯完全沒(méi)法復(fù)用。最后逼我動(dòng)手重構(gòu)的導(dǎo)火索是一次演示翻車(chē)模型明明應(yīng)該調(diào)用查數(shù)據(jù)庫(kù)技能卻因?yàn)槊枋隼镉袀€(gè)模糊詞誤選了搜索文件。那時(shí)候我意識(shí)到不能把工具當(dāng)散兵游勇得把它們變成一個(gè)結(jié)構(gòu)化的技能資產(chǎn)來(lái)治理。1.2 agent-skills 的設(shè)計(jì)目標(biāo)我需要的不是一個(gè)框架而是一套輕量級(jí)的規(guī)范。當(dāng)時(shí)列了幾個(gè)硬性要求每個(gè)技能有獨(dú)立、自描述的結(jié)構(gòu)包含名稱(chēng)、用途、參數(shù)校驗(yàn)規(guī)則、執(zhí)行體。技能注冊(cè)是聲明式的新增技能不需要改動(dòng)調(diào)度主邏輯。模型看到的技能目錄是動(dòng)態(tài)生成的可以根據(jù)對(duì)話上下文裁剪而不是一股腦全塞進(jìn)去。技能之間可以有顯式的依賴(lài)關(guān)系允許一個(gè)技能內(nèi)部調(diào)用另一個(gè)技能。這套規(guī)范我起名叫 agent-skills后面就是按這個(gè)思路一步步實(shí)裝的。它的本質(zhì)是把模型可以調(diào)用什么這件事從代碼中解耦出來(lái)變成可注冊(cè)、可發(fā)現(xiàn)、可度量、可淘汰的資源。1.3 和 Function Calling、插件體系的關(guān)系提一句容易混淆的概念。OpenAI 的 Function Calling 是模型輸出結(jié)構(gòu)化調(diào)用指令的能力LangChain 的 Tool 則是將函數(shù)包裝成模型可用形式的抽象。agent-skills 更接近一個(gè)技能管理層它位于模型和實(shí)際工具函數(shù)之間負(fù)責(zé)技能的登記、索引、描述生成、參數(shù)校驗(yàn)和調(diào)用編排。你可以理解成 Function Calling 是通信協(xié)議Tool 是單個(gè)接口而 agent-skills 是管理這些接口的注冊(cè)中心和調(diào)度器。這樣分層之后換一個(gè)底層模型、換一種 Function Calling 實(shí)現(xiàn)技能定義不用大改上層業(yè)務(wù)代碼也不受影響。2. 技能的標(biāo)準(zhǔn)結(jié)構(gòu)一個(gè)可被模型讀懂和執(zhí)行的單元2.1 核心組成身份、Schema、執(zhí)行體在 agent-skills 里我定義了一個(gè)技能的最小單元它必須有四個(gè)部分name機(jī)器可讀的技能標(biāo)識(shí)用 snake_case比如 web_search。description給模型看的人類(lèi)可讀說(shuō)明必須包含什么時(shí)候用、什么時(shí)候不要用。parameters參數(shù)結(jié)構(gòu)定義使用 Pydantic 模型自動(dòng)生成 JSON Schema。execute異步執(zhí)行函數(shù)負(fù)責(zé)完成具體動(dòng)作并返回結(jié)構(gòu)化結(jié)果。這個(gè)結(jié)構(gòu)參考了 OpenAPI 規(guī)范和 Anthropic 的 tool use 格式但為敏捷開(kāi)發(fā)做了一些簡(jiǎn)化。下面是實(shí)際代碼里 Skill 類(lèi)的核心片段。from typing import Any, Callable, Optional, Type from pydantic import BaseModel, create_model import json class Skill: def __init__( self, name: str, description: str, params_model: Type[BaseModel], execute: Callable[..., Any], category: str general, version: str 1.0.0, ): self.name name self.description description self.params_model params_model self.execute execute self.category category self.version version property def param_schema(self) - dict: # 由 Pydantic 模型直接生成 JSON Schema供模型側(cè)使用 return self.params_model.model_json_schema() async def run(self, **kwargs) - Any: # 入口處統(tǒng)一做參數(shù)校驗(yàn)失敗時(shí)給出可讀錯(cuò)誤信息 validated self.params_model(**kwargs) return await self.execute(**validated.model_dump())這里最容易被忽略的一點(diǎn)是參數(shù)校驗(yàn)不能放到執(zhí)行函數(shù)內(nèi)部做必須在技能入口統(tǒng)一做。因?yàn)槟Ｐ头祷氐膮?shù)經(jīng)常有缺漏、類(lèi)型錯(cuò)誤如果每個(gè)技能里各寫(xiě)各的校驗(yàn)很快就會(huì)出現(xiàn)同一個(gè)錯(cuò)誤在不同技能上報(bào)錯(cuò)格式不一致的情況。統(tǒng)一在 run 里做校驗(yàn)后續(xù)做日志審計(jì)、指標(biāo)收集都會(huì)方便很多。2.2 為什么要用 Pydantic 自動(dòng)生成 Schema而不是手寫(xiě) JSON我見(jiàn)過(guò)不少項(xiàng)目直接在代碼里手寫(xiě) JSON Schema比如{ type: object, properties: { query: {type: string, description: 搜索關(guān)鍵詞} }, required: [query] }第一次寫(xiě)沒(méi)問(wèn)題但技能有二十個(gè)以后字段一改手寫(xiě)的 JSON 經(jīng)常忘記同步。模型拿到的 Schema 和實(shí)際執(zhí)行函數(shù)對(duì)不上后果就是調(diào)用時(shí)報(bào)參數(shù)錯(cuò)誤甚至是更隱蔽的漏參。用 Pydantic 之后參數(shù)模型就是唯一事實(shí)來(lái)源。比如我定義搜索技能from pydantic import BaseModel, Field class WebSearchParams(BaseModel): query: str Field(description搜索關(guān)鍵詞盡量精確) max_results: int Field(3, ge1, le10, description返回結(jié)果數(shù)量) region: str Field(zh-CN, description搜索區(qū)域) async def web_search(query: str, max_results: int, region: str) - list[dict]: # 實(shí)際調(diào)用搜索 API ...param_schema會(huì)直接生成{ properties: { query: {description: 搜索關(guān)鍵詞盡量精確, title: Query, type: string}, max_results: {default: 3, description: 返回結(jié)果數(shù)量, maximum: 10, minimum: 1, type: integer}, region: {default: zh-CN, description: 搜索區(qū)域, type: string} }, required: [query], title: WebSearchParams, type: object }這樣寫(xiě)的好處不僅是少改一份文件更重要的是Pydantic 的 Field 約束ge、le、枚舉等會(huì)直接變成模型可讀的約束信息模型生成參數(shù)時(shí)會(huì)更少越界。實(shí)測(cè)下來(lái)參數(shù)非法導(dǎo)致的重試次數(shù)下降了約 40%。2.3 技能描述怎么寫(xiě)模型才聽(tīng)得懂這是整個(gè)技能庫(kù)里最軟但也最關(guān)鍵的部分。我發(fā)現(xiàn)很多團(tuán)隊(duì)把描述寫(xiě)成一句話簡(jiǎn)介比如執(zhí)行搜索模型根本選不準(zhǔn)。我的經(jīng)驗(yàn)是描述里必須寫(xiě)清使用場(chǎng)景和不要使用的場(chǎng)景而且要給出正反例。下面是我常用的一段描述使用場(chǎng)景當(dāng)用戶需要查詢(xún)實(shí)時(shí)信息、獲取最新新聞、查找某個(gè)機(jī)構(gòu)/人物/產(chǎn)品的當(dāng)前情況時(shí)。 不要使用如果用戶只是問(wèn)概念解釋、歷史知識(shí)且不要求最新信息請(qǐng)使用 knowledge_base 技能。這段描述直接把搜索技能和知識(shí)庫(kù)技能區(qū)分開(kāi)了。模型對(duì)什么時(shí)候不要用特別敏感因?yàn)榇罅空`選都發(fā)生在兩個(gè)技能邊界模糊時(shí)。后面我還會(huì)專(zhuān)門(mén)講怎么靠邊界描述來(lái)提升技能選擇的準(zhǔn)確率。3. 注冊(cè)中心與動(dòng)態(tài)發(fā)現(xiàn)讓新建技能像插線板一樣簡(jiǎn)單3.1 基于裝飾器的注冊(cè)機(jī)制有了技能定義下一步是把它們收集到一個(gè)注冊(cè)中心里。我用的方式是在模塊加載時(shí)通過(guò)裝飾器自動(dòng)注冊(cè)。先定義全局注冊(cè)表from typing import Dict from dataclasses import dataclass, field class SkillRegistry: def __init__(self): self._skills: Dict[str, Skill] {} def register(self, skill: Skill) - Skill: if skill.name in self._skills: raise ValueError(fSkill {skill.name} already registered) self._skills[skill.name] skill return skill def get(self, name: str) - Skill: return self._skills[name] def all(self) - list[Skill]: return list(self._skills.values()) registry SkillRegistry() def skill_skill( description: str, category: str general, version: str 1.0.0, ): def wrapper(params_model: Type[BaseModel], execute: Callable): skill Skill( nameexecute.__name__, descriptiondescription, params_modelparams_model, executeexecute, categorycategory, versionversion, ) registry.register(skill) return skill return wrapper具體使用如下skill_skill( description獲取指定城市的當(dāng)前天氣適合用戶詢(xún)問(wèn)天氣、溫度、降雨概率時(shí)。, categoryutility, ) class GetWeatherParams(BaseModel): city: str Field(description城市中文名) async def get_weather(city: str) - dict: ...裝飾器把函數(shù)名作為技能名參數(shù)類(lèi)作為 Schema 定義整個(gè)流程非常輕。新加一個(gè)技能時(shí)只有模塊被 import 進(jìn)來(lái)技能就會(huì)自動(dòng)進(jìn)入注冊(cè)表主調(diào)度邏輯完全不用改。這基本就是插件架構(gòu)的低配版但已經(jīng)能很好地滿足需求。3.2 為什么不用硬編碼列表很多人會(huì)問(wèn)項(xiàng)目不大直接在列表里寫(xiě)清楚不就行了我早期也這么做過(guò)但吃了幾次虧之后決定改用注冊(cè)中心。一次是多人協(xié)作時(shí)同事加了一個(gè)技能但導(dǎo)入了模塊卻忘記在列表里追加結(jié)果模型看不到這個(gè)技能。還有一次是寫(xiě)測(cè)試時(shí)需要隔離技能集合硬編碼列表讓測(cè)試非常別扭。改用注冊(cè)中心后測(cè)試時(shí)可以輕松構(gòu)造一個(gè)臨時(shí) Registry 并注入 mock 技能再也不用擔(dān)心污染公共列表。另外自動(dòng)掃描還有利于做按需加載。大項(xiàng)目里技能可能涉及重依賴(lài)比如 PDF 解析技能要導(dǎo)入一堆庫(kù)。我可以在技能模塊里做懶加載注冊(cè)階段只存描述和 Schema執(zhí)行時(shí)才真正 import 重依賴(lài)庫(kù)。這樣應(yīng)用啟動(dòng)速度和內(nèi)存占用都更可控。3.3 技能間依賴(lài)從重復(fù)實(shí)現(xiàn)到組合調(diào)用技能庫(kù)管理工具多了以后第二個(gè)高頻需求就是技能復(fù)用。比如天氣查詢(xún)和穿衣建議兩個(gè)技能后者應(yīng)該組合前者而不是重新實(shí)現(xiàn)一遍天氣邏輯。我采用的方式是在 Skill 執(zhí)行體里可以直接拿到注冊(cè)表實(shí)例async def dressing_advice(city: str, temp: float) - str: weather_skill registry.get(get_weather) weather await weather_skill.run(citycity) ...這樣調(diào)度核心不關(guān)心技能內(nèi)部怎么組織下游技能只需要知道自己依賴(lài)哪個(gè)技能名。但我會(huì)在技能描述里顯式聲明依賴(lài)比如本技能需要依賴(lài) get_weather 獲取實(shí)時(shí)溫度這樣模型選擇組合型技能時(shí)會(huì)更清楚它背后的成本。不過(guò)這里也要提醒一句技能間調(diào)用會(huì)增加一次模型調(diào)度延遲如果可以盡量在同一個(gè)執(zhí)行函數(shù)內(nèi)并行調(diào)用多個(gè)基礎(chǔ)技能而不是串行依賴(lài)。我后面會(huì)專(zhuān)門(mén)講性能優(yōu)化。4. 讓模型知道用什么技能技能選擇提示詞的組裝策略4.1 全量技能都塞進(jìn) Prompt 是最蠢的做法一開(kāi)始我天真地把所有技能的名字、描述、參數(shù)規(guī)則全部塞進(jìn) system prompt。技能數(shù)量只有五個(gè)的時(shí)候還行到十五個(gè)以后模型的選擇準(zhǔn)確率明顯下降token 消耗也讓人肉疼。后來(lái)我統(tǒng)計(jì)了一次完整對(duì)話的平均 token 消耗系統(tǒng)提示詞里技能描述占了 60% 以上而實(shí)際單輪對(duì)話中模型通常只需要兩三個(gè)技能。也就是說(shuō)絕大部分信息是冗余的反而干擾了模型的注意力。4.2 兩級(jí)索引先選技能再補(bǔ)詳情我的解法是兩級(jí)索引策略。第一級(jí)維護(hù)一個(gè)精簡(jiǎn)的技能目錄每個(gè)技能只保留 name、一句話簡(jiǎn)介、使用場(chǎng)景、參數(shù)約束摘要。這個(gè)目錄盡量控制在模型能一屏看完的規(guī)模目標(biāo)是讓模型快速定位候選技能。第二級(jí)當(dāng)模型在回復(fù)中表示需要調(diào)用技能 X時(shí)調(diào)度器再把技能 X 的完整參數(shù) Schema、詳細(xì)描述、示例注入到下一輪上下文里讓模型嚴(yán)格按 Schema 生成參數(shù)。具體實(shí)現(xiàn)上我在 system prompt 里放這樣的模板可用技能目錄 {skills_catalog} 如果你需要完成某個(gè)操作請(qǐng)先輸出要使用的技能名稱(chēng)以及對(duì)應(yīng)的參數(shù) JSON。def build_skills_catalog(skills: list[Skill]) - str: lines [] for s in skills: lines.append( f- {s.name}: {s.description.split(使用場(chǎng)景)[0].strip()} ) return \n.join(lines) def build_skill_detail(skill: Skill) - str: return ( f技能名稱(chēng): {skill.name}\n f完整描述: {skill.description}\n f參數(shù)Schema: {json.dumps(skill.param_schema, ensure_asciiFalse, indent2)}\n f請(qǐng)嚴(yán)格按照Schema生成參數(shù)。 )調(diào)用流程簡(jiǎn)化為模型閱讀技能目錄判斷需要哪個(gè)技能。模型輸出技能名和參數(shù)摘要也可以直接輸出空參數(shù)。調(diào)度器找到技能詳情拼接到下一輪 prompt。模型輸出最終結(jié)構(gòu)化參數(shù)。調(diào)度器校驗(yàn)并執(zhí)行技能。這個(gè)流程讓模型每次只需要關(guān)注一小段信息準(zhǔn)確率提高非常明顯。代價(jià)是多了一輪交互但很多場(chǎng)景下值得。后續(xù)也可以對(duì)高頻技能做緩存根據(jù)對(duì)話主題直接預(yù)加載幾個(gè)可疑技能減少試探輪次。4.3 上下文裁剪根據(jù)對(duì)話狀態(tài)動(dòng)態(tài)過(guò)濾技能目錄除了兩級(jí)索引動(dòng)態(tài)裁剪也很關(guān)鍵。我的實(shí)現(xiàn)里維護(hù)了一個(gè)context_tags也就是從當(dāng)前對(duì)話中抽取的場(chǎng)景標(biāo)簽比如天氣新聞SQL。然后在構(gòu)建目錄時(shí)根據(jù)標(biāo)簽過(guò)濾掉明顯不相關(guān)的技能。比如用戶問(wèn)今天天氣就沒(méi)必要把數(shù)據(jù)庫(kù)備份這種運(yùn)維技能展示給模型。這個(gè)能力依賴(lài)于對(duì)用戶意圖的初步判斷不一定要很精確只要能把候選集從二十個(gè)降到五六個(gè)模型選擇的準(zhǔn)確度就能上一個(gè)臺(tái)階。我建議用一次快速的輕量分類(lèi)來(lái)打標(biāo)簽而不是讓主 Agent 又做意圖識(shí)別又做技能選擇否則每輪推理成本會(huì)高得離譜。5. 實(shí)測(cè)我把這套技術(shù)寫(xiě)作助手跑起來(lái)之后5.1 場(chǎng)景設(shè)定與技能清單為了驗(yàn)證 agent-skills 不是玩具我做了一個(gè)相對(duì)完整的示例項(xiàng)目一個(gè)技術(shù)寫(xiě)作助手。它需要完成資料搜索、網(wǎng)頁(yè)內(nèi)容摘要、代碼示例獲取、稿件素材整理、保存到 Notion 數(shù)據(jù)庫(kù)這些任務(wù)。當(dāng)時(shí)注冊(cè)的技能包括技能名用途依賴(lài)web_search搜索最新技術(shù)資料無(wú)fetch_webpage抓取網(wǎng)頁(yè)正文并轉(zhuǎn)成純文本無(wú)extract_code從網(wǎng)頁(yè)正文中提取代碼塊fetch_webpagegenerate_summary調(diào)用大模型對(duì)文本生成摘要無(wú)save_to_notion將整理好的內(nèi)容保存到數(shù)據(jù)庫(kù)無(wú)5.2 效果對(duì)比技能選擇準(zhǔn)確率從 68% 提到 94%我準(zhǔn)備了一百條真實(shí)用戶問(wèn)句作為測(cè)試集覆蓋搜索、摘要、保存、組合任務(wù)等類(lèi)型。在沒(méi)做技能庫(kù)管理、所有工具硬編碼、描述也很簡(jiǎn)陋的情況下模型正確選擇技能的比例只有 68%也就是三成的情況下選出了錯(cuò)誤的工具。經(jīng)過(guò)技能結(jié)構(gòu)標(biāo)準(zhǔn)化、兩級(jí)索引、動(dòng)態(tài)裁剪和描述優(yōu)化之后同樣的一百條樣本技能選擇準(zhǔn)確率提升到了 94%。誤選主要發(fā)生在fetch_webpage和extract_code之間的調(diào)用順序上后來(lái)靠強(qiáng)化示例才壓下去。token 消耗方面也有明顯改善。沒(méi)優(yōu)化前每輪對(duì)話平均在系統(tǒng)提示詞上花費(fèi)約 1800 token優(yōu)化后因?yàn)橹蛔⑷肽夸浐捅匾募寄茉斍槠骄档?700 token 左右整體對(duì)話成本下降了約 60%。當(dāng)然這個(gè)數(shù)據(jù)跟具體技能數(shù)量和模型上下文能力有關(guān)系但方向是通用的。5.3 一個(gè)讓我意外的發(fā)現(xiàn)技能執(zhí)行結(jié)果也需要結(jié)構(gòu)化回填做到一半我發(fā)現(xiàn)技能執(zhí)行完返回的數(shù)據(jù)不能原樣丟給模型。直接返回一長(zhǎng)串網(wǎng)頁(yè)全文不僅浪費(fèi) token而且模型難以提取重點(diǎn)。后來(lái)我給技能加了一層format_result讓每個(gè)技能返回結(jié)構(gòu)化且精煉的結(jié)果摘要。比如搜索技能返回的不是完整結(jié)果列表而是每個(gè)結(jié)果的標(biāo)題、URL、時(shí)間、一句話摘要。這個(gè)改動(dòng)讓后續(xù)對(duì)話的上下文變得更干凈模型在引用資料時(shí)也更準(zhǔn)確。我建議給每個(gè)技能準(zhǔn)備一個(gè)result_summary方法或者至少對(duì)返回內(nèi)容做一個(gè) token 上限截?cái)?。這比在主提示詞里寫(xiě)請(qǐng)忽略無(wú)關(guān)內(nèi)容有效得多。6. 最容易翻車(chē)的三個(gè)細(xì)節(jié)與我的完整排查鏈路6.1 現(xiàn)象模型總把參數(shù)類(lèi)型搞錯(cuò)第一次上線時(shí)模型調(diào)用web_search時(shí)把max_results傳成了字符串 5。Pydantic 其實(shí)會(huì)自動(dòng)做類(lèi)型轉(zhuǎn)換但如果是字符串 abc 就會(huì)直接報(bào)錯(cuò)。本來(lái)我以為校驗(yàn)失敗會(huì)讓模型自己重試但發(fā)現(xiàn)模型報(bào)錯(cuò)后經(jīng)常不知道該改成什么。排查鏈路我先在日志里打印每次技能執(zhí)行的validated參數(shù)確認(rèn)錯(cuò)誤來(lái)源是類(lèi)型強(qiáng)制轉(zhuǎn)換失敗。然后檢查 Pydantic 的model_config發(fā)現(xiàn)沒(méi)有禁止字符串強(qiáng)轉(zhuǎn)成數(shù)字。調(diào)整參數(shù)模型增加strictTrue讓多余的類(lèi)型強(qiáng)迫轉(zhuǎn)換直接失敗反而讓模型更容易理解錯(cuò)誤信息。再給校驗(yàn)錯(cuò)誤設(shè)計(jì)了一條清晰的錯(cuò)誤提示包括出錯(cuò)字段、期望類(lèi)型、傳入值要求模型重新生成參數(shù)。這個(gè)鏈路最值得夸的一點(diǎn)是Pydantic 的嚴(yán)格模式一開(kāi)始就要開(kāi)。如果不嚴(yán)格很多隱性類(lèi)型問(wèn)題會(huì)在技能執(zhí)行階段才炸出來(lái)而且定位成本更高。6.2 現(xiàn)象兩個(gè)技能描述太像模型反復(fù)選錯(cuò)有一次模型在查天氣和查空氣質(zhì)量之間反復(fù)橫跳幾乎沒(méi)什么規(guī)律。我把兩個(gè)技能的完整描述拿出來(lái)逐字對(duì)比發(fā)現(xiàn)都寫(xiě)著用于查詢(xún)城市的當(dāng)前環(huán)境信息。這顯然不行。排查鏈路我寫(xiě)了一個(gè)小腳本對(duì)所有技能描述做兩兩相似度計(jì)算用簡(jiǎn)單的關(guān)鍵詞重疊度發(fā)現(xiàn)get_weather和get_air_quality的相似度最高。為每個(gè)技能重寫(xiě)了描述補(bǔ)充明確的邊界場(chǎng)景。比如空氣質(zhì)量技能必須提到AQI、PM2.5、污染天氣技能必須提到溫度、濕度、降雨。在測(cè)試集上加了兩條容易混淆的用例比如今天出門(mén)要不要戴口罩應(yīng)該選空氣質(zhì)量今天會(huì)不會(huì)下雨應(yīng)該選天氣。之后我把技能描述相似度檢查加入了 CI。每次提交代碼時(shí)自動(dòng)跑一遍如果發(fā)現(xiàn)兩個(gè)技能描述相似度過(guò)高就報(bào)警提示人工review。這個(gè)工具對(duì)團(tuán)隊(duì)協(xié)作特別有用。6.3 現(xiàn)象上下文里技能太多模型瞎選有段時(shí)間我的技能數(shù)量增加到二十多個(gè)即便做了目錄精簡(jiǎn)模型還是時(shí)不時(shí)選出一個(gè)跟當(dāng)前話題八竿子打不著的技能。排查鏈路我記錄了模型每次選擇的 log發(fā)現(xiàn)誤選大多發(fā)生在對(duì)話較長(zhǎng)的中后段。進(jìn)一步檢查發(fā)現(xiàn)前置對(duì)話把模型注意力帶偏了尤其是之前提到過(guò)某個(gè)技能模型容易慣性選擇。于是在構(gòu)建新一輪技能目錄時(shí)我顯式把當(dāng)前用戶問(wèn)題放在目錄之前讓模型先明確問(wèn)題再看技能。另外把技能目錄按類(lèi)別折疊默認(rèn)只展示用戶當(dāng)前場(chǎng)景可能相關(guān)的類(lèi)別收起無(wú)關(guān)類(lèi)別。改完以后長(zhǎng)對(duì)話中的誤選率明顯下降。這說(shuō)明技能選擇不是純靠模型理解能力輸入的結(jié)構(gòu)化程度對(duì)結(jié)果影響很大。7. 技能治理版本、評(píng)估與淘汰機(jī)制技能庫(kù)不是一勞永逸的。加了新技能可能擠壓舊技能的選擇空間改了一個(gè)技能的描述可能影響其他技能的邊界。我后來(lái)慢慢把這套東西當(dāng)成一個(gè)需要治理的代碼庫(kù)來(lái)對(duì)待。7.1 每個(gè)技能都要有版本和負(fù)責(zé)人我在 Skill 結(jié)構(gòu)里增加了author和version字段。雖然聽(tīng)起來(lái)不重要但在多人協(xié)作時(shí)版本標(biāo)簽?zāi)茏屓罩纠锏恼{(diào)用記錄對(duì)應(yīng)到一個(gè)明確的代碼版本。線上出問(wèn)題后git blame加version能快速定位是誰(shuí)改過(guò)、什么時(shí)候改的。7.2 建立技能選擇回歸集我強(qiáng)烈建議項(xiàng)目里至少準(zhǔn)備 50 到 100 條標(biāo)注好的意圖 - 技能 - 參數(shù)測(cè)試用例。每次修改技能定義后跑一遍回歸集統(tǒng)計(jì)技能選擇準(zhǔn)確率和參數(shù)生成準(zhǔn)確率。再進(jìn)一步可以給每個(gè)技能單獨(dú)維護(hù)一條技能熱度和技能錯(cuò)誤率。如果一個(gè)技能連續(xù)半個(gè)月沒(méi)被調(diào)用或者調(diào)用后頻頻報(bào)錯(cuò)就該考慮下線或重寫(xiě)描述。我用一張簡(jiǎn)單的表來(lái)跟蹤技能名調(diào)用次數(shù)成功率平均耗時(shí)最后調(diào)用時(shí)間web_search32092%1.2s2025-01-10extract_code2578%3.1s2025-01-08定期看這張表你能發(fā)現(xiàn)很多之前沒(méi)注意的問(wèn)題。比如extract_code調(diào)用次數(shù)少但成功率低說(shuō)明描述可能太窄或者依賴(lài)的fetch_webpage返回內(nèi)容不理想。這種數(shù)據(jù)驅(qū)動(dòng)的迭代比憑感覺(jué)改 prompt 高效得多。7.3 技能描述也要做 A/B 測(cè)試最后分享一個(gè)偏門(mén)但有效的經(jīng)驗(yàn)對(duì)高爭(zhēng)議的技能描述做 A/B 測(cè)試。同一時(shí)間讓一半流量看到描述 A一半看到描述 B統(tǒng)計(jì)技能選擇的準(zhǔn)確率、任務(wù)完成率。我自己測(cè)試過(guò)web_search描述里加不加不要使用約束結(jié)果加了之后誤選率下降了 12%。看似一句話的差別在幾十個(gè)技能并存時(shí)影響會(huì)被放大。如果你沒(méi)有完整 A/B 平臺(tái)至少可以在本地跑一個(gè)小樣本對(duì)比把兩個(gè)描述各跑二十條測(cè)試用例看看哪個(gè)更穩(wěn)。說(shuō)實(shí)話做到這一步agent-skills 已經(jīng)不再是一個(gè)簡(jiǎn)單的工具管理腳本而是一套關(guān)于如何讓模型可靠地使用工具的方法論。它的價(jià)值不在于某個(gè)具體的技能實(shí)現(xiàn)而在于你能把每個(gè)能力變化都變成可測(cè)試、可回滾、可觀測(cè)的過(guò)程。對(duì)我個(gè)人而言這套機(jī)制最直接的好處是我再也不怕業(yè)務(wù)方突然提再加一個(gè)技能的需求了——無(wú)非是寫(xiě)一個(gè)函數(shù)、配一個(gè)描述、跑一遍回歸集的事。