真·干活的項(xiàng)目把AI代理從“嘴強(qiáng)王者”變成“能力者”全靠一套Agent Skills技能庫(kù)之前我一直在搞AI代理Agent應(yīng)用最頭疼的問題就是模型對(duì)話能力再?gòu)?qiáng)只要一落到具體業(yè)務(wù)場(chǎng)景里比如讓它查個(gè)訂單、算個(gè)運(yùn)費(fèi)、調(diào)一下庫(kù)存就立刻露怯。模型只是會(huì)“說(shuō)”根本不會(huì)“做”。后來(lái)我意識(shí)到問題不在模型本身而在于——你壓根沒給代理配上一套真正能干的“手和腳”。這個(gè)項(xiàng)目叫agent-skills說(shuō)白了就是一套專門為AI代理設(shè)計(jì)的技能注冊(cè)與調(diào)度系統(tǒng)。它做的事情非常聚焦把外部能力API、數(shù)據(jù)庫(kù)查詢、計(jì)算邏輯、規(guī)則引擎封裝成一個(gè)個(gè)結(jié)構(gòu)化的“技能”讓代理在需要的時(shí)候能自動(dòng)、準(zhǔn)確地調(diào)用它們而不是靠模型瞎猜或者硬編碼一堆if-else。如果你正在開發(fā)AI客服、自動(dòng)化運(yùn)維助手、內(nèi)部知識(shí)庫(kù)問答機(jī)器人或者任何需要讓大模型真正操作業(yè)務(wù)系統(tǒng)的項(xiàng)目這套設(shè)計(jì)思路絕對(duì)是值得直接抄作業(yè)的參考樣板。我是在處理一個(gè)電商售后場(chǎng)景的原型時(shí)啟動(dòng)這個(gè)項(xiàng)目的。當(dāng)時(shí)把一堆功能邏輯硬塞進(jìn)Prompt里結(jié)果一長(zhǎng)對(duì)話就崩潰模型偶爾自己“腦補(bǔ)”出一個(gè)訂單號(hào)去查詢或者該調(diào)接口的時(shí)候不動(dòng)手直接把一段假數(shù)據(jù)當(dāng)成結(jié)果返回給我。后來(lái)我按agent-skills這套思路重構(gòu)了整個(gè)調(diào)用鏈路一下子清爽太多了。這篇就把完整的拆解、實(shí)現(xiàn)路徑和踩坑記錄拿出來(lái)聊聊。1. 項(xiàng)目思路剖析agent-skills到底在解決什么問題1.1 從“會(huì)聊天”到“能辦事”的關(guān)鍵跳躍先說(shuō)清楚為什么光有大模型還不夠。一個(gè)典型的AI代理應(yīng)用核心鏈路一定是用戶輸入 → 模型理解意圖 → 生成行動(dòng)方案 → 調(diào)用外部工具 → 匯總結(jié)果回復(fù)。在這個(gè)鏈路里前面兩步模型干得特別好但一旦進(jìn)入“調(diào)用外部工具”問題就來(lái)了。傳統(tǒng)做法是把工具函數(shù)一股腦塞進(jìn)代碼里然后靠提示詞讓模型自己去選。最開始我這么干的時(shí)候幾十個(gè)函數(shù)全掛在一個(gè)tools數(shù)組里結(jié)果模型經(jīng)常選錯(cuò)工具。尤其是兩個(gè)函數(shù)的功能描述比較接近時(shí)比如query_order_detail查訂單詳情和search_order_list搜索訂單列表模型分不清什么時(shí)候該用哪個(gè)經(jīng)常返回一個(gè)結(jié)構(gòu)完全不對(duì)的調(diào)用請(qǐng)求。agent-skills的核心思想是把每一個(gè)能力封裝成帶獨(dú)立命名空間、元信息描述、參數(shù)Schema校驗(yàn)的“技能”。它不追求模型直接調(diào)用函數(shù)而是讓模型學(xué)會(huì)“選技能、填參數(shù)”然后由技能注冊(cè)中心去完成實(shí)際執(zhí)行。等于在模型和業(yè)務(wù)代碼之間加了一層標(biāo)準(zhǔn)化網(wǎng)關(guān)。這一層的價(jià)值非常直觀模型只負(fù)責(zé)“做決定”不負(fù)責(zé)“做執(zhí)行”。執(zhí)行交給可靠的程序代碼決定通過(guò)結(jié)構(gòu)化的技能元信息來(lái)約束和引導(dǎo)。1.2 “工具”太多太亂的時(shí)候你需要“技能”層面的抽象很多團(tuán)隊(duì)是從“給模型加個(gè)函數(shù)調(diào)用”起步的但很快會(huì)發(fā)現(xiàn)函數(shù)數(shù)量上來(lái)以后管理就成了災(zāi)難。一個(gè)函數(shù)三五個(gè)人改過(guò)簽名變了描述過(guò)期了參數(shù)含義不清晰模型自然就懵了。agent-skills比單純“工具函數(shù)”多出來(lái)的是完整生命周期管理每個(gè)技能有明確的名稱、描述、版本號(hào)、所屬領(lǐng)域參數(shù)聲明嚴(yán)格遵守JSON Schema規(guī)范可以自動(dòng)化校驗(yàn)技能可以被動(dòng)態(tài)啟用/停用不影響其他技能技能之間可以被編排成組合流程而不是孤立的一對(duì)一調(diào)用。我實(shí)際體驗(yàn)中最大的直觀感受是排查問題變得極快。以前模型調(diào)錯(cuò)函數(shù)得翻代碼日志反復(fù)對(duì)?，F(xiàn)在技能層提供了標(biāo)準(zhǔn)的入?yún)?、出參、耗時(shí)和狀態(tài)記錄整個(gè)調(diào)用鏈一目了然看一眼日志就知道模型選了什么技能、填了什么參數(shù)、結(jié)果哪里不對(duì)。1.3 為什么“選技能”比“寫死邏輯”更適合LLM應(yīng)用這里要解釋一個(gè)底層原因大模型的指令遵循能力是有邊界概率的。你把一個(gè)任務(wù)寫死在Prompt里模型在簡(jiǎn)單場(chǎng)景下表現(xiàn)不錯(cuò)但一旦任務(wù)邊界模糊、輸入多樣化寫死邏輯就崩了。舉個(gè)例子用戶說(shuō)“幫我看看我那個(gè)包裹到哪了”模型需要自己判斷這涉及到“查詢物流信息”這個(gè)技能但它還需要從用戶消息中抽取訂單號(hào)、判斷查詢來(lái)源是哪個(gè)平臺(tái)。如果你把“查詢物流”的邏輯和“抽取訂單號(hào)”的邏輯混在一起模型很難穩(wěn)定執(zhí)行。agent-skills的做法是把“抽取訂單號(hào)”也定義為一個(gè)技能把“查詢物流”定義為另一個(gè)技能然后在技能描述里明確各自職責(zé)和依賴關(guān)系。模型可以通過(guò)一次“技能鏈調(diào)用”逐步完成先用extract_order_number技能從用戶原文中抽取訂單號(hào)再把結(jié)果傳給query_logistics技能。每一步的輸入輸出都有清晰約束可靠性高得多。這就是技能抽象的核心價(jià)值讓每個(gè)動(dòng)作都足夠單一、足夠可靠模型只需要做選擇題和填表題不需要做自由發(fā)揮的綜合題。2. 整體架構(gòu)與技能分類設(shè)計(jì)2.1 技能注冊(cè)中心一切能力皆可聲明我先給出整體架構(gòu)中最關(guān)鍵的一個(gè)角色技能注冊(cè)中心。它的職責(zé)是維護(hù)一份所有可用技能的清單并提供給模型進(jìn)行工具選擇。我用Python實(shí)現(xiàn)核心是一個(gè)帶有裝飾器的注冊(cè)表# skill_registry.py from typing import Callable, Dict, Any, Optional, List from pydantic import BaseModel, Field, create_model import inspect class Skill: def __init__(self, name: str, description: str, parameters_schema: Dict[str, Any], handler: Callable): self.name name self.description description self.parameters_schema parameters_schema self.handler handler self.enabled True def to_openai_format(self) - Dict[str, Any]: 轉(zhuǎn)換為 OpenAI function calling 所需的結(jié)構(gòu) return { type: function, function: { name: self.name, description: self.description, parameters: self.parameters_schema } } class SkillRegistry: _skills: Dict[str, Skill] {} classmethod def register(cls, name: str, description: str, parameters_schema: Dict[str, Any]): def decorator(func: Callable): skill Skill(namename, descriptiondescription, parameters_schemaparameters_schema, handlerfunc) cls._skills[name] skill return func return decorator classmethod def get_all_skills(cls) - List[Dict[str, Any]]: return [skill.to_openai_format() for skill in cls._skills.values() if skill.enabled] classmethod def execute(cls, name: str, arguments: Dict[str, Any]) - Any: skill cls._skills.get(name) if not skill: raise KeyError(f技能 {name} 不存在或未注冊(cè)) if not skill.enabled: raise RuntimeError(f技能 {name} 已被停用) return skill.handler(**arguments)這個(gè)注冊(cè)中心的實(shí)現(xiàn)本身并不復(fù)雜但設(shè)計(jì)上是經(jīng)過(guò)取舍的。用裝飾器注冊(cè)的好處是技能定義與業(yè)務(wù)實(shí)現(xiàn)完全內(nèi)聚新增一個(gè)技能只需要寫一個(gè)函數(shù)加一行裝飾器不需要改任何集中配置文件。一旦技能數(shù)量突破五十個(gè)這種聲明式管理的優(yōu)勢(shì)會(huì)非常明顯。to_openai_format()這個(gè)方法很關(guān)鍵它保證了技能注冊(cè)表可以直接無(wú)縫對(duì)接到各類模型的function calling接口不需要再單獨(dú)維護(hù)一套映射邏輯。2.2 技能分類按職責(zé)粒度劃分技能不是隨便堆的我通常把技能分成三個(gè)層次原子技能單個(gè)動(dòng)作不依賴其他技能直接執(zhí)行一個(gè)API調(diào)用或數(shù)據(jù)庫(kù)查詢。例如query_order_status、send_email、calculate_shipping_fee。組合技能編排多個(gè)原子技能的流程邏輯。例如handle_order_refund這個(gè)組合技能內(nèi)部要先調(diào)verify_identity、再調(diào)query_order_detail、再調(diào)calculate_refund_amount、最后執(zhí)行execute_refund。兜底技能當(dāng)所有技能都不匹配用戶意圖時(shí)觸發(fā)一個(gè)結(jié)構(gòu)化的話術(shù)回復(fù)或轉(zhuǎn)人工邏輯。兜底技能的存在至關(guān)重要它能避免模型強(qiáng)行匹配一個(gè)不相關(guān)技能的情況。這里的關(guān)鍵是按照“業(yè)務(wù)能力”來(lái)劃分而不是按照“代碼模塊”來(lái)劃分。這兩個(gè)是有本質(zhì)區(qū)別的。比如query_user_balance和query_user_points從代碼角度看可能都是讀同一個(gè)用戶表但它們面對(duì)的是完全不同的業(yè)務(wù)意圖必須拆成兩個(gè)技能。反過(guò)來(lái)get_order_by_id和get_order_by_tracking_number雖然API不同但業(yè)務(wù)意圖都是“查訂單詳情”建議合并成一個(gè)技能通過(guò)不同參數(shù)來(lái)區(qū)分。2.3 技能描述寫清楚才能被正確調(diào)用這是整個(gè)agent-skills體系里最容易被人忽略但影響最大的部分。技能描述寫不好模型再?gòu)?qiáng)也白搭。我總結(jié)了一套技能描述的黃金寫法核心規(guī)則如下描述必須以動(dòng)作開頭明確“這個(gè)技能能做什么”必須包含觸發(fā)場(chǎng)景的關(guān)鍵詞讓模型在意圖匹配時(shí)能找到必須說(shuō)明參數(shù)之間是否有依賴關(guān)系、哪個(gè)是必填項(xiàng)、哪個(gè)是可選必須說(shuō)明輸出格式的基礎(chǔ)特征避免模型誤解返回結(jié)構(gòu)。我舉個(gè)例子一個(gè)原本寫得很差的技能描述是查詢訂單信息。這種描述模型根本不知道怎么觸發(fā)也不知道應(yīng)該傳什么參數(shù)。我重寫之后是這樣name: query_order_detail description: 根據(jù)訂單編號(hào)查詢訂單的詳細(xì)信息包括商品清單、支付狀態(tài)、配送進(jìn)度和售后狀態(tài)。 當(dāng)用戶使用以下詞匯表達(dá)時(shí)使用此技能查訂單、訂單詳情、我的訂單、訂單狀態(tài)、 tracking、物流跟蹤。不適用于搜索歷史訂單列表那是另一個(gè)技能。 parameters: order_id: type: string description: 訂單編號(hào)格式為SO-開頭的字符串用戶在消息中直接提供如果沒有則需先通過(guò)用戶詢問獲取切勿編造。 required: true描述里面加了“不適用于”這幾個(gè)字看著不起眼但對(duì)模型來(lái)說(shuō)是非常強(qiáng)力的負(fù)向約束能顯著減少技能誤觸發(fā)的概率。實(shí)測(cè)下來(lái)把一組相似技能都這樣寫上“不適用場(chǎng)景”之后模型工具選擇的準(zhǔn)確率能提升不少。3. 從零構(gòu)建技能庫(kù)核心環(huán)節(jié)實(shí)戰(zhàn)3.1 一個(gè)實(shí)戰(zhàn)技能從封裝到上線的完整過(guò)程我這里用一個(gè)真實(shí)的電商場(chǎng)景技能來(lái)走一遍完整流程商品庫(kù)存查詢。這個(gè)技能在售后客服場(chǎng)景中特別常用但也很容易寫崩。第一步定義技能參數(shù)Schema。庫(kù)存查詢的關(guān)鍵參數(shù)有兩個(gè)商品SKU編號(hào)和查詢維度全局庫(kù)存還是某個(gè)倉(cāng)庫(kù)。另外還需要一個(gè)可選的include_locked參數(shù)用來(lái)控制是否包含鎖定庫(kù)存。參數(shù)定好了之后模型才不會(huì)傳亂七八糟的東西INVENTORY_CHECK_SCHEMA { type: object, properties: { sku_id: { type: string, description: 商品SKU編號(hào)例如SKU-8842 }, warehouse: { type: [string, null], description: 倉(cāng)庫(kù)編碼例如 WH-SH-01如果省略則查詢?nèi)揽値?kù)存, default: None }, include_locked: { type: boolean, description: 是否統(tǒng)計(jì)鎖定庫(kù)存默認(rèn)False即只返回可售庫(kù)存, default: False } }, required: [sku_id] }第二步寫具體執(zhí)行邏輯。這里要特別注意技能處理器里要做參數(shù)校驗(yàn)和容錯(cuò)不能假設(shè)模型一定傳了正確的參數(shù)進(jìn)來(lái)。實(shí)際項(xiàng)目里我遇到過(guò)模型把訂單號(hào)當(dāng)SKU編號(hào)傳進(jìn)來(lái)或者把倉(cāng)庫(kù)名寫成中文這類臟數(shù)據(jù)全靠處理器的守門邏輯攔截SkillRegistry.register( namecheck_inventory, description根據(jù)SKU編號(hào)查詢商品庫(kù)存情況當(dāng)用戶詢問是否有貨、庫(kù)存多少、什么時(shí)候能發(fā)貨時(shí)使用。, parameters_schemaINVENTORY_CHECK_SCHEMA ) def check_inventory(sku_id: str, warehouse: Optional[str] None, include_locked: bool False): # 參數(shù)兜底 if not sku_id: raise ValueError(sku_id不能為空) sku_id sku_id.strip().upper() if not sku_id.startswith(SKU-): raise ValueError(fSKU編號(hào)格式錯(cuò)誤: {sku_id}) # 調(diào)用真實(shí)的庫(kù)存服務(wù)接口 # 這里以mock數(shù)據(jù)代替實(shí)際RPC調(diào)用 inventory_data get_inventory_from_service(sku_id, warehouse, include_locked) result { sku_id: sku_id, available: inventory_data[available], locked: inventory_data[locked], warehouse: warehouse or ALL, estimated_restock_days: inventory_data.get(restock_days, None) } return result第三步尤其重要返回值要設(shè)計(jì)成結(jié)構(gòu)化JSON而且要“夠用、不多給”。模型拿到返回結(jié)果后還會(huì)用它組織回復(fù)話術(shù)。如果返回字段太少比如只返回available模型就不知道如何解釋“為什么缺貨”如果返回字段太多模型反而會(huì)抓不住重點(diǎn)。所以返回結(jié)構(gòu)我一般會(huì)控制在三到六個(gè)關(guān)鍵字段并給每個(gè)字段起直觀的英文命名。3.2 給模型接上技能從提示詞工程到Function Calling技能注冊(cè)好之后接下來(lái)是讓模型能夠“看到”這份技能清單。這里存在兩種主流做法我實(shí)際都用過(guò)做法一純提示詞JSON輸出解析。把技能清單的JSON格式塞進(jìn)系統(tǒng)提示詞里要求模型輸出一個(gè)固定格式的JSON調(diào)用請(qǐng)求。這個(gè)做法的優(yōu)點(diǎn)是兼容所有模型不需要額外接口能力缺點(diǎn)是輸出穩(wěn)定性差模型可能偶爾輸出額外的解釋文本或者格式錯(cuò)亂。做法二使用模型的Function Calling接口。這是目前推薦的方案。GPT系列、Claude等主流模型都原生支持工具調(diào)用功能。做法是把技能注冊(cè)中心的get_all_skills()返回結(jié)果直接傳給API的tools參數(shù)然后由模型輸出結(jié)構(gòu)化的調(diào)用指令def chat_with_agent(user_message: str): messages [{role: user, content: user_message}] # 第一次調(diào)用讓模型決定是否調(diào)用技能 response client.chat.completions.create( modelgpt-4o, messagesmessages, toolsSkillRegistry.get_all_skills(), tool_choiceauto ) tool_calls response.choices[0].message.tool_calls if not tool_calls: # 模型直接回復(fù)沒有調(diào)用技能 return response.choices[0].message.content # 執(zhí)行技能并拼接結(jié)果 result_messages [] for tool_call in tool_calls: func_name tool_call.function.name func_args json.loads(tool_call.function.arguments) try: result SkillRegistry.execute(func_name, func_args) result_messages.append({ role: tool, tool_call_id: tool_call.id, content: json.dumps(result, ensure_asciiFalse) }) except Exception as e: result_messages.append({ role: tool, tool_call_id: tool_call.id, content: f技能執(zhí)行失敗: {str(e)} }) # 第二次調(diào)用把執(zhí)行結(jié)果交回給模型組織最終回復(fù) messages.extend(result_messages) final_response client.chat.completions.create( modelgpt-4o, messagesmessages, toolsSkillRegistry.get_all_skills() ) return final_response.choices[0].message.content這個(gè)模式的精髓在于“兩次調(diào)用”第一輪讓模型決定要不要技能、要哪些技能第二輪把技能真實(shí)執(zhí)行結(jié)果交還給模型讓它組織成人話回復(fù)。如果技能執(zhí)行出錯(cuò)同樣可以走第二輪流程讓模型基于錯(cuò)誤信息生成安撫話術(shù)或轉(zhuǎn)人工判斷體驗(yàn)會(huì)自然很多。3.3 技能編排如何實(shí)現(xiàn)多技能組合調(diào)用單一技能場(chǎng)景相對(duì)簡(jiǎn)單真正體現(xiàn)agent-skills價(jià)值的是多技能編排。售后場(chǎng)景中用戶一句“我要退了這個(gè)訂單里那個(gè)不合適的尺碼”就同時(shí)涉及身份驗(yàn)證、訂單查詢、商品信息讀取、售后受理等多個(gè)技能。我有兩種編排方式可以分享順序編排模型在第一輪調(diào)用時(shí)輸出多個(gè)tool_calls它們之間沒有依賴關(guān)系可以同時(shí)或者按順序執(zhí)行。比如同時(shí)查訂單信息和查用戶等級(jí)互不干擾。鏈?zhǔn)骄幣藕笠粋€(gè)技能需要前一個(gè)技能的執(zhí)行結(jié)果作為輸入。這種情況模型第一輪只會(huì)輸出一個(gè)調(diào)用執(zhí)行完拿到結(jié)果、拼接進(jìn)消息歷史之后再到第二輪繼續(xù)決策。我代碼里的循環(huán)結(jié)構(gòu)就是干這個(gè)用的while True: response client.chat.completions.create( modelgpt-4o, messagesmessages, toolsSkillRegistry.get_all_skills(), tool_choiceauto ) tool_calls response.choices[0].message.tool_calls if not tool_calls: break for tool_call in tool_calls: # 逐個(gè)執(zhí)行技能 result SkillRegistry.execute(...) messages.append({role: tool, content: json.dumps(result)})這里需要注意一個(gè)關(guān)鍵設(shè)置loop的最大次數(shù)要設(shè)上限通常三到五次。不設(shè)上限的話遇到一個(gè)循環(huán)依賴或者模型抽風(fēng)請(qǐng)求就永遠(yuǎn)停不下來(lái)了既燒錢又拖慢響應(yīng)。4. 踩坑記錄與排查實(shí)錄技能庫(kù)落地最容易翻車的地方這部分是平時(shí)最容易忽略、但線上問題幾乎全部集中在這里的內(nèi)容。4.1 技能描述與用戶真實(shí)表達(dá)之間的“語(yǔ)言鴻溝”我遇到過(guò)最典型的案例技能描述里寫的是“查詢訂單”但用戶實(shí)際說(shuō)的是“我那個(gè)東西怎么還沒到”“能幫我催一下快遞嗎”。模型其實(shí)知道要用技能但就是匹配不上因?yàn)槊枋隼锔緵]有“快遞”“到貨”“催單”這類詞。排查方法很簡(jiǎn)單打開線上對(duì)話日志把模型實(shí)際觸發(fā)的技能名和用戶原始文本放在一起對(duì)比。你會(huì)發(fā)現(xiàn)凡是頻繁出現(xiàn)“模型未調(diào)用任何技能但用戶明顯有需求”的情況大概率是技能描述缺少口語(yǔ)化同義詞。解決方式是我后來(lái)固定的一個(gè)習(xí)慣每上線一個(gè)技能先拉取過(guò)去三十天使用過(guò)的真實(shí)用戶語(yǔ)料提取高頻詞匯回填進(jìn)技能描述里。這個(gè)動(dòng)作看起來(lái)簡(jiǎn)單但對(duì)技能命中率的提升非常顯著。例如發(fā)貨查詢技能的描述里加上“包裹”“物流單號(hào)”“到哪了”“多久到”整體準(zhǔn)確率能直接上一個(gè)臺(tái)階。4.2 模型“幻覺”參數(shù)明明沒有的訂單號(hào)硬編一個(gè)出來(lái)這個(gè)坑幾乎每個(gè)做Agent的人都會(huì)踩。用戶問“我上周的訂單”模型確實(shí)調(diào)用了查訂單技能但是把ORDER_ID填成了ORDER-12345678這個(gè)單號(hào)完全是虛構(gòu)的。技能層拿這個(gè)假單號(hào)去查詢自然什么都查不到。這種情況的本質(zhì)是模型的參數(shù)抽取能力有問題或者上下文中根本不存在訂單號(hào)模型只能靠猜。徹底解決方案是在技能參數(shù)Schema中設(shè)置依賴描述{ order_id: { type: string, description: 訂單編號(hào)必須由用戶直接提供或通過(guò)身份驗(yàn)證接口獲取禁止自行生成或猜測(cè)。如果缺少該參數(shù)請(qǐng)先詢問用戶。 } }描述里明確“禁止猜測(cè)”三個(gè)字雖然不能保證100%避免幻覺但實(shí)測(cè)能明顯減少次數(shù)。更穩(wěn)妥的做法是加一層執(zhí)行前校驗(yàn)如果參數(shù)值不符合業(yè)務(wù)規(guī)則比如訂單號(hào)格式不匹配或者沒有在已登錄用戶上下文里找到訂單記錄直接讓技能返回一個(gè)標(biāo)準(zhǔn)錯(cuò)誤消息讓模型基于錯(cuò)誤消息去詢問用戶。4.3 技能之間的隱式依賴與循環(huán)調(diào)用多技能組合場(chǎng)景下一個(gè)比較隱蔽的問題是技能A的執(zhí)行邏輯內(nèi)部又去調(diào)用了技能B而技能B內(nèi)部又回調(diào)A形成了循環(huán)調(diào)用。例如技能A: 查詢訂單詳情 技能B: 查詢退款狀態(tài) 查詢訂單詳情的邏輯里為了展示退款狀態(tài)又去調(diào)用了查詢退款狀態(tài)的接口。 查詢退款狀態(tài)的邏輯里為了判斷退款進(jìn)度又去調(diào)用了訂單詳情接口。表面看兩個(gè)技能都寫得沒毛病但實(shí)際一跑一對(duì)用戶請(qǐng)求就能把服務(wù)拖僵死。我處理這類問題的原則是技能處理器內(nèi)部不調(diào)用其他技能只調(diào)用真實(shí)的業(yè)務(wù)API或數(shù)據(jù)服務(wù)。如果需要跨技能數(shù)據(jù)應(yīng)該在編排層組合而不是在實(shí)現(xiàn)層相互調(diào)用。為此我還加了一個(gè)簡(jiǎn)單的依賴檢查工具掃描注冊(cè)的所有技能處理器函數(shù)凡是直接調(diào)用了SkillRegistry.execute內(nèi)部邏輯的都會(huì)在啟動(dòng)時(shí)被標(biāo)記警告。4.4 技能參數(shù)校驗(yàn)失敗后的提示語(yǔ)模板參數(shù)校驗(yàn)失敗時(shí)錯(cuò)誤信息直接影響后續(xù)模型的回復(fù)質(zhì)量。如果你直接拋出ValueError: sku_id為空模型很可能把這個(gè)硬邦邦的異常文本直接轉(zhuǎn)述給用戶非常不友好。后來(lái)我給每個(gè)技能都定義了標(biāo)準(zhǔn)錯(cuò)誤碼和錯(cuò)誤提示模板{ error_code: SKU_NOT_FOUND, user_message: 沒有找到編號(hào)為 {sku_id} 的商品請(qǐng)您核對(duì)一下商品編碼后重新發(fā)送。, debug_message: 庫(kù)存服務(wù)返回404sku_id{sku_id} }技能執(zhí)行異常時(shí)返回這個(gè)結(jié)構(gòu)體而不是拋出異常模型拿到user_message字段就能組織成一個(gè)自然、溫和的回復(fù)。而debug_message則會(huì)同步記錄在日志里供研發(fā)人員排查。這樣一魚多吃用戶體驗(yàn)和工程排障都兼顧到了。5. 技能庫(kù)的日常維護(hù)測(cè)試、觀測(cè)與迭代5.1 給每個(gè)技能配一套“罐頭用例”做回歸測(cè)試技能是給模型用的模型的調(diào)用充滿了不確定性所以技能庫(kù)比普通代碼更需要測(cè)試。我給自己定了一條規(guī)矩每個(gè)技能上線時(shí)必須配備至少五個(gè)測(cè)試用例覆蓋正常調(diào)用、邊界參數(shù)、缺失必填項(xiàng)、業(yè)務(wù)異常四種情況。測(cè)試用例的形態(tài)是一一對(duì)應(yīng)的“用戶輸入語(yǔ)句 → 期望觸發(fā)的技能 → 期望參數(shù)值”。例如用例名稱用戶輸入期望技能期望參數(shù)正常查詢幫我查一下訂單SO-12345到哪里了query_order_detailorder_idSO-12345無(wú)參數(shù)查詢我的訂單情況怎么樣query_order_listuser_id當(dāng)前用戶參數(shù)格式錯(cuò)誤查訂單123query_order_detail無(wú)應(yīng)觸發(fā)追問非相關(guān)請(qǐng)求今天天氣怎么樣不觸發(fā)任何訂單技能-這些用例不僅是測(cè)試腳本實(shí)際也是后續(xù)微調(diào)Prompt的數(shù)據(jù)基礎(chǔ)。每輪技能改動(dòng)后跑一遍回歸能非?？焖侔l(fā)現(xiàn)模型行為是否有退化。5.2 技能調(diào)用日志從對(duì)話中復(fù)盤每一處“失手”我強(qiáng)烈建議從項(xiàng)目第一天起就記錄完整技能調(diào)用日志。字段不需要太復(fù)雜但下面這五項(xiàng)必須有時(shí)間戳、會(huì)話ID、用戶輸入原文、技能名稱、入?yún)SON、出參JSON、執(zhí)行耗時(shí)、是否成功。注意如果技能執(zhí)行失敗必須同時(shí)記錄異常堆?；驑I(yè)務(wù)錯(cuò)誤碼否則排查等于抓瞎。有了日志我做的最有價(jià)值的動(dòng)作是每天跑一次“技能失手分析”篩選出模型調(diào)用了技能、但用戶隨后明確表達(dá)不滿例如“不對(duì)”“不是這個(gè)”“我是說(shuō)”的會(huì)話逐條查看是什么原因?qū)е履Ｐ瓦x錯(cuò)了技能或填錯(cuò)了參數(shù)。這個(gè)過(guò)程非常痛苦但非常值得往往能發(fā)現(xiàn)描述上的模糊點(diǎn)、參數(shù)Schema設(shè)計(jì)不合理等平時(shí)注意不到的問題。5.3 技能上線、停用與版本迭代機(jī)制技能庫(kù)發(fā)展到后期一定會(huì)有技能被新技能替代或者業(yè)務(wù)下線導(dǎo)致某個(gè)技能廢棄。agent-skills里我實(shí)現(xiàn)了enabled開關(guān)同時(shí)還有一個(gè)簡(jiǎn)單的版本控制字段。版本控制的策略很簡(jiǎn)單給每個(gè)技能增加一個(gè)version屬性注冊(cè)時(shí)記錄執(zhí)行時(shí)默認(rèn)使用最新版本如果模型在參數(shù)解析時(shí)出現(xiàn)歷史技能的緩存引用則自動(dòng)映射到最新版本并記錄一條告警日志。技能廢棄時(shí)不是直接刪除代碼而是先置為enabledFalse保留定義和實(shí)現(xiàn)在日志中觀察一段時(shí)間沒有異常調(diào)用后再清理。這樣做的原因是已經(jīng)被上下文中保存的歷史消息引用的工具調(diào)用某些模型還會(huì)嘗試用舊ID訪問如果直接刪除技能可能會(huì)在第二輪回調(diào)時(shí)報(bào)錯(cuò)。6. 一些關(guān)鍵配置與技巧沉淀到這里主體架構(gòu)已經(jīng)全拆完了。最后我把自己幾個(gè)月來(lái)沉淀下來(lái)的幾條硬經(jīng)驗(yàn)直接列在這里希望能幫你少走一些彎路。第一技能數(shù)量控制在20到40個(gè)左右時(shí)模型的選擇準(zhǔn)確率最高。少于20個(gè)意味著有些技能粒度過(guò)粗模型繞彎路多于40個(gè)模型的選擇困惑度明顯上升。如果真的需要超過(guò)40個(gè)技能優(yōu)先考慮分組路由先讓模型選擇技能分類再在分類內(nèi)選擇具體技能。第二技能返回的JSON結(jié)構(gòu)必須穩(wěn)定。上線后盡量不要更改字段名或嵌套層級(jí)否則已經(jīng)習(xí)慣舊結(jié)構(gòu)的模型在相同場(chǎng)景下可能會(huì)輸出錯(cuò)誤引用。必須改時(shí)先在描述里同步更新示例再用幾輪真實(shí)對(duì)話做回歸驗(yàn)證。第三不要吝嗇在技能描述里寫“邊界約束”。那些寫著“不要用于XX場(chǎng)景”“僅當(dāng)XX時(shí)才使用”的約束雖然讓描述顯得啰嗦但它們的價(jià)值在模型誤觸發(fā)率上有著直接影響。這是投入產(chǎn)出比極高的優(yōu)化項(xiàng)。第四為技能執(zhí)行設(shè)置超時(shí)與重試機(jī)制。我當(dāng)時(shí)用的是兩秒超時(shí)失敗后最多重試一次仍失敗則直接返回標(biāo)準(zhǔn)錯(cuò)誤結(jié)構(gòu)。這個(gè)設(shè)置讓整體掉線率大大下降——外部API不穩(wěn)定就是技術(shù)的常態(tài)與其讓用戶干等不如快速給一個(gè)可解釋的答復(fù)。第五關(guān)于日志脫敏。技能庫(kù)場(chǎng)景里一定會(huì)接觸到用戶手機(jī)號(hào)、訂單號(hào)等敏感數(shù)據(jù)日志記錄前必須做脫敏處理至少把中間幾位打碼。千萬(wàn)別貪圖排查便利把明文數(shù)據(jù)全量入庫(kù)一旦日志庫(kù)泄露就是安全事故這個(gè)底線不要碰。我在實(shí)際項(xiàng)目的感受是agent-skills這套東西最爽的一點(diǎn)在于你每新增一個(gè)業(yè)務(wù)能力不再需要改動(dòng)對(duì)話主流程的代碼只需注冊(cè)一個(gè)新技能寫清楚描述和參數(shù)結(jié)構(gòu)就能立刻被代理使用。整個(gè)系統(tǒng)的擴(kuò)展方式從“改代碼”變成了“加配置”這才是它真正的長(zhǎng)期價(jià)值。如果你也正在做Agent類應(yīng)用建議從小規(guī)模開始先把三個(gè)最核心的業(yè)務(wù)動(dòng)作封裝成技能跑通全鏈路再慢慢擴(kuò)充這個(gè)方法比我一開始貪多貪全要舒服得多。