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