1. 為什么你的 Agent 技能總是“一次性”的很多人搭智能體時(shí)都遇到過這個(gè)場(chǎng)景寫了一個(gè)能查天氣、能讀文件、能調(diào)接口的 Agent跑通一次挺開心但換個(gè)任務(wù)就得重寫一遍。技能和業(yè)務(wù)邏輯攪在一起參數(shù)校驗(yàn)散落在各個(gè)函數(shù)里調(diào)度全靠 if-else 硬編碼。結(jié)果就是——技能不可復(fù)用Agent 越寫越臃腫。這篇要解決的就是這個(gè)問題給智能體搭一棵可插拔的技能樹。核心思路是把技能從 Agent 主邏輯里抽出來做成獨(dú)立的注冊(cè)表讓技能發(fā)現(xiàn)、參數(shù)校驗(yàn)、調(diào)度執(zhí)行三層解耦。你可以把它理解成給 Agent 裝了一個(gè)“應(yīng)用商店”技能按統(tǒng)一格式注冊(cè)進(jìn)來Agent 運(yùn)行時(shí)按需查找、校驗(yàn)、調(diào)用用完即走。適合誰看如果你正在做多 Agent 協(xié)作、想讓技能跨項(xiàng)目復(fù)用或者單純覺得現(xiàn)在的 Agent 代碼太亂想重構(gòu)這篇的配置和腳本可以直接抄。我會(huì)用兩個(gè)示例技能一個(gè)查匯率、一個(gè)算文本統(tǒng)計(jì)走完整流程注冊(cè) → 發(fā)現(xiàn) → 校驗(yàn) → 調(diào)度 → 驗(yàn)證返回。全程本地可跑不依賴任何外部服務(wù)最后再講怎么把調(diào)用憑證統(tǒng)一管起來。先明確一個(gè)概念邊界。Skills 和 Tools 不是一回事Tools 是原子能力讀文件、發(fā)請(qǐng)求Skills 是編排好的工作流先校驗(yàn)參數(shù)、再調(diào)工具、最后格式化輸出。我們要搭的注冊(cè)與調(diào)度層管的是 Skills 這一層。MCP 負(fù)責(zé)數(shù)據(jù)接入Subagents 負(fù)責(zé)并行隔離這些是上下游本篇聚焦中間那層“技能怎么管”。2. TaoToken 前置把調(diào)用憑證從技能里剝出來技能樹要可復(fù)用有個(gè)前提容易被忽略技能本身不能綁死某一家模型的 Key。如果每個(gè)技能里都硬編碼一個(gè) API Key那技能就沒法跨環(huán)境遷移也沒法集中輪換憑證。所以第一步是把模型調(diào)用通道統(tǒng)一出去。我用的方案是 TaoToken它提供一個(gè)統(tǒng)一的 Key/API 通道兼容 OpenAI 風(fēng)格的接口格式。好處是技能注冊(cè)表里只存“模型標(biāo)識(shí)”不存憑證真正調(diào)用時(shí)由調(diào)度層統(tǒng)一注入 Base URL 和 Key。這樣技能文件可以進(jìn) Git憑證留在環(huán)境變量里。你需要準(zhǔn)備三樣?xùn)|西我列成表格方便對(duì)照項(xiàng)目值說明Base URLhttps://taotoken.net/api統(tǒng)一入口不加任何多余路徑API Key在控制臺(tái)生成形如sk-開頭只存環(huán)境變量Model ID按需選擇調(diào)度層配置里引用技能文件不寫死獲取 Key 的入口在控制臺(tái)的 API Keys 頁面生成后復(fù)制一次即可頁面刷新后不再完整顯示。如果你還沒賬號(hào)從官網(wǎng)進(jìn)https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注冊(cè)后在控制臺(tái)左側(cè)找到 API Keys。這里有個(gè)工程習(xí)慣值得養(yǎng)成把憑證讀取封裝成一個(gè)函數(shù)所有技能調(diào)度都走它。這樣以后換通道、加限流、做審計(jì)只改一處。下面是我用的最小封裝放在config/llm_client.pyimport os from openai import OpenAI def get_client(): base_url os.environ.get(TAOTOKEN_BASE_URL, https://taotoken.net/api) api_key os.environ.get(TAOTOKEN_API_KEY) if not api_key: raise RuntimeError(TAOTOKEN_API_KEY 未設(shè)置請(qǐng)先導(dǎo)出環(huán)境變量) return OpenAI(base_urlbase_url, api_keyapi_key) DEFAULT_MODEL os.environ.get(TAOTOKEN_MODEL, gpt-4o-mini)環(huán)境變量這樣導(dǎo)出Linux/macOSexport TAOTOKEN_BASE_URLhttps://taotoken.net/api export TAOTOKEN_API_KEYsk-你的key export TAOTOKEN_MODELgpt-4o-miniWindows PowerShell 用$env:TAOTOKEN_API_KEYsk-...。注意 Base URL 結(jié)尾不要帶/v1SDK 會(huì)自己拼多寫一層會(huì) 404。這一步做完技能樹就有了統(tǒng)一的“電源接口”后面所有技能都從這里取電。3. 可復(fù)制的技能注冊(cè)表與調(diào)度腳本現(xiàn)在進(jìn)入核心部分。技能樹要落地得先定義技能的“身份證”格式。我用 JSON 存注冊(cè)表每個(gè)技能一條記錄包含名稱、描述、參數(shù) schema、執(zhí)行入口。這樣調(diào)度層可以只讀注冊(cè)表就知道有哪些技能、怎么校驗(yàn)參數(shù)不用 import 具體實(shí)現(xiàn)。先建目錄結(jié)構(gòu)agent_skills/ ├── registry/ │ └── skills.json ├── skills/ │ ├── currency_convert.py │ └── text_stats.py ├── config/ │ └── llm_client.py └── dispatcher.py注冊(cè)表registry/skills.json內(nèi)容如下兩個(gè)示例技能都注冊(cè)進(jìn)去{ version: 1.0, skills: [ { name: currency_convert, description: 把一種貨幣金額換算成另一種貨幣使用固定匯率表, entry: skills.currency_convert:run, parameters: { type: object, properties: { amount: { type: number, minimum: 0 }, from_currency: { type: string, enum: [CNY, USD, EUR] }, to_currency: { type: string, enum: [CNY, USD, EUR] } }, required: [amount, from_currency, to_currency] } }, { name: text_stats, description: 統(tǒng)計(jì)一段文本的字符數(shù)、詞數(shù)和行數(shù), entry: skills.text_stats:run, parameters: { type: object, properties: { text: { type: string, minLength: 1 } }, required: [text] } } ] }注意entry字段用的是模塊路徑:函數(shù)名格式調(diào)度層用importlib動(dòng)態(tài)加載。這樣加新技能只需改 JSON不用動(dòng)調(diào)度代碼——這就是“可插拔”的關(guān)鍵。兩個(gè)技能實(shí)現(xiàn)skills/currency_convert.pyRATES { (CNY, USD): 0.14, (USD, CNY): 7.15, (CNY, EUR): 0.13, (EUR, CNY): 7.70, (USD, EUR): 0.92, (EUR, USD): 1.09, } def run(amount, from_currency, to_currency): if from_currency to_currency: return {result: amount, rate: 1.0} rate RATES.get((from_currency, to_currency)) if rate is None: raise ValueError(f不支持的貨幣對(duì): {from_currency}-{to_currency}) return {result: round(amount * rate, 2), rate: rate}skills/text_stats.pydef run(text): lines text.splitlines() words text.split() return { chars: len(text), words: len(words), lines: len(lines), }調(diào)度層dispatcher.py負(fù)責(zé)三件事加載注冊(cè)表、用 JSON Schema 校驗(yàn)參數(shù)、動(dòng)態(tài)調(diào)用。校驗(yàn)用jsonschema庫沒裝的話pip install jsonschemaimport json import importlib from pathlib import Path from jsonschema import validate, ValidationError REGISTRY_PATH Path(__file__).parent / registry / skills.json class SkillDispatcher: def __init__(self): self.registry {} self._load() def _load(self): data json.loads(REGISTRY_PATH.read_text(encodingutf-8)) for item in data[skills]: self.registry[item[name]] item def list_skills(self): return [ {name: k, description: v[description]} for k, v in self.registry.items() ] def call(self, name, params): if name not in self.registry: raise KeyError(f技能未注冊(cè): {name}) meta self.registry[name] try: validate(instanceparams, schemameta[parameters]) except ValidationError as e: raise ValueError(f參數(shù)校驗(yàn)失敗: {e.message}) module_path, func_name meta[entry].split(:) module importlib.import_module(module_path) func getattr(module, func_name) return func(**params)這段代碼里list_skills就是“技能發(fā)現(xiàn)”接口call就是“校驗(yàn) 調(diào)度”。技能發(fā)現(xiàn)和調(diào)度徹底解耦A(yù)gent 主邏輯只需要拿到技能列表決定調(diào)哪個(gè)剩下的交給 dispatcher。4. 驗(yàn)證請(qǐng)求注冊(cè)兩個(gè)技能后觸發(fā)調(diào)用配置寫完得驗(yàn)證路由和返回是否符合預(yù)期。我寫了個(gè)驗(yàn)證腳本verify.py依次做四件事列出技能、正常調(diào)用、故意傳錯(cuò)參數(shù)、調(diào)用不存在的技能。from dispatcher import SkillDispatcher d SkillDispatcher() print( 1. 技能發(fā)現(xiàn) ) for s in d.list_skills(): print(f- {s[name]}: {s[description]}) print(\n 2. 正常調(diào)用 currency_convert ) print(d.call(currency_convert, { amount: 100, from_currency: CNY, to_currency: USD })) print(\n 3. 正常調(diào)用 text_stats ) print(d.call(text_stats, {text: hello agent skills\nsecond line})) print(\n 4. 參數(shù)校驗(yàn)金額為負(fù)) try: d.call(currency_convert, { amount: -5, from_currency: CNY, to_currency: USD }) except ValueError as e: print(已攔截:, e) print(\n 5. 未注冊(cè)技能 ) try: d.call(not_exist, {}) except KeyError as e: print(已攔截:, e)跑python verify.py預(yù)期輸出 1. 技能發(fā)現(xiàn) - currency_convert: 把一種貨幣金額換算成另一種貨幣使用固定匯率表 - text_stats: 統(tǒng)計(jì)一段文本的字符數(shù)、詞數(shù)和行數(shù) 2. 正常調(diào)用 currency_convert {result: 14.0, rate: 0.14} 3. 正常調(diào)用 text_stats {chars: 30, words: 5, lines: 2} 4. 參數(shù)校驗(yàn)金額為負(fù) 已攔截: 參數(shù)校驗(yàn)失敗: -5 is less than the minimum of 0 5. 未注冊(cè)技能 已攔截: 技能未注冊(cè): not_exist看到這個(gè)輸出說明路由正確、校驗(yàn)生效、異?？煽?。第 2 步返回14.0是 100 CNY 按 0.14 匯率換算的結(jié)果第 3 步chars是 30含換行符words是 5都對(duì)得上。如果你想讓 Agent 自己決定調(diào)哪個(gè)技能可以把list_skills()的結(jié)果塞進(jìn)模型上下文讓模型輸出技能名和參數(shù)再交給 dispatcher。這一步的模型調(diào)用就走第 2 章封裝的 clientfrom config.llm_client import get_client, DEFAULT_MODEL client get_client() resp client.chat.completions.create( modelDEFAULT_MODEL, messages[ {role: system, content: 你是技能路由器根據(jù)用戶請(qǐng)求輸出技能名和JSON參數(shù)。}, {role: user, content: 幫我把 200 美元換成人民幣} ] ) print(resp.choices[0].message.content)這一步能跑通說明“模型決策 本地調(diào)度”的鏈路是通的。模型只負(fù)責(zé)選技能和填參數(shù)真正的執(zhí)行和校驗(yàn)在本地安全邊界清晰。5. 本篇常見錯(cuò)排查401、校驗(yàn)失敗與路由異常技能樹搭起來后報(bào)錯(cuò)基本集中在四類。我把真實(shí)遇到的錯(cuò)誤和定位方法列出來你對(duì)照著查。第一類401 Unauthorized / invalid api key。這個(gè)幾乎都是憑證問題。先確認(rèn)TAOTOKEN_API_KEY真的導(dǎo)出了用echo $TAOTOKEN_API_KEY看有沒有值。如果值對(duì)但還報(bào) 401檢查 Base URL 是不是寫成了https://taotoken.net/api/v1——多一層/v1會(huì)導(dǎo)致路徑拼接錯(cuò)誤。正確寫法就是https://taotoken.net/api。還有一種情況是 Key 復(fù)制時(shí)帶了空格或換行重新生成一次最省事。第二類參數(shù)校驗(yàn)失敗報(bào)is not of type number或is not one of。這是 JSON Schema 在起作用不是 bug。常見原因是模型返回的參數(shù)類型不對(duì)比如把a(bǔ)mount輸出成字符串100。解決辦法是在調(diào)度層加一層輕量轉(zhuǎn)換或者在 system prompt 里明確要求“數(shù)值字段輸出數(shù)字類型”。enum報(bào)錯(cuò)則是貨幣代碼不在允許列表里檢查注冊(cè)表的enum是否覆蓋了實(shí)際用到的值。第三類ModuleNotFoundError: No module named skills。動(dòng)態(tài)加載時(shí)模塊路徑找不到。確認(rèn)dispatcher.py和skills/目錄在同一級(jí)且skills/下有__init__.py空文件即可。如果是從其他目錄運(yùn)行腳本importlib的搜索路徑可能不對(duì)在dispatcher.py頂部加一句把項(xiàng)目根目錄塞進(jìn)sys.pathimport sys from pathlib import Path sys.path.insert(0, str(Path(__file__).parent))第四類reading choices相關(guān)報(bào)錯(cuò)比如KeyError: choices或返回體里沒有 choices。這通常說明請(qǐng)求根本沒到模型或者返回的是錯(cuò)誤結(jié)構(gòu)。先打印完整響應(yīng)體看error字段。如果是local proxy failed這類提示說明網(wǎng)絡(luò)層有問題檢查 Base URL 是否可達(dá)。如果響應(yīng)正常但結(jié)構(gòu)不對(duì)確認(rèn) SDK 版本和接口格式匹配——TaoToken 兼容 OpenAI 格式用官方openaiSDK 即可。排查順序建議固定成先看憑證401→ 再看參數(shù)校驗(yàn)→ 再看模塊路徑import→ 最后看響應(yīng)結(jié)構(gòu)choices。按這個(gè)順序走九成問題五分鐘內(nèi)能定位。6. 把技能樹接上統(tǒng)一通道下一步做并行調(diào)度到這里一棵最小可用的技能樹就跑起來了注冊(cè)表管技能元數(shù)據(jù)dispatcher 管發(fā)現(xiàn)和校驗(yàn)技能實(shí)現(xiàn)只管業(yè)務(wù)邏輯憑證統(tǒng)一走 TaoToken 通道。這套結(jié)構(gòu)的好處是加第三個(gè)、第十個(gè)技能時(shí)你只需要往skills.json里追加一條記錄再寫一個(gè)純函數(shù)調(diào)度層一行都不用改。如果你要把這套東西用到實(shí)際項(xiàng)目里有兩個(gè)方向可以繼續(xù)。一是把list_skills()的輸出做成工具描述喂給模型讓模型自主路由這就是“模型決策 本地執(zhí)行”的 Agent 形態(tài)。二是把 dispatcher 的call改成異步配合 Subagents 做并行調(diào)用——多個(gè)互不依賴的技能同時(shí)跑主線程只收結(jié)果上下文不被污染。憑證這塊建議你盡早把 Key 從代碼里徹底剝離。我現(xiàn)在的做法是本地用環(huán)境變量CI 里用 secrets所有模型調(diào)用都走config/llm_client.py一個(gè)出口。這樣以后要換通道、加限流、做用量統(tǒng)計(jì)改一個(gè)文件就夠了。需要生成新 Key 或者查看用量從控制臺(tái)的 API Keys 進(jìn)想先試試模型對(duì)話效果可以從模型對(duì)話頁面直接測(cè)如果打算長(zhǎng)期跑編碼類 AgentCoding Plan 的額度更劃算。接入細(xì)節(jié)看文檔里面有各語言的示例。下一篇會(huì)講技能樹的第二層怎么讓多個(gè) Agent 共享同一棵技能樹以及技能版本管理和灰度發(fā)布。那部分會(huì)涉及注冊(cè)表的版本字段和調(diào)度層的路由策略感興趣可以先把手頭這版跑通把兩個(gè)示例技能換成你自己的業(yè)務(wù)邏輯試試。