1. 從“只會(huì)聊天”到“真能干活”Agent Skill 到底解決了什么問(wèn)題你可能遇到過(guò)這種場(chǎng)景問(wèn)模型“幫我查一下北京現(xiàn)在的天氣”它回你一句“我無(wú)法獲取實(shí)時(shí)信息”。不是模型不聰明而是它天生只能“動(dòng)口”不能“動(dòng)手”。Agent Skill 就是給模型裝上手腳的那層封裝——把查天氣、讀文件、發(fā)請(qǐng)求、寫數(shù)據(jù)庫(kù)這些具體動(dòng)作打包成模型能看懂、能調(diào)用的標(biāo)準(zhǔn)化模塊。一句話定義Agent Skill 是把一項(xiàng)具體能力封裝成帶名稱、描述、參數(shù) Schema 和執(zhí)行函數(shù)的模塊讓 Agent 在需要時(shí)自動(dòng)調(diào)用。它在不同框架里叫法不同OpenAI 體系里叫 Function Calling 的 functionLangChain 里叫 ToolMCP 里叫 ToolCoze 里叫插件本質(zhì)是一回事。適合誰(shuí)看已經(jīng)會(huì)用 Python 調(diào)模型接口、想讓自己的 Agent 從“陪聊”升級(jí)到“辦事”的開(kāi)發(fā)者正在選型 Function Calling 還是 MCP 的工程同學(xué)以及想搞明白 Skill 和 MCP 到底啥關(guān)系的技術(shù)負(fù)責(zé)人。我試過(guò)把一個(gè)“查匯率”的 Skill 塞進(jìn)客服 Agent原本需要人工轉(zhuǎn)接的匯率咨詢直接由模型調(diào)接口返回響應(yīng)從分鐘級(jí)降到秒級(jí)。關(guān)鍵不在于代碼多復(fù)雜而在于把“什么時(shí)候調(diào)、傳什么參數(shù)、返回什么”這三件事描述清楚。這篇會(huì)帶你走完整條鏈路先講清 Skill 的運(yùn)行原理Function Calling 循環(huán)再用 Python 手寫一個(gè)可復(fù)用的 Skill 骨架接著把它注冊(cè)成 MCP 工具最后通過(guò) TaoToken 統(tǒng)一 Key 通道完成一次端到端調(diào)用驗(yàn)證。全程可復(fù)制跑通為止。需要提前說(shuō)明的是Skill 的開(kāi)發(fā)核心不是寫多花哨的函數(shù)而是寫好那段給模型看的 JSON Schema 描述。描述寫得準(zhǔn)模型選對(duì) Skill 的概率就高描述含糊模型要么不調(diào)要么傳錯(cuò)參數(shù)。這是后面所有實(shí)戰(zhàn)的地基。2. TaoToken 統(tǒng)一 Key 接入為什么 Agent 項(xiàng)目需要一個(gè)穩(wěn)定通道做 Agent 開(kāi)發(fā)的人很快會(huì)撞上一個(gè)現(xiàn)實(shí)問(wèn)題Skill 要調(diào)模型模型接口要 Key而不同模型、不同環(huán)境、不同同事之間的 Key 管理一團(tuán)亂。本地調(diào)試用一個(gè) Key測(cè)試環(huán)境換一個(gè)上線再換一個(gè)代碼里硬編碼的 Base URL 改來(lái)改去稍不注意就把測(cè)試 Key 提交進(jìn)了倉(cāng)庫(kù)。TaoToken 在這里扮演的角色是統(tǒng)一入口一個(gè) Key、一個(gè) Base URL兼容 OpenAI 風(fēng)格的接口協(xié)議。你的 Agent 代碼里OpenAI(api_key..., base_url...)這兩行配置一次寫好后面換模型、換環(huán)境只需要改 Model ID不用動(dòng)調(diào)用邏輯。對(duì) Skill 開(kāi)發(fā)來(lái)說(shuō)這意味著你可以把精力放在 Skill 本身的描述和執(zhí)行函數(shù)上而不是反復(fù)折騰接入層。它的接口地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions路徑。也就是說(shuō)你原來(lái)用openai這個(gè) Python 包寫的代碼只需要把base_url指過(guò)來(lái)其余client.chat.completions.create(...)的寫法完全不變。這對(duì)已經(jīng)寫過(guò) Function Calling 代碼的人來(lái)說(shuō)遷移成本幾乎為零。為什么 Agent 場(chǎng)景特別需要這種統(tǒng)一通道因?yàn)?Agent 的運(yùn)行循環(huán)里一次用戶請(qǐng)求可能觸發(fā)多輪模型調(diào)用第一輪模型決定調(diào)哪個(gè) Skill執(zhí)行完 Skill 后把結(jié)果送回模型模型再?zèng)Q定是繼續(xù)調(diào)下一個(gè) Skill 還是生成最終回復(fù)。這個(gè)循環(huán)里每一次模型調(diào)用都要走同一個(gè)通道如果通道不穩(wěn)定或者 Key 頻繁失效整個(gè) Agent 就卡住了。統(tǒng)一 Key 的價(jià)值在于讓這個(gè)循環(huán)的每一環(huán)都指向同一個(gè)可靠入口。另外Skill 開(kāi)發(fā)階段經(jīng)常需要對(duì)比不同模型對(duì)同一段 Schema 描述的理解能力。有的模型對(duì)參數(shù)類型判斷更準(zhǔn)有的模型在長(zhǎng)上下文里更穩(wěn)。用統(tǒng)一通道的好處是切換模型只改一個(gè)字符串你可以快速做 A/B 對(duì)比找出最適合你 Skill 集合的那個(gè) Model ID。配置上你只需要準(zhǔn)備三樣?xùn)|西Base URL 填https://taotoken.net/apiAPI Key 從控制臺(tái)生成Model ID 按你實(shí)際要用的模型填。這三件套在后面的 JSON 配置和 Python 代碼里會(huì)反復(fù)出現(xiàn)先記牢?？刂婆_(tái)入口在https://taotoken.net/consoleAPI Key 管理在https://taotoken.net/api-keys接入文檔在https://taotoken.net/doc需要的話可以對(duì)照著看。3. 可復(fù)制配置Skill 骨架 MCP 注冊(cè) TaoToken 三件套這一節(jié)直接給可復(fù)制的代碼和配置。先看 TaoToken 的三件套怎么落到配置文件里再寫 Skill 骨架最后把它注冊(cè)成 MCP 工具。先建一個(gè)config.json把接入信息集中管理避免硬編碼散落各處{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密鑰, model_id: gpt-4o-mini, timeout: 30 }注意base_url只寫到/api不要自己拼/v1SDK 會(huì)按 OpenAI 規(guī)范補(bǔ)全路徑。model_id按你控制臺(tái)里實(shí)際可用的模型填這里用gpt-4o-mini舉例。接著寫 Skill 骨架。一個(gè) Skill 由三部分組成名稱與描述、參數(shù) Schema、執(zhí)行函數(shù)。下面這個(gè)get_weather是完整可跑的示例import json import requests from openai import OpenAI with open(config.json, r, encodingutf-8) as f: cfg json.load(f) client OpenAI( api_keycfg[api_key], base_urlcfg[base_url], timeoutcfg[timeout], ) def get_weather(city: str) - str: 查詢指定城市的實(shí)時(shí)天氣返回溫度和天氣狀況。 url https://api.open-meteo.com/v1/forecast params { latitude: 39.9042, longitude: 116.4074, current_weather: True, } try: resp requests.get(url, paramsparams, timeout10) data resp.json() temp data[current_weather][temperature] wind data[current_weather][windspeed] return f{city} 當(dāng)前溫度 {temp}°C風(fēng)速 {wind} km/h except Exception as e: return f查詢天氣失敗{str(e)} weather_tool { type: function, function: { name: get_weather, description: 獲取指定城市的實(shí)時(shí)天氣。當(dāng)用戶詢問(wèn)某地天氣、溫度、是否下雨時(shí)使用。, parameters: { type: object, properties: { city: { type: string, description: 城市名稱例如 Beijing、Shanghai, } }, required: [city], }, }, } available_functions {get_weather: get_weather}這段代碼里最關(guān)鍵的是description字段。它直接決定模型什么時(shí)候會(huì)選這個(gè) Skill。寫法上要包含“做什么”和“什么時(shí)候用”比如“當(dāng)用戶詢問(wèn)某地天氣時(shí)使用”這樣模型在收到“北京熱不熱”這種口語(yǔ)化輸入時(shí)也能正確匹配。如果你要把這個(gè) Skill 注冊(cè)成 MCP 工具讓支持 MCP 的客戶端也能發(fā)現(xiàn)它可以用mcp這個(gè) Python 包寫一個(gè)最小服務(wù)器。先裝依賴pip install mcp openai requests然后寫weather_server.pyfrom mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent import asyncio import requests app Server(weather-skill) app.list_tools() async def list_tools(): return [ Tool( nameget_weather, description獲取指定城市的實(shí)時(shí)天氣。當(dāng)用戶詢問(wèn)某地天氣時(shí)使用。, inputSchema{ type: object, properties: { city: {type: string, description: 城市名稱} }, required: [city], }, ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name get_weather: city arguments.get(city, Beijing) url https://api.open-meteo.com/v1/forecast params {latitude: 39.9042, longitude: 116.4074, current_weather: True} resp requests.get(url, paramsparams, timeout10) data resp.json() temp data[current_weather][temperature] return [TextContent(typetext, textf{city} 當(dāng)前溫度 {temp}°C)] raise ValueError(f未知工具{name}) async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ __main__: asyncio.run(main())這個(gè) MCP 服務(wù)器通過(guò) stdio 暴露get_weather工具任何支持 MCP 的客戶端連上后都能自動(dòng)發(fā)現(xiàn)它。注意inputSchema的結(jié)構(gòu)和前面 Function Calling 的parameters完全一致這就是 Skill 描述在不同協(xié)議間的可遷移性。如果你用的是 Claude Code 這類支持 MCP 的編碼工具可以在它的配置里掛載這個(gè)服務(wù)器。以 Claude Code 的 MCP 配置為例在項(xiàng)目根目錄的.mcp.json里寫{ mcpServers: { weather-skill: { command: python, args: [weather_server.py], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的TaoToken密鑰 } } } }這里把 TaoToken 的 Base URL 和 Key 通過(guò)環(huán)境變量傳給 MCP 服務(wù)器服務(wù)器內(nèi)部如果要調(diào)模型讀這兩個(gè)變量即可。三件套Base URL、Key、Model ID在 MCP 場(chǎng)景下同樣適用只是傳遞方式從 JSON 配置變成了環(huán)境變量。4. 端到端驗(yàn)證一次請(qǐng)求跑通 Skill 調(diào)用循環(huán)配置寫完現(xiàn)在跑一次完整驗(yàn)證。目標(biāo)是用戶輸入一句自然語(yǔ)言模型自動(dòng)決定調(diào)用get_weather執(zhí)行函數(shù)拿到結(jié)果模型再生成最終回復(fù)。先寫運(yùn)行循環(huán)def run_agent(user_message: str, tools: list, functions: dict) - str: messages [{role: user, content: user_message}] response client.chat.completions.create( modelcfg[model_id], messagesmessages, toolstools, tool_choiceauto, ) msg response.choices[0].message while msg.tool_calls: messages.append(msg) for tc in msg.tool_calls: fn_name tc.function.name fn_args json.loads(tc.function.arguments) result functions[fn_name](**fn_args) messages.append({ role: tool, tool_call_id: tc.id, content: str(result), }) response client.chat.completions.create( modelcfg[model_id], messagesmessages, toolstools, tool_choiceauto, ) msg response.choices[0].message return msg.content if __name__ __main__: print(run_agent(北京現(xiàn)在天氣怎么樣, [weather_tool], available_functions))運(yùn)行python agent.py你會(huì)看到類似這樣的輸出北京 當(dāng)前溫度 18.3°C風(fēng)速 12.5 km/h如果模型在最終回復(fù)里做了自然語(yǔ)言潤(rùn)色可能輸出“北京現(xiàn)在氣溫大約 18.3 攝氏度風(fēng)速 12.5 公里每小時(shí)天氣比較舒適”。無(wú)論哪種都說(shuō)明整條鏈路通了模型識(shí)別意圖 → 輸出 tool_calls → 本地執(zhí)行函數(shù) → 結(jié)果回傳 → 模型生成回復(fù)。驗(yàn)證成功的幾個(gè)標(biāo)志第一response.choices[0].message.tool_calls不為空說(shuō)明模型確實(shí)決定調(diào)用 Skill第二tc.function.arguments里能解析出{city: Beijing}說(shuō)明參數(shù) Schema 被正確理解第三最終msg.content是自然語(yǔ)言而非空值說(shuō)明結(jié)果回傳后模型完成了二次推理。如果你想驗(yàn)證 MCP 那條鏈路可以用 MCP 客戶端連上weather_server.py調(diào)用list_tools應(yīng)該返回get_weather的定義調(diào)用call_tool傳入{city: Shanghai}應(yīng)該返回溫度文本。這一步通了說(shuō)明你的 Skill 不僅能被自家 Agent 用還能被任何 MCP 客戶端發(fā)現(xiàn)和調(diào)用。實(shí)測(cè)下來(lái)最容易出問(wèn)題的不是函數(shù)邏輯而是模型沒(méi)觸發(fā) tool_calls。這時(shí)候先檢查tool_choice是不是auto再檢查description里有沒(méi)有寫清使用場(chǎng)景。如果模型把“北京天氣”理解成閑聊而不是查詢多半是描述里缺了“當(dāng)用戶詢問(wèn)天氣時(shí)使用”這類觸發(fā)條件。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuth這一節(jié)對(duì)照真實(shí)報(bào)錯(cuò)逐個(gè)拆。這些錯(cuò)誤在 Skill 開(kāi)發(fā)和 MCP 接入過(guò)程中出現(xiàn)頻率最高提前知道怎么定位能省很多時(shí)間。401 Unauthorized最常見(jiàn)的原因是 Key 沒(méi)傳對(duì)或者 Base URL 寫錯(cuò)。先確認(rèn)config.json里的api_key是完整的sk-開(kāi)頭字符串沒(méi)有多余空格。再確認(rèn)base_url是https://taotoken.net/api不要寫成https://taotoken.net/api/v1或者漏掉/api。如果用的是環(huán)境變量檢查變量名拼寫和加載順序。401 的本質(zhì)是認(rèn)證失敗跟 Skill 邏輯無(wú)關(guān)先把接入層排干凈。local proxy failed / connection refused這個(gè)報(bào)錯(cuò)通常出現(xiàn)在 MCP 服務(wù)器啟動(dòng)階段。如果你在.mcp.json里配的command是python但系統(tǒng)里 Python 不在 PATH 上客戶端就拉不起服務(wù)器。解決辦法是寫絕對(duì)路徑比如/usr/bin/python3或者虛擬環(huán)境里的./venv/bin/python。另外args里的腳本路徑要相對(duì)于客戶端的工作目錄不確定的話也寫絕對(duì)路徑。這個(gè)錯(cuò)誤跟網(wǎng)絡(luò)代理無(wú)關(guān)純粹是進(jìn)程啟動(dòng)失敗。reading choices of undefined這個(gè)報(bào)錯(cuò)說(shuō)明response.choices是 undefined也就是模型接口返回的結(jié)構(gòu)不符合預(yù)期。常見(jiàn)原因有三個(gè)一是 Base URL 指錯(cuò)了請(qǐng)求打到了非 OpenAI 兼容的端點(diǎn)二是 Model ID 填了一個(gè)不存在的模型接口返回了錯(cuò)誤對(duì)象而不是標(biāo)準(zhǔn)響應(yīng)三是請(qǐng)求體里messages格式不對(duì)比如 role 寫成了user 帶空格。排查方法是把response整個(gè)打印出來(lái)看返回的 JSON 里有沒(méi)有error字段。如果是{error: {message: model not found}}那就是 Model ID 的問(wèn)題。OAuth 相關(guān)報(bào)錯(cuò)如果你在 Claude Code 或類似工具里看到 OAuth 失敗通常是因?yàn)楣ぞ吣J(rèn)走官方登錄流程而你想用 TaoToken 的 Key 通道。這時(shí)候需要在工具的配置里顯式指定 Base URL 和 API Key覆蓋默認(rèn)的 OAuth 路徑。以 Claude Code 為例可以在settings.json里配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密鑰 } }注意這里的變量名是工具約定的不同工具可能不同。核心思路是只要工具支持自定義 Base URL 和 Key就能走統(tǒng)一通道繞開(kāi) OAuth。如果工具不支持那就只能用它默認(rèn)的接入方式。還有一個(gè)容易忽略的坑MCP 服務(wù)器通過(guò) stdio 通信時(shí)如果服務(wù)器往 stdout 打印了調(diào)試信息會(huì)污染協(xié)議數(shù)據(jù)導(dǎo)致客戶端解析失敗。所以weather_server.py里不要用print輸出日志要輸出就用sys.stderr。這個(gè)錯(cuò)誤不會(huì)報(bào)得很明確通常表現(xiàn)為客戶端連上了但list_tools返回空或者超時(shí)。6. 把 Skill 用起來(lái)從單個(gè)示例到你的 Agent 能力矩陣跑通一個(gè)get_weather只是起點(diǎn)。真正讓 Agent 有超能力的是把多個(gè) Skill 組合起來(lái)形成能力矩陣。比如一個(gè)“出行助手”Agent可以同時(shí)掛載查天氣、查航班、查匯率、發(fā)郵件四個(gè) Skill模型會(huì)根據(jù)用戶意圖自動(dòng)選擇調(diào)用哪個(gè)或哪幾個(gè)。組合的關(guān)鍵在于 Skill 描述的邊界要清晰。如果兩個(gè) Skill 的描述都寫了“查詢信息”模型就不知道該選哪個(gè)。正確做法是讓每個(gè) Skill 的描述互斥且具體get_weather寫“查詢城市天氣”get_flight寫“查詢航班狀態(tài)”get_exchange_rate寫“查詢貨幣匯率”。描述越具體模型路由越準(zhǔn)。另一個(gè)實(shí)踐技巧是把 Skill 的返回結(jié)果結(jié)構(gòu)化。比如get_weather不要只返回一句自然語(yǔ)言而是返回 JSON 字符串讓模型自己決定怎么呈現(xiàn)給用戶。這樣同一個(gè) Skill 可以適配不同的輸出風(fēng)格要求復(fù)用性更強(qiáng)。如果你要把 Skill 分享給團(tuán)隊(duì)或社區(qū)MCP 是更好的交付形式。把 Skill 封裝成 MCP 服務(wù)器后任何人只要在客戶端配置里掛上你的服務(wù)器地址就能直接使用不需要復(fù)制代碼。這也是 MCP 作為“管道”的價(jià)值Skill 是內(nèi)容MCP 是分發(fā)標(biāo)準(zhǔn)。最后給一個(gè)實(shí)用建議每寫一個(gè)新 Skill先用單元測(cè)試驗(yàn)證執(zhí)行函數(shù)本身正確再放進(jìn) Agent 循環(huán)里測(cè)模型調(diào)用。因?yàn)槟Ｐ陀袝r(shí)會(huì)傳入你意想不到的參數(shù)比如把city傳成北京 帶空格或者傳成Beijing, China。執(zhí)行函數(shù)里做好參數(shù)清洗和異常捕獲比在模型側(cè)反復(fù)調(diào)描述更省事。需要對(duì)照接入細(xì)節(jié)的話接入文檔在https://taotoken.net/docAPI Key 在https://taotoken.net/api-keys管理模型對(duì)話調(diào)試可以用https://taotoken.net/chat長(zhǎng)期跑編碼類 Agent 任務(wù)可以看 Coding Plan 的說(shuō)明。三件套配好剩下的就是構(gòu)思你的 Agent 該有哪些 Skill然后一個(gè)一個(gè)實(shí)現(xiàn)。