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