戰(zhàn)指南：騰訊云上打造全能Agent的技能編排核心方法)
1. 先搞明白AI Skills 在 Agent 體系里到底扮演什么角色我在實(shí)戰(zhàn)里帶過(guò)不少 Agent 項(xiàng)目說(shuō)實(shí)話早期踩過(guò)最大的坑就是把“Agent 框架”和“AI Skills”混為一談以為只要接一個(gè)大模型API再套一層工具調(diào)用就算完事。結(jié)果項(xiàng)目跑到中后期技能一多豆?jié){油條全往里塞邏輯糾纏到一起調(diào)試一次恨不得抽一包煙。后來(lái)在騰訊云上完整跑通了一套基于 AI Skills 的 Agent 項(xiàng)目才算是把“技能分層、按需編排、獨(dú)立擴(kuò)展”這條路走順了。這篇博文我索性把這套實(shí)踐完整復(fù)盤出來(lái)標(biāo)題就叫“全能 Agent 養(yǎng)成記”不吹不黑把配置、編碼、聯(lián)調(diào)、排障的過(guò)程全擺出來(lái)希望能幫到正在做 Agent 開發(fā)、尤其是打算在騰訊云上落地的朋友。先說(shuō)清楚一個(gè)基本概念Skills 在 AI Agent 體系里對(duì)應(yīng)的是模型之外的能力集合它可以是一個(gè)工具函數(shù)的描述集也可以是若干API的編排模板還可以是帶提示詞約束的專用子流程。Agent 本身負(fù)責(zé)理解意圖、拆解任務(wù)、決定調(diào)哪個(gè)技能Skills 則負(fù)責(zé)具體干活兒。所以改寫一個(gè) Agent 項(xiàng)目的復(fù)雜度很大程度上取決于你技能層的設(shè)計(jì)是否夠清晰、是否方便獨(dú)立測(cè)試、是否便于動(dòng)態(tài)加載。為什么選騰訊云做訓(xùn)練場(chǎng)坦率講云廠商這類服務(wù)很多但騰訊云的 AI Skills 在“模型服務(wù)、技能注冊(cè)、云端調(diào)試、灰度發(fā)布”這套閉環(huán)上做得比較完整加上用的是我們國(guó)內(nèi)團(tuán)隊(duì)更熟悉的控制臺(tái)操作習(xí)慣上手門檻低。更關(guān)鍵的是它在技能編排這一層其實(shí)兼容了很多開源生態(tài)的思維比如把技能描述寫清楚后模型能自動(dòng)路由到正確的技能上。這一點(diǎn)在你技能數(shù)量超過(guò) 20 個(gè)之后會(huì)變得非常重要靠“if-else 硬編碼調(diào)度”的方式根本活不過(guò)三個(gè)月。我在文章后面會(huì)按照“先理解、再配置、后實(shí)現(xiàn)、最后排障”的順序來(lái)拆解盡量讓你看完就能在自己的騰訊云賬號(hào)里復(fù)現(xiàn)出一個(gè)真正能用的 Agent 項(xiàng)目。這篇文章的定位不是給你念一遍官方文檔而是告訴你文檔沒寫明的那 30% 關(guān)鍵細(xì)節(jié)。1.1 從“會(huì)聊天”到“會(huì)干活”Agent 缺的是技能層很多人對(duì) Agent 的理解還停留在“一個(gè)聊天機(jī)器人 調(diào)用大模型”。這種理解只能支撐 Demo支撐不了真實(shí)業(yè)務(wù)。因?yàn)檎鎸?shí)業(yè)務(wù)里大模型只是“大腦”它需要一套可編排的“手腳”才能做正經(jīng)事這套手腳就是技能層。如果把 Agent 拆開看應(yīng)該是三層理解層負(fù)責(zé)意圖識(shí)別和任務(wù)規(guī)劃決策層負(fù)責(zé)根據(jù)上下文選擇執(zhí)行路徑執(zhí)行層負(fù)責(zé)真正調(diào)用工具、查數(shù)據(jù)庫(kù)、寫文件、發(fā)請(qǐng)求。AI Skills 正好填補(bǔ)的是執(zhí)行層的能力沉淀。沒有技能層模型再聰明也拿不到實(shí)時(shí)訂單數(shù)據(jù)沒法操作業(yè)務(wù)后臺(tái)更不可能完成多步驟的信息整合。我在項(xiàng)目里通常會(huì)把技能按“原子技能”和“復(fù)合技能”兩類來(lái)設(shè)計(jì)。原子技能對(duì)應(yīng)一個(gè)獨(dú)立 API 或工具調(diào)用比如“根據(jù)訂單號(hào)查詢訂單”復(fù)合技能則由多個(gè)原子技能串聯(lián)比如“查詢訂單 → 計(jì)算優(yōu)惠 → 生成客服回復(fù)”。這個(gè)分層好處非常明顯單個(gè)技能出了問(wèn)題我可以單獨(dú)測(cè)、單獨(dú)修不用整條鏈路上線回滾。還有一個(gè)容易忽略的價(jià)值點(diǎn)技能層的存在讓 Agent 可以“越用越強(qiáng)”。每新增一個(gè)業(yè)務(wù)場(chǎng)景不需要重寫 Agent 邏輯只需要在技能庫(kù)里注冊(cè)一個(gè)新的技能描述然后讓模型在規(guī)劃階段“看得到”這個(gè)技能就行了。這也是為什么 Skill 與 Agent 框架的關(guān)系更像“插件系統(tǒng)與主程序”的關(guān)系而不是“函數(shù)與調(diào)用方”的耦合關(guān)系。1.2 Skills 與 Agent 框架的分工邊界到底怎么劃我見過(guò)不少團(tuán)隊(duì)的架構(gòu)圖上把 Skills、Agent、模型全部畫在一層里看起來(lái)沒啥問(wèn)題但真到寫代碼時(shí)就犯糊涂了。我建議用下面這個(gè)分工方式來(lái)劃邊界。Agent 框架只做三件事“理解用戶訴求、拆解執(zhí)行步驟、維護(hù)會(huì)話記憶”。模型在這里充當(dāng)推理引擎不直接接觸數(shù)據(jù)庫(kù)也不直接調(diào)外部API。而 AI Skills 對(duì)外暴露的是“能力描述 入?yún)⒊鰠⒍x 實(shí)際執(zhí)行邏輯”它不需要關(guān)心當(dāng)前對(duì)話里用戶的情緒也不需要維護(hù)上下文狀態(tài)只管把輸入?yún)?shù)消費(fèi)掉返回一個(gè)結(jié)構(gòu)化結(jié)果。這樣劃分之后好處特別實(shí)際第一技能可以被多個(gè) Agent 復(fù)用比如訂單查詢技能售前 Agent 能用售后 Agent 也能用第二技能的上線可以通過(guò)配置完成不需要改 Agent 代碼第三不同的技能可以由不同團(tuán)隊(duì)各自維護(hù)職責(zé)邊界清晰不會(huì)出現(xiàn)“牽一發(fā)動(dòng)全身”的恐怖局面。在騰訊云 AI Skills 的實(shí)踐里我最滿意的是它對(duì)“技能描述”的重視。系統(tǒng)會(huì)要求你為每個(gè)技能寫清楚“功能描述、適用場(chǎng)景、參數(shù)說(shuō)明、輸出格式”這段描述直接影響模型路由的準(zhǔn)確率。你如果偷懶只寫一句“查詢訂單”模型很容易在相似場(chǎng)景下調(diào)用錯(cuò)技能寫清楚“當(dāng)用戶咨詢包裹物流或訂單狀態(tài)時(shí)使用此技能輸入?yún)?shù)為訂單號(hào)或手機(jī)號(hào)”路由準(zhǔn)確率會(huì)立刻上一個(gè)臺(tái)階。1.3 為什么拿騰訊云做技能訓(xùn)練場(chǎng)而不是本地裸跑也許你會(huì)問(wèn)Skills 這套設(shè)計(jì)我在本地用 Python 也能搭為什么非得用騰訊云我的回答是本地搭一套技能框架確實(shí)不難難的是“模型服務(wù)、技能注冊(cè)、可靠調(diào)度、日志追蹤”這幾件事的集成度騰訊云在這里確實(shí)能幫我們省下大量基建時(shí)間。首先騰訊云的模型服務(wù)通過(guò)統(tǒng)一網(wǎng)關(guān)對(duì)外提供服務(wù)你在代碼里既可以用官方大模型也可以接自部署的開源模型切換成本很低。其次AI Skills 的服務(wù)托管幫你處理了鑒權(quán)、限流、監(jiān)控這些“臟活”這對(duì)中小團(tuán)隊(duì)尤其重要畢竟不是每個(gè)人都有專門的運(yùn)維人力來(lái)盯服務(wù)穩(wěn)定性。另外騰訊云在國(guó)內(nèi)的節(jié)點(diǎn)覆蓋和合規(guī)備案做得比較省心。公司項(xiàng)目要過(guò)等保、要審計(jì)本地裸跑技能服務(wù)的話很多東西從零開始搞周期長(zhǎng)、成本高。而云上直接帶上云日志、訪問(wèn)管理、密鑰管理等現(xiàn)成能力能幫助你把精力集中在“技能本身的業(yè)務(wù)邏輯”上而不是整天折騰底層環(huán)境?？梢哉f(shuō)這與我的實(shí)際需求是比較貼合的。2. 環(huán)境準(zhǔn)備與基礎(chǔ)配置開通服務(wù)、搭好運(yùn)行環(huán)境在寫任何代碼之前先把環(huán)境跑通。很多人習(xí)慣一上來(lái)就寫業(yè)務(wù)邏輯結(jié)果測(cè)試時(shí)發(fā)現(xiàn)調(diào)用不通回頭再排查網(wǎng)絡(luò)、鑒權(quán)、依賴?yán)速M(fèi)時(shí)間不說(shuō)還容易懷疑人生。這里我直接把一套最省心的基礎(chǔ)環(huán)境準(zhǔn)備流程給你列出來(lái)。2.1 從注冊(cè)到開通 AI Skills 服務(wù)的完整路徑假如你現(xiàn)在是第一次用騰訊云注冊(cè)賬號(hào)這一步就不多說(shuō)了建議直接使用企業(yè)認(rèn)證后面調(diào)用模型服務(wù)和企業(yè)級(jí)技能托管時(shí)權(quán)限會(huì)寬很多。登錄控制臺(tái)之后在搜索框輸入“AI Skills”或者“智能體”進(jìn)入產(chǎn)品頁(yè)點(diǎn)擊開通服務(wù)。首次開通時(shí)系統(tǒng)會(huì)讓你選擇運(yùn)行區(qū)域盡量選靠近你業(yè)務(wù)用戶的區(qū)域比如業(yè)務(wù)集中在華東就選上海這樣接口延遲會(huì)低一些。開通服務(wù)之后建議順手把“訪問(wèn)密鑰”準(zhǔn)備好。在騰訊云控制臺(tái)的訪問(wèn)管理 CAM 里創(chuàng)建子用戶并為該子用戶關(guān)聯(lián) AI Skills 相關(guān)的策略權(quán)限然后生成 SecretId 和 SecretKey。這里我多說(shuō)一句千萬(wàn)不要用根賬號(hào)的密鑰跑到代碼里一旦代碼倉(cāng)庫(kù)泄露后果不堪設(shè)想。我們用子用戶密鑰配好最小權(quán)限夠用就行。最后到模型服務(wù)控制臺(tái)里確認(rèn)一下是否已經(jīng)開通你計(jì)劃使用的大模型服務(wù)。通常官方默認(rèn)的模型比如混元系列或 DeepSeek 相關(guān)版本會(huì)在你開通產(chǎn)品時(shí)一并可用。如果你想接入自部署的模型需要在模型服務(wù)里創(chuàng)建“接入點(diǎn)”拿到對(duì)應(yīng)的 Endpoint 地址這個(gè)地址下一步會(huì)用到 Skill 配置里。2.2 用 Cloud Shell 還是本地 CLI 對(duì)接我的建議騰訊云提供了兩種常見的對(duì)接方式一是直接使用網(wǎng)頁(yè)版的 Cloud Shell二是本地安裝并配置騰訊云 CLI。我的建議是如果只是做實(shí)驗(yàn)、跑 Demo直接用 Cloud Shell 最省心打開即用網(wǎng)絡(luò)環(huán)境已經(jīng)幫你配置好了不用處理本地代理之類的問(wèn)題但如果要持續(xù)開發(fā)、要集成到 CI/CD 流程里就必須配置本地 CLI保證本機(jī)與云端鑒權(quán)一致。本地 CLI 配置流程也不復(fù)雜。先安裝騰訊云 CLI 工具支持主流操作系統(tǒng)然后在命令行里執(zhí)行配置命令輸入 SecretId、SecretKey 和默認(rèn)地域。配好之后建議先執(zhí)行一條簡(jiǎn)單的查詢命令測(cè)通比如查詢當(dāng)前賬號(hào)下的服務(wù)列表返回正常就說(shuō)明鑒權(quán)和網(wǎng)絡(luò)都沒問(wèn)題。還有一個(gè)細(xì)節(jié)很多人容易忽略AI Skills 的接口調(diào)用對(duì) Python 版本有要求官方 SDK 推薦 3.8 以上。如果你本地默認(rèn) Python 還是 3.6 或者更老建議用虛擬環(huán)境管理工具比如 conda 或 venv單獨(dú)創(chuàng)建一個(gè) Python 3.11 的環(huán)境避免將來(lái)依賴沖突。我項(xiàng)目里一直用 Python 3.11跑騰訊云 SDK 和主流 Agent 框架都很穩(wěn)。2.3 干凈的項(xiàng)目目錄是之后不崩潰的前提環(huán)境配好了接下來(lái)創(chuàng)建項(xiàng)目。我習(xí)慣的性能項(xiàng)目結(jié)構(gòu)大概是這樣的一個(gè)主目錄下分為 config 存放全局配置和技能注冊(cè)信息skills 存放各類技能實(shí)現(xiàn)core 存放 Agent 編排邏輯 tests 存放技能與鏈路的測(cè)試腳本logs 存放運(yùn)行日志。這套結(jié)構(gòu)未必最先進(jìn)但勝在直觀團(tuán)隊(duì)協(xié)作時(shí)新成員上手也快。在 config 里我會(huì)專門放一個(gè)skills_config.yaml它是技能注冊(cè)的“戶口本”每個(gè)技能的名字、描述、入?yún)⒊鰠⒍x、對(duì)應(yīng)的執(zhí)行模塊都寫在這個(gè)文件里。騰訊云 AI Skills 控制臺(tái)同樣支持配置技能元信息但我自己的經(jīng)驗(yàn)是先用代碼維護(hù)一份文件測(cè)試通過(guò)后再同步到云端這樣技能演進(jìn)過(guò)程有記錄可查也比直接在網(wǎng)頁(yè)上改來(lái)改去更可控。我建議在項(xiàng)目根目錄加一份requirements.txt或pyproject.toml把需要用到的依賴固定好版本。騰訊云官方 SDK、OpenAI 兼容客戶端如果需要、pydantic用于參數(shù)校驗(yàn)、pytest測(cè)試用都是基礎(chǔ)配置。依賴版本一定要鎖死否則過(guò)兩個(gè)月項(xiàng)目重裝環(huán)境時(shí)SDK 批量升級(jí)很容易把接口搞掛。3. 從零實(shí)現(xiàn)一個(gè)“能查訂單、能算優(yōu)惠”的 Agent Skills環(huán)境好了抽象概念講再多也得落地。這一節(jié)我用一個(gè)具體場(chǎng)景來(lái)演示一個(gè)電商客服 Agent需要支持“查詢訂單狀態(tài)”和“計(jì)算優(yōu)惠金額”兩個(gè)技能然后讓 Agent 能根據(jù)用戶描述自動(dòng)調(diào)用對(duì)應(yīng)技能并把兩個(gè)技能串聯(lián)起來(lái)處理復(fù)雜問(wèn)題。3.1 先寫標(biāo)準(zhǔn)技能描述文件這一步別偷懶在寫業(yè)務(wù)邏輯之前先來(lái)寫技能描述。我見過(guò)太多人跳過(guò)這步直接寫函數(shù)結(jié)果模型路由不準(zhǔn)回頭又怪框架不好用。實(shí)際上大模型靠的是“描述文字”來(lái)理解技能用途描述質(zhì)量直接決定路由效果。一個(gè)科學(xué)的技能描述至少要包含幾個(gè)要素。技能名稱簡(jiǎn)短且唯一比如query_order_status。功能描述詳細(xì)說(shuō)明該技能“在什么情況下觸發(fā)”、“做什么事”、“不做什么事”。入?yún)⒍x參數(shù)名、類型、是否必填、默認(rèn)值、取值范圍。輸出格式建議結(jié)構(gòu)化為 JSON方便下游解析。示例給一個(gè)完整的調(diào)用示例方便模型理解。我拿訂單查詢技能舉例name: query_order_status description: | 當(dāng)用戶咨詢訂單狀態(tài)、物流進(jìn)度、發(fā)貨時(shí)間等問(wèn)題時(shí)使用此技能。 輸入?yún)?shù)可以是訂單號(hào)order_id也可以是用戶手機(jī)號(hào)phone。 如果兩個(gè)參數(shù)都未提供返回錯(cuò)誤提示。 parameters: order_id: type: string required: false description: 訂單號(hào)通常為數(shù)字和字母組合 phone: type: string required: false description: 用戶下單手機(jī)號(hào) output: type: object properties: order_status: type: string description: 訂單狀態(tài)pending/shipped/delivered/cancelled shipping_progress: type: string description: 物流進(jìn)度描述 estimated_arrival: type: string description: 預(yù)計(jì)送達(dá)日期 example: | 輸入: {order_id: DD20240516001} 輸出: {order_status: shipped, shipping_progress: 包裹已到達(dá)杭州轉(zhuǎn)運(yùn)中心, estimated_arrival: 2024-05-20}寫完之后不要急著進(jìn)入下一步先在項(xiàng)目里把這份 yaml 用 pydantic 校驗(yàn)一遍確保格式合法再去控制臺(tái)創(chuàng)建或同步到云端。很多路由問(wèn)題根源就是寫入控制臺(tái)時(shí)的 YAML 縮進(jìn)寫錯(cuò)了這是最基礎(chǔ)也最容易犯的錯(cuò)誤。3.2 業(yè)務(wù)邏輯實(shí)現(xiàn)訂單查詢與優(yōu)惠計(jì)算要注意什么技能描述寫好之后接下來(lái)就是實(shí)現(xiàn)真實(shí)業(yè)務(wù)邏輯。訂單查詢技能我在本地用一個(gè)模擬數(shù)據(jù)源來(lái)做方便你復(fù)現(xiàn)請(qǐng)求進(jìn)來(lái)之后先做參數(shù)校驗(yàn)然后從內(nèi)存數(shù)據(jù)字典或數(shù)據(jù)庫(kù)里查出對(duì)應(yīng)訂單最后返回標(biāo)準(zhǔn) JSON。# skills/order_skill.py import re from typing import Dict, Optional MOCK_ORDERS { DD20240516001: { order_status: shipped, shipping_progress: 包裹已到達(dá)杭州轉(zhuǎn)運(yùn)中心, estimated_arrival: 2024-05-20, amount: 199.00, }, DD20240517002: { order_status: delivered, shipping_progress: 包裹已簽收, estimated_arrival: 2024-05-18, amount: 89.00, }, } def query_order_status(order_id: Optional[str] None, phone: Optional[str] None) - Dict: if not order_id and not phone: return {error: order_id 和 phone 至少需要提供一個(gè)} # 簡(jiǎn)單校驗(yàn)order_id 格式檢查 if order_id and not re.fullmatch(rDD\d{8,}, order_id): return {error: order_id 格式不正確} # 實(shí)際項(xiàng)目中這里查數(shù)據(jù)庫(kù)演示環(huán)境用本地字典 order MOCK_ORDERS.get(order_id) if not order: return {error: f未找到訂單: {order_id}} return { order_status: order[order_status], shipping_progress: order[shipping_progress], estimated_arrival: order[estimated_arrival], }優(yōu)惠計(jì)算技能輸入商品原價(jià)和用戶等級(jí)輸出優(yōu)惠金額和最終價(jià)。# skills/discount_skill.py from typing import Dict, Union VIp_RATE { normal: 0.0, silver: 0.05, gold: 0.10, platinum: 0.20, } def calc_discount(price: Union[float, int], user_level: str normal) - Dict: rate VIP_RATE.get(user_level, 0.0) discount_amount round(float(price) * rate, 2) final_price round(float(price) - discount_amount, 2) return { original_price: float(price), user_level: user_level, discount_rate: rate, discount_amount: discount_amount, final_price: final_price, }業(yè)務(wù)邏輯本身不難難在邊界情況。比如訂單號(hào)為空、價(jià)格傳負(fù)數(shù)、用戶等級(jí)不存在這些情況技能內(nèi)部都必須兜住異常不能讓異常穿透到 Agent 層。一個(gè)經(jīng)驗(yàn)法則技能層永遠(yuǎn)返回結(jié)構(gòu)化結(jié)果要么返回業(yè)務(wù)數(shù)據(jù)要么返回錯(cuò)誤描述絕不拋異常。只有這樣才能保證 Agent 在拿到錯(cuò)誤結(jié)果后還能繼續(xù)與用戶對(duì)話而不是直接崩潰。3.3 把 Skills 寫成服務(wù)暴露給 Agent 調(diào)度技能函數(shù)寫好之后下一步就是把它們暴露出來(lái)讓 Agent 可以被網(wǎng)絡(luò)調(diào)用。我見過(guò)不少團(tuán)隊(duì)直接把函數(shù) import 到 Agent 框架里用這在單體項(xiàng)目里沒問(wèn)題但一旦技能多了、要獨(dú)立部署或灰度發(fā)布時(shí)這種方式就非常難受。所以這里我建議走“技能即服務(wù)”的路線。在騰訊云上最簡(jiǎn)單的做法是把技能實(shí)現(xiàn)為一個(gè) HTTP 服務(wù)部署到云函數(shù)、容器服務(wù)或者輕量服務(wù)器上然后在 AI Skills 控制臺(tái)配置為外部服務(wù)。Agent 發(fā)起調(diào)用時(shí)通過(guò)約定的 API 地址完成調(diào)用。我用 FastAPI 寫了個(gè)輕量服務(wù)把兩個(gè)技能封裝成 HTTP 接口# server.py from fastapi import FastAPI from pydantic import BaseModel from typing import Optional from skills.order_skill import query_order_status from skills.discount_skill import calc_discount app FastAPI() class OrderRequest(BaseModel): order_id: Optional[str] None phone: Optional[str] None class DiscountRequest(BaseModel): price: float user_level: str normal app.post(/api/query_order_status) def order_status(req: OrderRequest): return query_order_status(order_idreq.order_id, phonereq.phone) app.post(/api/calc_discount) def discount(req: DiscountRequest): return calc_discount(pricereq.price, user_levelreq.user_level)這樣設(shè)計(jì)有一個(gè)非常實(shí)際的好處每個(gè)技能服務(wù)都可以單獨(dú)測(cè)試、單獨(dú)擴(kuò)容。訂單查詢流量大了給訂單服務(wù)擴(kuò)容優(yōu)惠計(jì)算邏輯迭代了只發(fā)布優(yōu)惠服務(wù)互不影響。相比把技能函數(shù)全堆在 Agent 進(jìn)程里這個(gè)架構(gòu)在真實(shí)業(yè)務(wù)里能少踩一半的運(yùn)維坑。3.4 參數(shù)調(diào)優(yōu)與成本控制的三個(gè)關(guān)鍵配置技能服務(wù)上線之后緊接著要考慮的其實(shí)是成本控制。大模型推理是按 Token 計(jì)費(fèi)的Agent 在會(huì)話中如果反復(fù)調(diào)用技能、返回長(zhǎng)文本費(fèi)用會(huì)蹭蹭地漲。我在這塊總結(jié)了三個(gè)很關(guān)鍵的控制點(diǎn)。第一是設(shè)置合理的模型溫度參數(shù)。對(duì) Agent 場(chǎng)景來(lái)說(shuō)temperature 建議控制在 0.2 到 0.4 之間溫度太高容易讓模型“自由發(fā)揮”編造技能參數(shù)導(dǎo)致調(diào)用出問(wèn)題。第二是限制技能返回結(jié)果的最大 Token 數(shù)。很多時(shí)候 Agent 只需要一個(gè)結(jié)論不需要完整的長(zhǎng)文本詳情在技能返回層直接截?cái)嗷蚍庋b成精簡(jiǎn)格式能省不少 Token 費(fèi)用。第三是設(shè)計(jì)好模型最大重試次數(shù)。當(dāng)模型調(diào)用技能失敗時(shí)給它一兩次機(jī)會(huì)重新生成參數(shù)是可以的但沒必要無(wú)限重試容易拖慢響應(yīng)也燒錢。這里我提供一個(gè)思路在調(diào)用模型接口時(shí)騰訊云模型服務(wù)或者兼容 OpenAI 的客戶端里通常支持max_tokens、temperature、stop參數(shù)把這三個(gè)參數(shù)按場(chǎng)景預(yù)置到配置里。比如客服場(chǎng)景我會(huì)把 max_tokens 設(shè)為 512temperature 設(shè)為 0.3stop 設(shè)置為空這樣大多數(shù)情況下響應(yīng)質(zhì)量和成本能達(dá)到一個(gè)不錯(cuò)的平衡點(diǎn)。# config/model_config.py MODEL_CONFIG { temperature: 0.3, max_tokens: 1024, top_p: 0.9, timeout: 30, }4. 核心流程實(shí)現(xiàn)注冊(cè)技能、編排聯(lián)調(diào)、跑通全鏈路技能服務(wù)就緒后剩下的事情就是把它們“教會(huì)”給 Agent 用。這一階段的核心流程包括在騰訊云控制臺(tái)完成技能注冊(cè)、在 Agent 編排層配置技能調(diào)用規(guī)則、最終跑通一條真實(shí)用戶請(qǐng)求的端到端鏈路。4.1 在 Agent 構(gòu)建平臺(tái)中注冊(cè)技能注意哪些字段登錄騰訊云 AI Skills 控制臺(tái)進(jìn)入“技能管理”頁(yè)面創(chuàng)建一個(gè)新技能。你會(huì)看到幾個(gè)關(guān)鍵的輸入字段技能名稱、技能描述、請(qǐng)求地址HTTP 接口地址、請(qǐng)求方法、入?yún)⒊鰠?Schema。這里我要特別強(qiáng)調(diào)“技能描述”和“入?yún)⒊鰠?Schema”這兩個(gè)字段它們決定模型能不能準(zhǔn)確“看懂”你的技能。技能描述要盡量用業(yè)務(wù)語(yǔ)言來(lái)寫最好包含觸發(fā)條件。比如“當(dāng)用戶想要查詢訂單物流狀態(tài)時(shí)調(diào)用此接口傳入訂單號(hào)”這比只寫“訂單查詢”要精確得多。入?yún)⒊鰠?Schema 建議按照 JSON Schema 規(guī)范嚴(yán)格定義。如果定義模糊模型在推理時(shí)無(wú)法猜測(cè)到底該傳什么字段值很容易因?yàn)閰?shù)缺失導(dǎo)致接口報(bào)錯(cuò)。注冊(cè)完成后控制臺(tái)會(huì)生成一個(gè)技能 ID。后面在 Agent 編排層配置工具調(diào)用時(shí)引用的是這個(gè)技能 ID。如果你像我的習(xí)慣一樣在本地 yaml 里維護(hù)了一份技能描述此時(shí)需要做一次比對(duì)本地代碼中的描述字段與控制臺(tái)是否一致。開發(fā)環(huán)境經(jīng)常出現(xiàn)改了一處卻忘記同步的情況最后發(fā)現(xiàn)問(wèn)題時(shí)排查成本很高。4.2 Agent 多技能編排的會(huì)話策略怎么設(shè)置才合理注冊(cè)完技能接著配置 Agent 編排。騰訊云的 Agent 構(gòu)建平臺(tái)或者你自選的開源框架一般允許配置系統(tǒng)提示詞、技能列表和會(huì)話策略。系統(tǒng)提示詞是 Agent 的總綱它決定了 Agent 怎么拆解用戶的復(fù)雜訴求。比如對(duì)于我們的電商客服場(chǎng)景系統(tǒng)提示詞我會(huì)這么寫你是一個(gè)電商客服助手當(dāng)用戶詢問(wèn)訂單狀態(tài)時(shí)調(diào)用查詢訂單技能當(dāng)用戶詢問(wèn)價(jià)格優(yōu)惠時(shí)調(diào)用計(jì)算優(yōu)惠技能。如果用戶的問(wèn)題同時(shí)涉及多個(gè)技能先查詢訂單再根據(jù)訂單金額計(jì)算優(yōu)惠。這段提示詞的“編排暗示”非常重要它相當(dāng)于給模型的規(guī)劃過(guò)程畫了一條輕量級(jí)的業(yè)務(wù)規(guī)則。會(huì)話策略方面重點(diǎn)關(guān)注上下文長(zhǎng)度管理。AI Agent 多輪對(duì)話時(shí)上下文會(huì)不斷累積到達(dá)模型上限后要么截?cái)?、要么?bào)錯(cuò)。我建議設(shè)置一個(gè) token 閾值比如超過(guò) 4000 tokens 時(shí)自動(dòng)精簡(jiǎn)歷史消息只保留最近兩輪完整對(duì)話和系統(tǒng)提示詞、之前輪次生成的關(guān)鍵結(jié)論。騰訊云 AI Skills 的配置項(xiàng)里通常有相關(guān)參數(shù)可調(diào)還是要根據(jù)實(shí)際業(yè)務(wù)測(cè)試后選擇一個(gè)合理的閾值。4.3 聯(lián)調(diào)實(shí)錄一次完整對(duì)話的完整追蹤過(guò)程配置好這一切之后我們從用戶視角來(lái)跑一遍完整鏈路然后追蹤系統(tǒng)日志。用戶提問(wèn)“我的訂單 DD20240516001 什么時(shí)候能到我現(xiàn)在是金牌會(huì)員還能便宜多少”這個(gè)過(guò)程 Agent 內(nèi)部大致會(huì)經(jīng)歷幾個(gè)階段一是意圖拆解模型判斷該問(wèn)題涉及“查詢訂單狀態(tài)”和“計(jì)算優(yōu)惠”兩個(gè)技能二是編排計(jì)劃模型生成調(diào)用序列計(jì)劃先調(diào)訂單查詢、再調(diào)優(yōu)惠計(jì)算三是技能執(zhí)行Agent 框架依次調(diào)用兩個(gè)技能四是匯總答案模型根據(jù)兩個(gè)技能結(jié)果組織最終回復(fù)包含訂單到達(dá)時(shí)間、優(yōu)惠金額、最終價(jià)格。全程日志追蹤我會(huì)用一個(gè)請(qǐng)求 ID 貫穿。具體方法是入口處生成 Request ID在每個(gè)技能調(diào)用處將 Request ID 寫入 Headers這樣即使鏈路很長(zhǎng)也能從日志平臺(tái)把一次請(qǐng)求的完整調(diào)用鏈拖出來(lái)排查。我在實(shí)踐中發(fā)現(xiàn)沒有統(tǒng)一請(qǐng)求 ID出了問(wèn)題連“哪個(gè)技能在哪個(gè)環(huán)節(jié)報(bào)錯(cuò)”都說(shuō)不清這是 Agent 項(xiàng)目排查中最大的痛點(diǎn)之一。模擬執(zhí)行之后你要驗(yàn)證兩件事第一兩個(gè)技能是否正確返回結(jié)果第二模型的最終回復(fù)是否把技能結(jié)果用對(duì)了。如果模型明明拿到了訂單金額卻不計(jì)算優(yōu)惠很可能是系統(tǒng)提示詞里沒把“金牌會(huì)員可以打折”的業(yè)務(wù)規(guī)則交代清楚。這種問(wèn)題不是技能本身有問(wèn)題而是 Agent 的業(yè)務(wù)規(guī)則配置不夠具體這也是 Agent 落地時(shí)最常遇到的隱性坑。5. 常見問(wèn)題與排查技巧實(shí)錄Agent 項(xiàng)目調(diào)試階段的體驗(yàn)和傳統(tǒng)后端有明顯區(qū)別傳統(tǒng)后端請(qǐng)求響應(yīng)結(jié)果是確定性的而 Agent 環(huán)節(jié)里模型推理有隨機(jī)性出錯(cuò)位置也不好復(fù)現(xiàn)。我把這段時(shí)間實(shí)際踩過(guò)的坑、排查出來(lái)的心得記錄如下。5.1 技能觸發(fā)不準(zhǔn)Agent 總是接錯(cuò)話癥狀是用戶明明在問(wèn)物流Agent 卻調(diào)用了優(yōu)惠計(jì)算技能。這種問(wèn)題非常常見我排查的順序是這樣的。第一步檢查技能描述是否清晰。描述太泛、太短是首要原因模型無(wú)法理解技能的邊界。這里我給一個(gè)對(duì)比模糊寫法是“物流查詢”建議寫“當(dāng)用戶需要了解包裹運(yùn)輸進(jìn)度、快遞當(dāng)前位置、預(yù)計(jì)送達(dá)時(shí)間時(shí)調(diào)用本技能。輸入訂單號(hào)或手機(jī)號(hào)”效果差別很明顯。第二步檢查是否有復(fù)數(shù)技能之間描述重合。比如“訂單查詢”和“售后查詢”都寫了“用戶詢問(wèn)訂單相關(guān)信息時(shí)調(diào)用”模型當(dāng)然會(huì)犯迷糊。解決方式是明確區(qū)別給每個(gè)技能劃定更專屬的觸發(fā)詞和場(chǎng)景。第三步檢查系統(tǒng)提示詞是否做了強(qiáng)約束。如果業(yè)務(wù)規(guī)則允許可以在系統(tǒng)提示詞里直接寫明“涉及物流狀態(tài)一律優(yōu)先調(diào)用查詢訂單技能”這能極大提升命中率。如果這三點(diǎn)都排查完還是不準(zhǔn)可以在各技能內(nèi)部打印一段可觀測(cè)日志記錄“某個(gè)技能被調(diào)用時(shí)模型的完整推理過(guò)程”定位模型到底為什么選擇錯(cuò)了。這一步需要底層框架支持中間過(guò)程輸出不是所有平臺(tái)都開放但如果調(diào)試環(huán)境允許價(jià)值非常大。5.2 技能請(qǐng)求超時(shí)與并發(fā)限制怎么破Agent 場(chǎng)景有個(gè)很特殊的問(wèn)題模型調(diào)度外部技能外部技能響應(yīng)時(shí)間一長(zhǎng)模型那邊會(huì)先一步超時(shí)導(dǎo)致 Agent 報(bào)錯(cuò)。我在騰訊云上實(shí)踐時(shí)遇到過(guò)幾次技能服務(wù)響應(yīng)超過(guò) 10 秒的情況結(jié)果 Agent 直接中斷。排查后發(fā)現(xiàn)是兩個(gè)原因一是技能服務(wù)內(nèi)部有慢 SQL二是云函數(shù)冷啟動(dòng)過(guò)慢。對(duì)前者我給訂單表加了索引對(duì)后者我把云函數(shù)最小實(shí)例數(shù)從 0 調(diào)到了 1減少冷啟動(dòng)概率。這一改成功率提升明顯。并發(fā)限制方面需要注意騰訊云上的限流配置。默認(rèn)限流閾值可能適合 Demo但真實(shí)業(yè)務(wù)一旦流量上來(lái)需要提前評(píng)估峰值 QPS并在控制臺(tái)調(diào)整限流策略。反過(guò)來(lái)如果 Agent 長(zhǎng)時(shí)間高頻調(diào)用某個(gè)技能也需要在技能服務(wù)側(cè)做好降級(jí)方案比如返回緩存數(shù)據(jù)而不是直接報(bào)錯(cuò)。我們做客服場(chǎng)景的時(shí)候如果一個(gè)用戶的訂單查詢因并發(fā)觸發(fā)限流直接返回“系統(tǒng)繁忙”的體驗(yàn)并不好更好的方式是返回一個(gè)降級(jí)提示“訂單正在反復(fù)核驗(yàn)中請(qǐng)稍后刷新”這樣交互上不會(huì)太生硬。5.3 鑒權(quán)與安全踩坑密鑰泄露才是最大的雷Agent 項(xiàng)目中技能服務(wù)往往有調(diào)用權(quán)限能查數(shù)據(jù)庫(kù)、操作業(yè)務(wù)后臺(tái)所以鑒權(quán)安全問(wèn)題不可忽視。我在早期項(xiàng)目中為了圖方便直接把騰訊云的 SecretKey 寫在代碼環(huán)境變量里結(jié)果有一次不小心把環(huán)境變量文件提交到了 Git 倉(cāng)庫(kù)雖然及時(shí)發(fā)現(xiàn)并回收了密鑰但想起來(lái)仍然有些后怕這件事之后我就規(guī)范了密鑰管理方式。規(guī)范的做法是云上的訪問(wèn)密鑰不使用根賬號(hào)密鑰而是創(chuàng)建子賬號(hào)并授予最小權(quán)限同時(shí)啟用騰訊云的密鑰管理系統(tǒng)KMS或者使用環(huán)境變量的方式注入運(yùn)行時(shí)不讓密鑰出現(xiàn)在代碼倉(cāng)庫(kù)里。技能服務(wù)之間的調(diào)用可以使用 JWT 或者內(nèi)部簽名機(jī)制確保只有 Agent 編排層可以調(diào)用暴露出來(lái)的接口。如果你用的是云函數(shù)部署技能服務(wù)可以關(guān)閉公網(wǎng)訪問(wèn)只在 VPC 內(nèi)網(wǎng)與 Agent 編排層通信這相當(dāng)于把技能服務(wù)藏在了內(nèi)網(wǎng)外部無(wú)法直接訪問(wèn)安全系數(shù)會(huì)高很多。5.4 用日志和追蹤打造屬于自己的排障工作臺(tái)Agent 項(xiàng)目調(diào)試中我強(qiáng)烈建議你從一開始就把日志系統(tǒng)建好。不要等項(xiàng)目出問(wèn)題再補(bǔ)因?yàn)?Agent 的調(diào)用鏈路長(zhǎng)、不確定性高沒有日志幾乎等于盲人摸象。我在項(xiàng)目里會(huì)記錄三類日志一是入?yún)⑷罩居涗浻脩粼驾斎?、Agent 生成的調(diào)用計(jì)劃二是技能執(zhí)行日志記錄每個(gè)技能的入?yún)?、出參、耗時(shí)和錯(cuò)誤信息三是模型推理日志記錄大模型每次調(diào)用的 token 數(shù)、溫度、最終響應(yīng)。三類日志用請(qǐng)求 ID 串聯(lián)配合騰訊云日志服務(wù)做檢索排障速度會(huì)大幅提升。這里我分享一個(gè)排查技巧在 Agent 編排層不返回報(bào)錯(cuò)詳情給終端用戶但完整日志直接打到云端。這樣做既避免把內(nèi)部系統(tǒng)信息暴露給用戶又不影響開發(fā)人員查問(wèn)題。很多 Agent 平臺(tái)有“思考過(guò)程”追蹤功能強(qiáng)烈建議開啟實(shí)際調(diào)試時(shí)能讓你直觀看到模型是如何做技能決策的看著它一步步想比只看最終結(jié)果好太多。6. 一些額外的優(yōu)化建議與個(gè)人實(shí)踐心得最后這部分我把我實(shí)際操作中總結(jié)的一些體會(huì)分享出來(lái)也許能幫你少走一點(diǎn)彎路。第一技能注冊(cè)的版本管理非常重要。我在實(shí)踐中發(fā)現(xiàn)技能服務(wù)一旦發(fā)布上線后續(xù)迭代就不可避免。如果每次都直接改線上技能配置出了問(wèn)題想回滾都難。建議在技能描述里增加一個(gè)版本號(hào)字段或者在本地 git 里給技能配置單獨(dú)建一個(gè)目錄每次修改發(fā)版都有記錄。騰訊云 AI Skills 控制臺(tái)支持創(chuàng)建新版本建議養(yǎng)成“新版本驗(yàn)證通過(guò)后再發(fā)布”的習(xí)慣這個(gè)過(guò)程可能多花十幾分鐘但遠(yuǎn)比線上事故的恢復(fù)成本低得多。第二Agent 測(cè)試不能只測(cè)正常路徑。真實(shí)世界里用戶提問(wèn)千奇百怪我今天測(cè)試了幾十條異常輸入包括不存在的訂單號(hào)、含糊的“幫我看看我的訂單”、只給手機(jī)號(hào)的查詢。每條異常輸入都整理成測(cè)試用例沉淀到 automated tests 里。以后每次改技能描述或模型配置把全量測(cè)試跑一遍能防住大部分回歸問(wèn)題。第三騰訊云 AI Skills 與開源 Agent 框架的兼容性其實(shí)是超預(yù)期的。最初我以為只能在騰訊云自家平臺(tái)里玩后來(lái)發(fā)現(xiàn)通過(guò)標(biāo)準(zhǔn) HTTP 技能接口定義同樣可以被主流 Agent 框架作為“外部工具”注冊(cè)使用。這意味著你完全可以“云上托管技能、本地編排 Agent”靈活性很高。如果你團(tuán)隊(duì)已有自研 Agent 框架不要被“全家桶”的心理預(yù)設(shè)限制完全可以只選騰訊云服務(wù)里對(duì)你最有價(jià)值的那一兩個(gè)能力來(lái)用。第四也是最想強(qiáng)調(diào)的一點(diǎn)Agent 項(xiàng)目的復(fù)雜度主要來(lái)自技能層而不是模型層。模型能力再?gòu)?qiáng)技能描述混亂、服務(wù)不穩(wěn)定、日志缺失Agent 照樣沒法用。先把技能層像基礎(chǔ)設(shè)施一樣認(rèn)真對(duì)待Agent 才能成為真正可靠的生產(chǎn)力工具。這也是我做這個(gè)“全能 Agent 養(yǎng)成記”系列最想傳遞的東西。如果你也正在騰訊云上折騰 Agent 和 AI Skills希望這篇實(shí)踐記錄能給你省下一些不必要的調(diào)試時(shí)間。每個(gè)人項(xiàng)目實(shí)施環(huán)境不同坑的位置也不會(huì)完全一樣但底層思路是相通。如果你在實(shí)踐過(guò)程中有更好的技巧或踩到了不一樣的坑歡迎交流我們互相補(bǔ)全各自的經(jīng)驗(yàn)庫(kù)。 AI Skills實(shí)戰(zhàn)指南：騰訊云上打造全能Agent的技能編排核心方法
1. 先搞明白AI Skills 在 Agent 體系里到底扮演什么角色我在實(shí)戰(zhàn)里帶過(guò)不少 Agent 項(xiàng)目說(shuō)實(shí)話早期踩過(guò)最大的坑就是把“Agent 框架”和“AI Skills”混為一談以為只要接一個(gè)大模型API再套一層工具調(diào)用就算完事。結(jié)果項(xiàng)目跑到中后期技能一多豆?jié){油條全往里塞邏輯糾纏到一起調(diào)試一次恨不得抽一包煙。后來(lái)在騰訊云上完整跑通了一套基于 AI Skills 的 Agent 項(xiàng)目才算是把“技能分層、按需編排、獨(dú)立擴(kuò)展”這條路走順了。這篇博文我索性把這套實(shí)踐完整復(fù)盤出來(lái)標(biāo)題就叫“全能 Agent 養(yǎng)成記”不吹不黑把配置、編碼、聯(lián)調(diào)、排障的過(guò)程全擺出來(lái)希望能幫到正在做 Agent 開發(fā)、尤其是打算在騰訊云上落地的朋友。先說(shuō)清楚一個(gè)基本概念Skills 在 AI Agent 體系里對(duì)應(yīng)的是模型之外的能力集合它可以是一個(gè)工具函數(shù)的描述集也可以是若干API的編排模板還可以是帶提示詞約束的專用子流程。Agent 本身負(fù)責(zé)理解意圖、拆解任務(wù)、決定調(diào)哪個(gè)技能Skills 則負(fù)責(zé)具體干活兒。所以改寫一個(gè) Agent 項(xiàng)目的復(fù)雜度很大程度上取決于你技能層的設(shè)計(jì)是否夠清晰、是否方便獨(dú)立測(cè)試、是否便于動(dòng)態(tài)加載。為什么選騰訊云做訓(xùn)練場(chǎng)坦率講云廠商這類服務(wù)很多但騰訊云的 AI Skills 在“模型服務(wù)、技能注冊(cè)、云端調(diào)試、灰度發(fā)布”這套閉環(huán)上做得比較完整加上用的是我們國(guó)內(nèi)團(tuán)隊(duì)更熟悉的控制臺(tái)操作習(xí)慣上手門檻低。更關(guān)鍵的是它在技能編排這一層其實(shí)兼容了很多開源生態(tài)的思維比如把技能描述寫清楚后模型能自動(dòng)路由到正確的技能上。這一點(diǎn)在你技能數(shù)量超過(guò) 20 個(gè)之后會(huì)變得非常重要靠“if-else 硬編碼調(diào)度”的方式根本活不過(guò)三個(gè)月。我在文章后面會(huì)按照“先理解、再配置、后實(shí)現(xiàn)、最后排障”的順序來(lái)拆解盡量讓你看完就能在自己的騰訊云賬號(hào)里復(fù)現(xiàn)出一個(gè)真正能用的 Agent 項(xiàng)目。這篇文章的定位不是給你念一遍官方文檔而是告訴你文檔沒寫明的那 30% 關(guān)鍵細(xì)節(jié)。1.1 從“會(huì)聊天”到“會(huì)干活”Agent 缺的是技能層很多人對(duì) Agent 的理解還停留在“一個(gè)聊天機(jī)器人 調(diào)用大模型”。這種理解只能支撐 Demo支撐不了真實(shí)業(yè)務(wù)。因?yàn)檎鎸?shí)業(yè)務(wù)里大模型只是“大腦”它需要一套可編排的“手腳”才能做正經(jīng)事這套手腳就是技能層。如果把 Agent 拆開看應(yīng)該是三層理解層負(fù)責(zé)意圖識(shí)別和任務(wù)規(guī)劃決策層負(fù)責(zé)根據(jù)上下文選擇執(zhí)行路徑執(zhí)行層負(fù)責(zé)真正調(diào)用工具、查數(shù)據(jù)庫(kù)、寫文件、發(fā)請(qǐng)求。AI Skills 正好填補(bǔ)的是執(zhí)行層的能力沉淀。沒有技能層模型再聰明也拿不到實(shí)時(shí)訂單數(shù)據(jù)沒法操作業(yè)務(wù)后臺(tái)更不可能完成多步驟的信息整合。我在項(xiàng)目里通常會(huì)把技能按“原子技能”和“復(fù)合技能”兩類來(lái)設(shè)計(jì)。原子技能對(duì)應(yīng)一個(gè)獨(dú)立 API 或工具調(diào)用比如“根據(jù)訂單號(hào)查詢訂單”復(fù)合技能則由多個(gè)原子技能串聯(lián)比如“查詢訂單 → 計(jì)算優(yōu)惠 → 生成客服回復(fù)”。這個(gè)分層好處非常明顯單個(gè)技能出了問(wèn)題我可以單獨(dú)測(cè)、單獨(dú)修不用整條鏈路上線回滾。還有一個(gè)容易忽略的價(jià)值點(diǎn)技能層的存在讓 Agent 可以“越用越強(qiáng)”。每新增一個(gè)業(yè)務(wù)場(chǎng)景不需要重寫 Agent 邏輯只需要在技能庫(kù)里注冊(cè)一個(gè)新的技能描述然后讓模型在規(guī)劃階段“看得到”這個(gè)技能就行了。這也是為什么 Skill 與 Agent 框架的關(guān)系更像“插件系統(tǒng)與主程序”的關(guān)系而不是“函數(shù)與調(diào)用方”的耦合關(guān)系。1.2 Skills 與 Agent 框架的分工邊界到底怎么劃我見過(guò)不少團(tuán)隊(duì)的架構(gòu)圖上把 Skills、Agent、模型全部畫在一層里看起來(lái)沒啥問(wèn)題但真到寫代碼時(shí)就犯糊涂了。我建議用下面這個(gè)分工方式來(lái)劃邊界。Agent 框架只做三件事“理解用戶訴求、拆解執(zhí)行步驟、維護(hù)會(huì)話記憶”。模型在這里充當(dāng)推理引擎不直接接觸數(shù)據(jù)庫(kù)也不直接調(diào)外部API。而 AI Skills 對(duì)外暴露的是“能力描述 入?yún)⒊鰠⒍x 實(shí)際執(zhí)行邏輯”它不需要關(guān)心當(dāng)前對(duì)話里用戶的情緒也不需要維護(hù)上下文狀態(tài)只管把輸入?yún)?shù)消費(fèi)掉返回一個(gè)結(jié)構(gòu)化結(jié)果。這樣劃分之后好處特別實(shí)際第一技能可以被多個(gè) Agent 復(fù)用比如訂單查詢技能售前 Agent 能用售后 Agent 也能用第二技能的上線可以通過(guò)配置完成不需要改 Agent 代碼第三不同的技能可以由不同團(tuán)隊(duì)各自維護(hù)職責(zé)邊界清晰不會(huì)出現(xiàn)“牽一發(fā)動(dòng)全身”的恐怖局面。在騰訊云 AI Skills 的實(shí)踐里我最滿意的是它對(duì)“技能描述”的重視。系統(tǒng)會(huì)要求你為每個(gè)技能寫清楚“功能描述、適用場(chǎng)景、參數(shù)說(shuō)明、輸出格式”這段描述直接影響模型路由的準(zhǔn)確率。你如果偷懶只寫一句“查詢訂單”模型很容易在相似場(chǎng)景下調(diào)用錯(cuò)技能寫清楚“當(dāng)用戶咨詢包裹物流或訂單狀態(tài)時(shí)使用此技能輸入?yún)?shù)為訂單號(hào)或手機(jī)號(hào)”路由準(zhǔn)確率會(huì)立刻上一個(gè)臺(tái)階。1.3 為什么拿騰訊云做技能訓(xùn)練場(chǎng)而不是本地裸跑也許你會(huì)問(wèn)Skills 這套設(shè)計(jì)我在本地用 Python 也能搭為什么非得用騰訊云我的回答是本地搭一套技能框架確實(shí)不難難的是“模型服務(wù)、技能注冊(cè)、可靠調(diào)度、日志追蹤”這幾件事的集成度騰訊云在這里確實(shí)能幫我們省下大量基建時(shí)間。首先騰訊云的模型服務(wù)通過(guò)統(tǒng)一網(wǎng)關(guān)對(duì)外提供服務(wù)你在代碼里既可以用官方大模型也可以接自部署的開源模型切換成本很低。其次AI Skills 的服務(wù)托管幫你處理了鑒權(quán)、限流、監(jiān)控這些“臟活”這對(duì)中小團(tuán)隊(duì)尤其重要畢竟不是每個(gè)人都有專門的運(yùn)維人力來(lái)盯服務(wù)穩(wěn)定性。另外騰訊云在國(guó)內(nèi)的節(jié)點(diǎn)覆蓋和合規(guī)備案做得比較省心。公司項(xiàng)目要過(guò)等保、要審計(jì)本地裸跑技能服務(wù)的話很多東西從零開始搞周期長(zhǎng)、成本高。而云上直接帶上云日志、訪問(wèn)管理、密鑰管理等現(xiàn)成能力能幫助你把精力集中在“技能本身的業(yè)務(wù)邏輯”上而不是整天折騰底層環(huán)境?？梢哉f(shuō)這與我的實(shí)際需求是比較貼合的。2. 環(huán)境準(zhǔn)備與基礎(chǔ)配置開通服務(wù)、搭好運(yùn)行環(huán)境在寫任何代碼之前先把環(huán)境跑通。很多人習(xí)慣一上來(lái)就寫業(yè)務(wù)邏輯結(jié)果測(cè)試時(shí)發(fā)現(xiàn)調(diào)用不通回頭再排查網(wǎng)絡(luò)、鑒權(quán)、依賴?yán)速M(fèi)時(shí)間不說(shuō)還容易懷疑人生。這里我直接把一套最省心的基礎(chǔ)環(huán)境準(zhǔn)備流程給你列出來(lái)。2.1 從注冊(cè)到開通 AI Skills 服務(wù)的完整路徑假如你現(xiàn)在是第一次用騰訊云注冊(cè)賬號(hào)這一步就不多說(shuō)了建議直接使用企業(yè)認(rèn)證后面調(diào)用模型服務(wù)和企業(yè)級(jí)技能托管時(shí)權(quán)限會(huì)寬很多。登錄控制臺(tái)之后在搜索框輸入“AI Skills”或者“智能體”進(jìn)入產(chǎn)品頁(yè)點(diǎn)擊開通服務(wù)。首次開通時(shí)系統(tǒng)會(huì)讓你選擇運(yùn)行區(qū)域盡量選靠近你業(yè)務(wù)用戶的區(qū)域比如業(yè)務(wù)集中在華東就選上海這樣接口延遲會(huì)低一些。開通服務(wù)之后建議順手把“訪問(wèn)密鑰”準(zhǔn)備好。在騰訊云控制臺(tái)的訪問(wèn)管理 CAM 里創(chuàng)建子用戶并為該子用戶關(guān)聯(lián) AI Skills 相關(guān)的策略權(quán)限然后生成 SecretId 和 SecretKey。這里我多說(shuō)一句千萬(wàn)不要用根賬號(hào)的密鑰跑到代碼里一旦代碼倉(cāng)庫(kù)泄露后果不堪設(shè)想。我們用子用戶密鑰配好最小權(quán)限夠用就行。最后到模型服務(wù)控制臺(tái)里確認(rèn)一下是否已經(jīng)開通你計(jì)劃使用的大模型服務(wù)。通常官方默認(rèn)的模型比如混元系列或 DeepSeek 相關(guān)版本會(huì)在你開通產(chǎn)品時(shí)一并可用。如果你想接入自部署的模型需要在模型服務(wù)里創(chuàng)建“接入點(diǎn)”拿到對(duì)應(yīng)的 Endpoint 地址這個(gè)地址下一步會(huì)用到 Skill 配置里。2.2 用 Cloud Shell 還是本地 CLI 對(duì)接我的建議騰訊云提供了兩種常見的對(duì)接方式一是直接使用網(wǎng)頁(yè)版的 Cloud Shell二是本地安裝并配置騰訊云 CLI。我的建議是如果只是做實(shí)驗(yàn)、跑 Demo直接用 Cloud Shell 最省心打開即用網(wǎng)絡(luò)環(huán)境已經(jīng)幫你配置好了不用處理本地代理之類的問(wèn)題但如果要持續(xù)開發(fā)、要集成到 CI/CD 流程里就必須配置本地 CLI保證本機(jī)與云端鑒權(quán)一致。本地 CLI 配置流程也不復(fù)雜。先安裝騰訊云 CLI 工具支持主流操作系統(tǒng)然后在命令行里執(zhí)行配置命令輸入 SecretId、SecretKey 和默認(rèn)地域。配好之后建議先執(zhí)行一條簡(jiǎn)單的查詢命令測(cè)通比如查詢當(dāng)前賬號(hào)下的服務(wù)列表返回正常就說(shuō)明鑒權(quán)和網(wǎng)絡(luò)都沒問(wèn)題。還有一個(gè)細(xì)節(jié)很多人容易忽略AI Skills 的接口調(diào)用對(duì) Python 版本有要求官方 SDK 推薦 3.8 以上。如果你本地默認(rèn) Python 還是 3.6 或者更老建議用虛擬環(huán)境管理工具比如 conda 或 venv單獨(dú)創(chuàng)建一個(gè) Python 3.11 的環(huán)境避免將來(lái)依賴沖突。我項(xiàng)目里一直用 Python 3.11跑騰訊云 SDK 和主流 Agent 框架都很穩(wěn)。2.3 干凈的項(xiàng)目目錄是之后不崩潰的前提環(huán)境配好了接下來(lái)創(chuàng)建項(xiàng)目。我習(xí)慣的性能項(xiàng)目結(jié)構(gòu)大概是這樣的一個(gè)主目錄下分為 config 存放全局配置和技能注冊(cè)信息skills 存放各類技能實(shí)現(xiàn)core 存放 Agent 編排邏輯 tests 存放技能與鏈路的測(cè)試腳本logs 存放運(yùn)行日志。這套結(jié)構(gòu)未必最先進(jìn)但勝在直觀團(tuán)隊(duì)協(xié)作時(shí)新成員上手也快。在 config 里我會(huì)專門放一個(gè)skills_config.yaml它是技能注冊(cè)的“戶口本”每個(gè)技能的名字、描述、入?yún)⒊鰠⒍x、對(duì)應(yīng)的執(zhí)行模塊都寫在這個(gè)文件里。騰訊云 AI Skills 控制臺(tái)同樣支持配置技能元信息但我自己的經(jīng)驗(yàn)是先用代碼維護(hù)一份文件測(cè)試通過(guò)后再同步到云端這樣技能演進(jìn)過(guò)程有記錄可查也比直接在網(wǎng)頁(yè)上改來(lái)改去更可控。我建議在項(xiàng)目根目錄加一份requirements.txt或pyproject.toml把需要用到的依賴固定好版本。騰訊云官方 SDK、OpenAI 兼容客戶端如果需要、pydantic用于參數(shù)校驗(yàn)、pytest測(cè)試用都是基礎(chǔ)配置。依賴版本一定要鎖死否則過(guò)兩個(gè)月項(xiàng)目重裝環(huán)境時(shí)SDK 批量升級(jí)很容易把接口搞掛。3. 從零實(shí)現(xiàn)一個(gè)“能查訂單、能算優(yōu)惠”的 Agent Skills環(huán)境好了抽象概念講再多也得落地。這一節(jié)我用一個(gè)具體場(chǎng)景來(lái)演示一個(gè)電商客服 Agent需要支持“查詢訂單狀態(tài)”和“計(jì)算優(yōu)惠金額”兩個(gè)技能然后讓 Agent 能根據(jù)用戶描述自動(dòng)調(diào)用對(duì)應(yīng)技能并把兩個(gè)技能串聯(lián)起來(lái)處理復(fù)雜問(wèn)題。3.1 先寫標(biāo)準(zhǔn)技能描述文件這一步別偷懶在寫業(yè)務(wù)邏輯之前先來(lái)寫技能描述。我見過(guò)太多人跳過(guò)這步直接寫函數(shù)結(jié)果模型路由不準(zhǔn)回頭又怪框架不好用。實(shí)際上大模型靠的是“描述文字”來(lái)理解技能用途描述質(zhì)量直接決定路由效果。一個(gè)科學(xué)的技能描述至少要包含幾個(gè)要素。技能名稱簡(jiǎn)短且唯一比如query_order_status。功能描述詳細(xì)說(shuō)明該技能“在什么情況下觸發(fā)”、“做什么事”、“不做什么事”。入?yún)⒍x參數(shù)名、類型、是否必填、默認(rèn)值、取值范圍。輸出格式建議結(jié)構(gòu)化為 JSON方便下游解析。示例給一個(gè)完整的調(diào)用示例方便模型理解。我拿訂單查詢技能舉例name: query_order_status description: | 當(dāng)用戶咨詢訂單狀態(tài)、物流進(jìn)度、發(fā)貨時(shí)間等問(wèn)題時(shí)使用此技能。 輸入?yún)?shù)可以是訂單號(hào)order_id也可以是用戶手機(jī)號(hào)phone。 如果兩個(gè)參數(shù)都未提供返回錯(cuò)誤提示。 parameters: order_id: type: string required: false description: 訂單號(hào)通常為數(shù)字和字母組合 phone: type: string required: false description: 用戶下單手機(jī)號(hào) output: type: object properties: order_status: type: string description: 訂單狀態(tài)pending/shipped/delivered/cancelled shipping_progress: type: string description: 物流進(jìn)度描述 estimated_arrival: type: string description: 預(yù)計(jì)送達(dá)日期 example: | 輸入: {order_id: DD20240516001} 輸出: {order_status: shipped, shipping_progress: 包裹已到達(dá)杭州轉(zhuǎn)運(yùn)中心, estimated_arrival: 2024-05-20}寫完之后不要急著進(jìn)入下一步先在項(xiàng)目里把這份 yaml 用 pydantic 校驗(yàn)一遍確保格式合法再去控制臺(tái)創(chuàng)建或同步到云端。很多路由問(wèn)題根源就是寫入控制臺(tái)時(shí)的 YAML 縮進(jìn)寫錯(cuò)了這是最基礎(chǔ)也最容易犯的錯(cuò)誤。3.2 業(yè)務(wù)邏輯實(shí)現(xiàn)訂單查詢與優(yōu)惠計(jì)算要注意什么技能描述寫好之后接下來(lái)就是實(shí)現(xiàn)真實(shí)業(yè)務(wù)邏輯。訂單查詢技能我在本地用一個(gè)模擬數(shù)據(jù)源來(lái)做方便你復(fù)現(xiàn)請(qǐng)求進(jìn)來(lái)之后先做參數(shù)校驗(yàn)然后從內(nèi)存數(shù)據(jù)字典或數(shù)據(jù)庫(kù)里查出對(duì)應(yīng)訂單最后返回標(biāo)準(zhǔn) JSON。# skills/order_skill.py import re from typing import Dict, Optional MOCK_ORDERS { DD20240516001: { order_status: shipped, shipping_progress: 包裹已到達(dá)杭州轉(zhuǎn)運(yùn)中心, estimated_arrival: 2024-05-20, amount: 199.00, }, DD20240517002: { order_status: delivered, shipping_progress: 包裹已簽收, estimated_arrival: 2024-05-18, amount: 89.00, }, } def query_order_status(order_id: Optional[str] None, phone: Optional[str] None) - Dict: if not order_id and not phone: return {error: order_id 和 phone 至少需要提供一個(gè)} # 簡(jiǎn)單校驗(yàn)order_id 格式檢查 if order_id and not re.fullmatch(rDD\d{8,}, order_id): return {error: order_id 格式不正確} # 實(shí)際項(xiàng)目中這里查數(shù)據(jù)庫(kù)演示環(huán)境用本地字典 order MOCK_ORDERS.get(order_id) if not order: return {error: f未找到訂單: {order_id}} return { order_status: order[order_status], shipping_progress: order[shipping_progress], estimated_arrival: order[estimated_arrival], }優(yōu)惠計(jì)算技能輸入商品原價(jià)和用戶等級(jí)輸出優(yōu)惠金額和最終價(jià)。# skills/discount_skill.py from typing import Dict, Union VIp_RATE { normal: 0.0, silver: 0.05, gold: 0.10, platinum: 0.20, } def calc_discount(price: Union[float, int], user_level: str normal) - Dict: rate VIP_RATE.get(user_level, 0.0) discount_amount round(float(price) * rate, 2) final_price round(float(price) - discount_amount, 2) return { original_price: float(price), user_level: user_level, discount_rate: rate, discount_amount: discount_amount, final_price: final_price, }業(yè)務(wù)邏輯本身不難難在邊界情況。比如訂單號(hào)為空、價(jià)格傳負(fù)數(shù)、用戶等級(jí)不存在這些情況技能內(nèi)部都必須兜住異常不能讓異常穿透到 Agent 層。一個(gè)經(jīng)驗(yàn)法則技能層永遠(yuǎn)返回結(jié)構(gòu)化結(jié)果要么返回業(yè)務(wù)數(shù)據(jù)要么返回錯(cuò)誤描述絕不拋異常。只有這樣才能保證 Agent 在拿到錯(cuò)誤結(jié)果后還能繼續(xù)與用戶對(duì)話而不是直接崩潰。3.3 把 Skills 寫成服務(wù)暴露給 Agent 調(diào)度技能函數(shù)寫好之后下一步就是把它們暴露出來(lái)讓 Agent 可以被網(wǎng)絡(luò)調(diào)用。我見過(guò)不少團(tuán)隊(duì)直接把函數(shù) import 到 Agent 框架里用這在單體項(xiàng)目里沒問(wèn)題但一旦技能多了、要獨(dú)立部署或灰度發(fā)布時(shí)這種方式就非常難受。所以這里我建議走“技能即服務(wù)”的路線。在騰訊云上最簡(jiǎn)單的做法是把技能實(shí)現(xiàn)為一個(gè) HTTP 服務(wù)部署到云函數(shù)、容器服務(wù)或者輕量服務(wù)器上然后在 AI Skills 控制臺(tái)配置為外部服務(wù)。Agent 發(fā)起調(diào)用時(shí)通過(guò)約定的 API 地址完成調(diào)用。我用 FastAPI 寫了個(gè)輕量服務(wù)把兩個(gè)技能封裝成 HTTP 接口# server.py from fastapi import FastAPI from pydantic import BaseModel from typing import Optional from skills.order_skill import query_order_status from skills.discount_skill import calc_discount app FastAPI() class OrderRequest(BaseModel): order_id: Optional[str] None phone: Optional[str] None class DiscountRequest(BaseModel): price: float user_level: str normal app.post(/api/query_order_status) def order_status(req: OrderRequest): return query_order_status(order_idreq.order_id, phonereq.phone) app.post(/api/calc_discount) def discount(req: DiscountRequest): return calc_discount(pricereq.price, user_levelreq.user_level)這樣設(shè)計(jì)有一個(gè)非常實(shí)際的好處每個(gè)技能服務(wù)都可以單獨(dú)測(cè)試、單獨(dú)擴(kuò)容。訂單查詢流量大了給訂單服務(wù)擴(kuò)容優(yōu)惠計(jì)算邏輯迭代了只發(fā)布優(yōu)惠服務(wù)互不影響。相比把技能函數(shù)全堆在 Agent 進(jìn)程里這個(gè)架構(gòu)在真實(shí)業(yè)務(wù)里能少踩一半的運(yùn)維坑。3.4 參數(shù)調(diào)優(yōu)與成本控制的三個(gè)關(guān)鍵配置技能服務(wù)上線之后緊接著要考慮的其實(shí)是成本控制。大模型推理是按 Token 計(jì)費(fèi)的Agent 在會(huì)話中如果反復(fù)調(diào)用技能、返回長(zhǎng)文本費(fèi)用會(huì)蹭蹭地漲。我在這塊總結(jié)了三個(gè)很關(guān)鍵的控制點(diǎn)。第一是設(shè)置合理的模型溫度參數(shù)。對(duì) Agent 場(chǎng)景來(lái)說(shuō)temperature 建議控制在 0.2 到 0.4 之間溫度太高容易讓模型“自由發(fā)揮”編造技能參數(shù)導(dǎo)致調(diào)用出問(wèn)題。第二是限制技能返回結(jié)果的最大 Token 數(shù)。很多時(shí)候 Agent 只需要一個(gè)結(jié)論不需要完整的長(zhǎng)文本詳情在技能返回層直接截?cái)嗷蚍庋b成精簡(jiǎn)格式能省不少 Token 費(fèi)用。第三是設(shè)計(jì)好模型最大重試次數(shù)。當(dāng)模型調(diào)用技能失敗時(shí)給它一兩次機(jī)會(huì)重新生成參數(shù)是可以的但沒必要無(wú)限重試容易拖慢響應(yīng)也燒錢。這里我提供一個(gè)思路在調(diào)用模型接口時(shí)騰訊云模型服務(wù)或者兼容 OpenAI 的客戶端里通常支持max_tokens、temperature、stop參數(shù)把這三個(gè)參數(shù)按場(chǎng)景預(yù)置到配置里。比如客服場(chǎng)景我會(huì)把 max_tokens 設(shè)為 512temperature 設(shè)為 0.3stop 設(shè)置為空這樣大多數(shù)情況下響應(yīng)質(zhì)量和成本能達(dá)到一個(gè)不錯(cuò)的平衡點(diǎn)。# config/model_config.py MODEL_CONFIG { temperature: 0.3, max_tokens: 1024, top_p: 0.9, timeout: 30, }4. 核心流程實(shí)現(xiàn)注冊(cè)技能、編排聯(lián)調(diào)、跑通全鏈路技能服務(wù)就緒后剩下的事情就是把它們“教會(huì)”給 Agent 用。這一階段的核心流程包括在騰訊云控制臺(tái)完成技能注冊(cè)、在 Agent 編排層配置技能調(diào)用規(guī)則、最終跑通一條真實(shí)用戶請(qǐng)求的端到端鏈路。4.1 在 Agent 構(gòu)建平臺(tái)中注冊(cè)技能注意哪些字段登錄騰訊云 AI Skills 控制臺(tái)進(jìn)入“技能管理”頁(yè)面創(chuàng)建一個(gè)新技能。你會(huì)看到幾個(gè)關(guān)鍵的輸入字段技能名稱、技能描述、請(qǐng)求地址HTTP 接口地址、請(qǐng)求方法、入?yún)⒊鰠?Schema。這里我要特別強(qiáng)調(diào)“技能描述”和“入?yún)⒊鰠?Schema”這兩個(gè)字段它們決定模型能不能準(zhǔn)確“看懂”你的技能。技能描述要盡量用業(yè)務(wù)語(yǔ)言來(lái)寫最好包含觸發(fā)條件。比如“當(dāng)用戶想要查詢訂單物流狀態(tài)時(shí)調(diào)用此接口傳入訂單號(hào)”這比只寫“訂單查詢”要精確得多。入?yún)⒊鰠?Schema 建議按照 JSON Schema 規(guī)范嚴(yán)格定義。如果定義模糊模型在推理時(shí)無(wú)法猜測(cè)到底該傳什么字段值很容易因?yàn)閰?shù)缺失導(dǎo)致接口報(bào)錯(cuò)。注冊(cè)完成后控制臺(tái)會(huì)生成一個(gè)技能 ID。后面在 Agent 編排層配置工具調(diào)用時(shí)引用的是這個(gè)技能 ID。如果你像我的習(xí)慣一樣在本地 yaml 里維護(hù)了一份技能描述此時(shí)需要做一次比對(duì)本地代碼中的描述字段與控制臺(tái)是否一致。開發(fā)環(huán)境經(jīng)常出現(xiàn)改了一處卻忘記同步的情況最后發(fā)現(xiàn)問(wèn)題時(shí)排查成本很高。4.2 Agent 多技能編排的會(huì)話策略怎么設(shè)置才合理注冊(cè)完技能接著配置 Agent 編排。騰訊云的 Agent 構(gòu)建平臺(tái)或者你自選的開源框架一般允許配置系統(tǒng)提示詞、技能列表和會(huì)話策略。系統(tǒng)提示詞是 Agent 的總綱它決定了 Agent 怎么拆解用戶的復(fù)雜訴求。比如對(duì)于我們的電商客服場(chǎng)景系統(tǒng)提示詞我會(huì)這么寫你是一個(gè)電商客服助手當(dāng)用戶詢問(wèn)訂單狀態(tài)時(shí)調(diào)用查詢訂單技能當(dāng)用戶詢問(wèn)價(jià)格優(yōu)惠時(shí)調(diào)用計(jì)算優(yōu)惠技能。如果用戶的問(wèn)題同時(shí)涉及多個(gè)技能先查詢訂單再根據(jù)訂單金額計(jì)算優(yōu)惠。這段提示詞的“編排暗示”非常重要它相當(dāng)于給模型的規(guī)劃過(guò)程畫了一條輕量級(jí)的業(yè)務(wù)規(guī)則。會(huì)話策略方面重點(diǎn)關(guān)注上下文長(zhǎng)度管理。AI Agent 多輪對(duì)話時(shí)上下文會(huì)不斷累積到達(dá)模型上限后要么截?cái)?、要么?bào)錯(cuò)。我建議設(shè)置一個(gè) token 閾值比如超過(guò) 4000 tokens 時(shí)自動(dòng)精簡(jiǎn)歷史消息只保留最近兩輪完整對(duì)話和系統(tǒng)提示詞、之前輪次生成的關(guān)鍵結(jié)論。騰訊云 AI Skills 的配置項(xiàng)里通常有相關(guān)參數(shù)可調(diào)還是要根據(jù)實(shí)際業(yè)務(wù)測(cè)試后選擇一個(gè)合理的閾值。4.3 聯(lián)調(diào)實(shí)錄一次完整對(duì)話的完整追蹤過(guò)程配置好這一切之后我們從用戶視角來(lái)跑一遍完整鏈路然后追蹤系統(tǒng)日志。用戶提問(wèn)“我的訂單 DD20240516001 什么時(shí)候能到我現(xiàn)在是金牌會(huì)員還能便宜多少”這個(gè)過(guò)程 Agent 內(nèi)部大致會(huì)經(jīng)歷幾個(gè)階段一是意圖拆解模型判斷該問(wèn)題涉及“查詢訂單狀態(tài)”和“計(jì)算優(yōu)惠”兩個(gè)技能二是編排計(jì)劃模型生成調(diào)用序列計(jì)劃先調(diào)訂單查詢、再調(diào)優(yōu)惠計(jì)算三是技能執(zhí)行Agent 框架依次調(diào)用兩個(gè)技能四是匯總答案模型根據(jù)兩個(gè)技能結(jié)果組織最終回復(fù)包含訂單到達(dá)時(shí)間、優(yōu)惠金額、最終價(jià)格。全程日志追蹤我會(huì)用一個(gè)請(qǐng)求 ID 貫穿。具體方法是入口處生成 Request ID在每個(gè)技能調(diào)用處將 Request ID 寫入 Headers這樣即使鏈路很長(zhǎng)也能從日志平臺(tái)把一次請(qǐng)求的完整調(diào)用鏈拖出來(lái)排查。我在實(shí)踐中發(fā)現(xiàn)沒有統(tǒng)一請(qǐng)求 ID出了問(wèn)題連“哪個(gè)技能在哪個(gè)環(huán)節(jié)報(bào)錯(cuò)”都說(shuō)不清這是 Agent 項(xiàng)目排查中最大的痛點(diǎn)之一。模擬執(zhí)行之后你要驗(yàn)證兩件事第一兩個(gè)技能是否正確返回結(jié)果第二模型的最終回復(fù)是否把技能結(jié)果用對(duì)了。如果模型明明拿到了訂單金額卻不計(jì)算優(yōu)惠很可能是系統(tǒng)提示詞里沒把“金牌會(huì)員可以打折”的業(yè)務(wù)規(guī)則交代清楚。這種問(wèn)題不是技能本身有問(wèn)題而是 Agent 的業(yè)務(wù)規(guī)則配置不夠具體這也是 Agent 落地時(shí)最常遇到的隱性坑。5. 常見問(wèn)題與排查技巧實(shí)錄Agent 項(xiàng)目調(diào)試階段的體驗(yàn)和傳統(tǒng)后端有明顯區(qū)別傳統(tǒng)后端請(qǐng)求響應(yīng)結(jié)果是確定性的而 Agent 環(huán)節(jié)里模型推理有隨機(jī)性出錯(cuò)位置也不好復(fù)現(xiàn)。我把這段時(shí)間實(shí)際踩過(guò)的坑、排查出來(lái)的心得記錄如下。5.1 技能觸發(fā)不準(zhǔn)Agent 總是接錯(cuò)話癥狀是用戶明明在問(wèn)物流Agent 卻調(diào)用了優(yōu)惠計(jì)算技能。這種問(wèn)題非常常見我排查的順序是這樣的。第一步檢查技能描述是否清晰。描述太泛、太短是首要原因模型無(wú)法理解技能的邊界。這里我給一個(gè)對(duì)比模糊寫法是“物流查詢”建議寫“當(dāng)用戶需要了解包裹運(yùn)輸進(jìn)度、快遞當(dāng)前位置、預(yù)計(jì)送達(dá)時(shí)間時(shí)調(diào)用本技能。輸入訂單號(hào)或手機(jī)號(hào)”效果差別很明顯。第二步檢查是否有復(fù)數(shù)技能之間描述重合。比如“訂單查詢”和“售后查詢”都寫了“用戶詢問(wèn)訂單相關(guān)信息時(shí)調(diào)用”模型當(dāng)然會(huì)犯迷糊。解決方式是明確區(qū)別給每個(gè)技能劃定更專屬的觸發(fā)詞和場(chǎng)景。第三步檢查系統(tǒng)提示詞是否做了強(qiáng)約束。如果業(yè)務(wù)規(guī)則允許可以在系統(tǒng)提示詞里直接寫明“涉及物流狀態(tài)一律優(yōu)先調(diào)用查詢訂單技能”這能極大提升命中率。如果這三點(diǎn)都排查完還是不準(zhǔn)可以在各技能內(nèi)部打印一段可觀測(cè)日志記錄“某個(gè)技能被調(diào)用時(shí)模型的完整推理過(guò)程”定位模型到底為什么選擇錯(cuò)了。這一步需要底層框架支持中間過(guò)程輸出不是所有平臺(tái)都開放但如果調(diào)試環(huán)境允許價(jià)值非常大。5.2 技能請(qǐng)求超時(shí)與并發(fā)限制怎么破Agent 場(chǎng)景有個(gè)很特殊的問(wèn)題模型調(diào)度外部技能外部技能響應(yīng)時(shí)間一長(zhǎng)模型那邊會(huì)先一步超時(shí)導(dǎo)致 Agent 報(bào)錯(cuò)。我在騰訊云上實(shí)踐時(shí)遇到過(guò)幾次技能服務(wù)響應(yīng)超過(guò) 10 秒的情況結(jié)果 Agent 直接中斷。排查后發(fā)現(xiàn)是兩個(gè)原因一是技能服務(wù)內(nèi)部有慢 SQL二是云函數(shù)冷啟動(dòng)過(guò)慢。對(duì)前者我給訂單表加了索引對(duì)后者我把云函數(shù)最小實(shí)例數(shù)從 0 調(diào)到了 1減少冷啟動(dòng)概率。這一改成功率提升明顯。并發(fā)限制方面需要注意騰訊云上的限流配置。默認(rèn)限流閾值可能適合 Demo但真實(shí)業(yè)務(wù)一旦流量上來(lái)需要提前評(píng)估峰值 QPS并在控制臺(tái)調(diào)整限流策略。反過(guò)來(lái)如果 Agent 長(zhǎng)時(shí)間高頻調(diào)用某個(gè)技能也需要在技能服務(wù)側(cè)做好降級(jí)方案比如返回緩存數(shù)據(jù)而不是直接報(bào)錯(cuò)。我們做客服場(chǎng)景的時(shí)候如果一個(gè)用戶的訂單查詢因并發(fā)觸發(fā)限流直接返回“系統(tǒng)繁忙”的體驗(yàn)并不好更好的方式是返回一個(gè)降級(jí)提示“訂單正在反復(fù)核驗(yàn)中請(qǐng)稍后刷新”這樣交互上不會(huì)太生硬。5.3 鑒權(quán)與安全踩坑密鑰泄露才是最大的雷Agent 項(xiàng)目中技能服務(wù)往往有調(diào)用權(quán)限能查數(shù)據(jù)庫(kù)、操作業(yè)務(wù)后臺(tái)所以鑒權(quán)安全問(wèn)題不可忽視。我在早期項(xiàng)目中為了圖方便直接把騰訊云的 SecretKey 寫在代碼環(huán)境變量里結(jié)果有一次不小心把環(huán)境變量文件提交到了 Git 倉(cāng)庫(kù)雖然及時(shí)發(fā)現(xiàn)并回收了密鑰但想起來(lái)仍然有些后怕這件事之后我就規(guī)范了密鑰管理方式。規(guī)范的做法是云上的訪問(wèn)密鑰不使用根賬號(hào)密鑰而是創(chuàng)建子賬號(hào)并授予最小權(quán)限同時(shí)啟用騰訊云的密鑰管理系統(tǒng)KMS或者使用環(huán)境變量的方式注入運(yùn)行時(shí)不讓密鑰出現(xiàn)在代碼倉(cāng)庫(kù)里。技能服務(wù)之間的調(diào)用可以使用 JWT 或者內(nèi)部簽名機(jī)制確保只有 Agent 編排層可以調(diào)用暴露出來(lái)的接口。如果你用的是云函數(shù)部署技能服務(wù)可以關(guān)閉公網(wǎng)訪問(wèn)只在 VPC 內(nèi)網(wǎng)與 Agent 編排層通信這相當(dāng)于把技能服務(wù)藏在了內(nèi)網(wǎng)外部無(wú)法直接訪問(wèn)安全系數(shù)會(huì)高很多。5.4 用日志和追蹤打造屬于自己的排障工作臺(tái)Agent 項(xiàng)目調(diào)試中我強(qiáng)烈建議你從一開始就把日志系統(tǒng)建好。不要等項(xiàng)目出問(wèn)題再補(bǔ)因?yàn)?Agent 的調(diào)用鏈路長(zhǎng)、不確定性高沒有日志幾乎等于盲人摸象。我在項(xiàng)目里會(huì)記錄三類日志一是入?yún)⑷罩居涗浻脩粼驾斎?、Agent 生成的調(diào)用計(jì)劃二是技能執(zhí)行日志記錄每個(gè)技能的入?yún)?、出參、耗時(shí)和錯(cuò)誤信息三是模型推理日志記錄大模型每次調(diào)用的 token 數(shù)、溫度、最終響應(yīng)。三類日志用請(qǐng)求 ID 串聯(lián)配合騰訊云日志服務(wù)做檢索排障速度會(huì)大幅提升。這里我分享一個(gè)排查技巧在 Agent 編排層不返回報(bào)錯(cuò)詳情給終端用戶但完整日志直接打到云端。這樣做既避免把內(nèi)部系統(tǒng)信息暴露給用戶又不影響開發(fā)人員查問(wèn)題。很多 Agent 平臺(tái)有“思考過(guò)程”追蹤功能強(qiáng)烈建議開啟實(shí)際調(diào)試時(shí)能讓你直觀看到模型是如何做技能決策的看著它一步步想比只看最終結(jié)果好太多。6. 一些額外的優(yōu)化建議與個(gè)人實(shí)踐心得最后這部分我把我實(shí)際操作中總結(jié)的一些體會(huì)分享出來(lái)也許能幫你少走一點(diǎn)彎路。第一技能注冊(cè)的版本管理非常重要。我在實(shí)踐中發(fā)現(xiàn)技能服務(wù)一旦發(fā)布上線后續(xù)迭代就不可避免。如果每次都直接改線上技能配置出了問(wèn)題想回滾都難。建議在技能描述里增加一個(gè)版本號(hào)字段或者在本地 git 里給技能配置單獨(dú)建一個(gè)目錄每次修改發(fā)版都有記錄。騰訊云 AI Skills 控制臺(tái)支持創(chuàng)建新版本建議養(yǎng)成“新版本驗(yàn)證通過(guò)后再發(fā)布”的習(xí)慣這個(gè)過(guò)程可能多花十幾分鐘但遠(yuǎn)比線上事故的恢復(fù)成本低得多。第二Agent 測(cè)試不能只測(cè)正常路徑。真實(shí)世界里用戶提問(wèn)千奇百怪我今天測(cè)試了幾十條異常輸入包括不存在的訂單號(hào)、含糊的“幫我看看我的訂單”、只給手機(jī)號(hào)的查詢。每條異常輸入都整理成測(cè)試用例沉淀到 automated tests 里。以后每次改技能描述或模型配置把全量測(cè)試跑一遍能防住大部分回歸問(wèn)題。第三騰訊云 AI Skills 與開源 Agent 框架的兼容性其實(shí)是超預(yù)期的。最初我以為只能在騰訊云自家平臺(tái)里玩后來(lái)發(fā)現(xiàn)通過(guò)標(biāo)準(zhǔn) HTTP 技能接口定義同樣可以被主流 Agent 框架作為“外部工具”注冊(cè)使用。這意味著你完全可以“云上托管技能、本地編排 Agent”靈活性很高。如果你團(tuán)隊(duì)已有自研 Agent 框架不要被“全家桶”的心理預(yù)設(shè)限制完全可以只選騰訊云服務(wù)里對(duì)你最有價(jià)值的那一兩個(gè)能力來(lái)用。第四也是最想強(qiáng)調(diào)的一點(diǎn)Agent 項(xiàng)目的復(fù)雜度主要來(lái)自技能層而不是模型層。模型能力再?gòu)?qiáng)技能描述混亂、服務(wù)不穩(wěn)定、日志缺失Agent 照樣沒法用。先把技能層像基礎(chǔ)設(shè)施一樣認(rèn)真對(duì)待Agent 才能成為真正可靠的生產(chǎn)力工具。這也是我做這個(gè)“全能 Agent 養(yǎng)成記”系列最想傳遞的東西。如果你也正在騰訊云上折騰 Agent 和 AI Skills希望這篇實(shí)踐記錄能給你省下一些不必要的調(diào)試時(shí)間。每個(gè)人項(xiàng)目實(shí)施環(huán)境不同坑的位置也不會(huì)完全一樣但底層思路是相通。如果你在實(shí)踐過(guò)程中有更好的技巧或踩到了不一樣的坑歡迎交流我們互相補(bǔ)全各自的經(jīng)驗(yàn)庫(kù)。