1. 先說(shuō)清楚為什么智能體開(kāi)發(fā)需要一套獨(dú)立框架最近半年我一直在折騰智能體應(yīng)用從最開(kāi)始的“調(diào)個(gè)大模型 API 然后寫(xiě)死 Prompt”一路做到真正能穩(wěn)定跑業(yè)務(wù)的系統(tǒng)。中間踩了不少坑也把市面主流的幾套方案都過(guò)了一遍。最后在某大廠開(kāi)源的智能體開(kāi)發(fā)套件上停了下來(lái)從 demo 一直推到生產(chǎn)環(huán)境?；剡^(guò)頭看這套框架解決的問(wèn)題不是“能不能調(diào)模型”而是“怎么讓智能體像一個(gè)正規(guī)軟件一樣被開(kāi)發(fā)、調(diào)試、運(yùn)維”。如果你自己從頭寫(xiě)過(guò) Agent一定體會(huì)過(guò)那種失控感。早期我做過(guò)一個(gè)簡(jiǎn)單的問(wèn)答機(jī)器人邏輯就是一個(gè) while 循環(huán)把用戶問(wèn)題拼進(jìn) Prompt調(diào)模型看返回結(jié)果里有沒(méi)有工具調(diào)用請(qǐng)求如果有就去執(zhí)行工具把結(jié)果再拼回去再調(diào)一次模型。兩三個(gè)工具的時(shí)候還好等工具到了十幾個(gè)模型開(kāi)始亂選工具、上下文越拼越長(zhǎng)、多輪對(duì)話狀態(tài)經(jīng)常串場(chǎng)代碼基本就成了一坨只能跑通 demo 的“一次性腳本”。這套開(kāi)源套件把上面這些臟活抽象成了標(biāo)準(zhǔn)組件模型統(tǒng)一接入、工具自動(dòng)分發(fā)、上下文自動(dòng)管理、回調(diào)事件追蹤、多智能體編排、沙箱代碼執(zhí)行、Agent 能力描述等等。你要做的只是定義 Agent 的行為和工具框架負(fù)責(zé)把模型推理循環(huán)跑順。這篇文章我就以這套架構(gòu)為主線把核心組件逐個(gè)拆開(kāi)講最后給一份可以直接抄作業(yè)的落地實(shí)踐。適合看的同學(xué)有三類(lèi)一是已經(jīng)用 LangChain 這類(lèi)通用編排框架但覺(jué)得不夠底層的二是準(zhǔn)備把 Agent 從 demo 推向生產(chǎn)的后端或算法工程師三是想搞懂智能體框架內(nèi)部設(shè)計(jì)的產(chǎn)品或技術(shù)負(fù)責(zé)人。基礎(chǔ)要求不高只要會(huì) Python、知道大模型 API 大概怎么調(diào)用就能跟著走完。2. 先記住這張組件地圖一個(gè) Agent 從啟動(dòng)到跑完的完整鏈條2.1 Agent 抽象框架里的“一切皆 Agent”這套框架最核心的抽象就是 Agent 類(lèi)。你可以把它理解成“一個(gè)帶有行為能力的對(duì)話實(shí)體”它不只是模型的封裝而是把模型、指令、工具、記憶、回調(diào)這些能力全部組合在一起的容器?？匆粋€(gè)最基礎(chǔ)的創(chuàng)建方式from core import Agent, tool tool def get_weather(city: str) - str: 查詢指定城市的實(shí)時(shí)天氣 return {city: city, weather: 晴, temp: 26} agent Agent( nameweather_assistant, modelyour-llm-model-id, instruction你是一個(gè)天氣助手使用 get_weather 工具回答用戶問(wèn)題。, tools[get_weather], )這段代碼里有一個(gè)容易被忽略的關(guān)鍵點(diǎn)Agent 的 name 不是隨便起的。它在框架里承擔(dān)兩個(gè)職能一是日志和追蹤的標(biāo)識(shí)二是在多智能體協(xié)作時(shí)作為路由尋址的 ID。我見(jiàn)過(guò)有團(tuán)隊(duì)把 name 全寫(xiě)成 default結(jié)果部署到線上出了故障根本沒(méi)法定位是哪個(gè)子智能體在跑排查成本直接翻倍。instruction 的作用也值得展開(kāi)說(shuō)。它不只是一個(gè)“人設(shè)提示詞”框架在設(shè)計(jì)上把它當(dāng)作智能體“系統(tǒng)級(jí)行為約束”來(lái)用。每輪推理時(shí)instruction 都會(huì)被放在對(duì)話上下文的系統(tǒng)位置并且在子智能體繼承、多智能體協(xié)作時(shí)會(huì)自動(dòng)隨 Agent 攜帶傳遞。這意味著你的智能體行為規(guī)范、工具使用邊界、輸出格式要求都應(yīng)該沉淀在 instruction 里而不是散落在業(yè)務(wù)代碼中。2.2 模型適配層為什么你必須用中間層而不是直連 API框架有一個(gè)統(tǒng)一的模型適配器Model Adapter概念所有大模型接入都走這一層。當(dāng)時(shí)我沒(méi)太在意覺(jué)得“不就是封裝一層 API 調(diào)用嗎”后來(lái)在對(duì)接不同模型時(shí)才發(fā)現(xiàn)這個(gè)設(shè)計(jì)有多重要。from core import Agent, ModelConfig config ModelConfig( provideropenai-compatible, modelyour-model-name, temperature0.2, max_tokens4096, ) agent Agent( modelconfig, ... )模型適配層解決的三個(gè)實(shí)際問(wèn)題統(tǒng)一接口不同大模型的請(qǐng)求格式差異被抹平業(yè)務(wù)代碼里永遠(yuǎn)不用寫(xiě) if 判斷“是哪個(gè)模型”。工具調(diào)用格式轉(zhuǎn)換不同模型的 function calling 參數(shù)格式不統(tǒng)一適配層負(fù)責(zé)把框架內(nèi)部的工具定義轉(zhuǎn)換成目標(biāo)模型需要的 schema。流式輸出和中斷處理框架會(huì)統(tǒng)一處理 token 級(jí)別的流式回調(diào)你的業(yè)務(wù)代碼收到的是完整事件不用自己處理流式拼接。我在生產(chǎn)環(huán)境里的真實(shí)體會(huì)是團(tuán)隊(duì)里會(huì)有不同業(yè)務(wù)線偏好不同的模型有了這層適配器切換模型就是改一行配置不用動(dòng)任何業(yè)務(wù)邏輯。這一點(diǎn)在中后期非常省事。2.3 上下文與狀態(tài)管理自動(dòng)幫你“收拾對(duì)話現(xiàn)場(chǎng)”所有做 Agent 的人都逃不過(guò)一個(gè)坎上下文怎么管。早期我手動(dòng)拼歷史消息每隔幾輪就要自己截?cái)嘟財(cái)嗟臅r(shí)候還要擔(dān)心把關(guān)鍵信息截掉了。這套框架的上下文管理模塊把這些做了自動(dòng)化。它的核心思路是把一次完整的 Agent 運(yùn)行看作一個(gè) Session每個(gè) Session 里有獨(dú)立的內(nèi)存狀態(tài)?？蚣軙?huì)在推理前自動(dòng)完成以下操作組裝系統(tǒng)指令、歷史消息、工具定義、當(dāng)前用戶輸入統(tǒng)計(jì) token 占用按你配置的上限自動(dòng)壓縮或裁剪過(guò)期消息在每輪工具調(diào)用之后把工具返回結(jié)果自動(dòng)追加進(jìn)上下文繼續(xù)下一次推理。這里有一個(gè)很重要的細(xì)節(jié)框架對(duì)上下文的裁剪策略不等于簡(jiǎn)單的“丟最老的對(duì)話”。它默認(rèn)會(huì)保留系統(tǒng)指令、最近的對(duì)話輪次、以及所有與工具調(diào)用相關(guān)的關(guān)鍵中間結(jié)果。這一點(diǎn)我后來(lái)做壓測(cè)時(shí)體會(huì)很深——簡(jiǎn)單的先進(jìn)先出策略在長(zhǎng)對(duì)話場(chǎng)景會(huì)讓智能體“失憶”而框架的保留策略明顯更合理。如果你有更復(fù)雜的記憶訴求框架也支持通過(guò) Memory 類(lèi)接入外部記憶存儲(chǔ)比如向量數(shù)據(jù)庫(kù)?；A(chǔ)場(chǎng)景下用內(nèi)置內(nèi)存就夠只有一個(gè)注意點(diǎn)內(nèi)置上下文默認(rèn)不會(huì)跨 Session 持久化重啟服務(wù)后對(duì)話歷史就沒(méi)了。需要持久化的場(chǎng)景得自己接存儲(chǔ)。2.4 推理循環(huán)框架替你寫(xiě)好了那個(gè) while 循環(huán)我前面提到自己手寫(xiě)的 while 循環(huán)框架內(nèi)部其實(shí)也是類(lèi)似的循環(huán)但它多做了幾件關(guān)鍵的事。框架的推理循環(huán)大致長(zhǎng)這樣組裝當(dāng)前會(huì)話的完整上下文調(diào)模型拿到模型輸出判斷模型輸出是普通文本還是工具調(diào)用請(qǐng)求若是工具調(diào)用則根據(jù)工具名分發(fā)到具體函數(shù)執(zhí)行后把結(jié)果注入上下文回到第 2 步若是最終回答文本則結(jié)束循環(huán)返回結(jié)果給用戶。這個(gè)循環(huán)本身的邏輯不難難的是邊界情況的處理。比如模型連續(xù)調(diào)用 5 個(gè)工具該怎么辦、工具拋異常后該怎么讓模型知道并繼續(xù)、以及如果模型陷入工具重試死循環(huán)該怎么止損?？蚣軐?duì)這些情況都有內(nèi)建的策略配置我在第 6 部分會(huì)展開(kāi)講“死循環(huán)防護(hù)”的配置參數(shù)。3. 工具系統(tǒng)拆解讓智能體真正“動(dòng)手干活”3.1 裝飾器定義工具三行代碼接入一個(gè)能力工具是智能體的“手”。框架里定義一個(gè)工具非常簡(jiǎn)單用裝飾器就行。from core import tool tool def query_order(order_id: str) - dict: 根據(jù)訂單號(hào)查詢訂單狀態(tài), 支持模糊匹配 # 這里寫(xiě)真實(shí)的業(yè)務(wù)查詢邏輯 return {order_id: order_id, status: 已發(fā)貨, logistics: SF123456}但這里有個(gè)容易被忽略的重點(diǎn)工具的函數(shù)名和 docstring 就是模型決定“什么時(shí)候該用這個(gè)工具”的唯一依據(jù)。很多開(kāi)發(fā)把 docstring 寫(xiě)得很隨意結(jié)果就是模型在真實(shí)場(chǎng)景里不知道該不該調(diào)用這個(gè)工具或者亂調(diào)用。我的實(shí)戰(zhàn)經(jīng)驗(yàn)是 docstring 要寫(xiě)清楚三件事工具職責(zé)是什么、什么場(chǎng)景下使用、參數(shù)的單位和邊界是什么。比如上面這個(gè) query_orderdocstring 里應(yīng)當(dāng)補(bǔ)充“當(dāng)用戶詢問(wèn)訂單物流、發(fā)貨狀態(tài)、簽收情況時(shí)使用。order_id 支持完整或部分訂單號(hào)?！?寫(xiě)清楚之后模型選工具的準(zhǔn)確率會(huì)明顯上升。這個(gè)經(jīng)驗(yàn)我在后面的評(píng)估章節(jié)還會(huì)提到。3.2 MCP 標(biāo)準(zhǔn)協(xié)議從此告別“每個(gè)系統(tǒng)寫(xiě)一套連接器”MCPModel Context Protocol在這套架構(gòu)里是一個(gè)連接外部系統(tǒng)的標(biāo)準(zhǔn)協(xié)議層。如果你接觸過(guò)的系統(tǒng)多一定會(huì)遇到這種情況企業(yè)內(nèi)部有 CRM、工單系統(tǒng)、數(shù)據(jù)庫(kù)、知識(shí)庫(kù)每個(gè)系統(tǒng)都要給智能體寫(xiě)一套 API 連接代碼維護(hù)成本極高。MCP 的思路是把“智能體如何連接外部數(shù)據(jù)/工具”標(biāo)準(zhǔn)化相當(dāng)于給智能體世界做了一個(gè)通用的 USB 接口。這套框架對(duì) MCP 的支持是內(nèi)建的一等公民from core.mcp import MCPTool # 定義一個(gè) MCP 連接會(huì)自動(dòng)加載工具列表 crm_tools MCPTool.from_server_url(http://internal-mcp-server:8000) agent Agent( ... tools[crm_tools, query_order], )框架會(huì)把 MCP 遠(yuǎn)端暴露的工具自動(dòng)展開(kāi)成當(dāng)前模型的工具 schema模型調(diào)用后通過(guò) MCP 協(xié)議把請(qǐng)求發(fā)回遠(yuǎn)端執(zhí)行。我在實(shí)際項(xiàng)目中把內(nèi)部知識(shí)庫(kù)、權(quán)限系統(tǒng)、訂單中心都做成了 MCP 服務(wù)智能體代碼里只需要掛載對(duì)應(yīng)工具業(yè)務(wù)系統(tǒng)完全不用感知 Agent 的存在。這個(gè)隔離性在團(tuán)隊(duì)協(xié)作里特別有價(jià)值——Agent 團(tuán)隊(duì)和業(yè)務(wù)系統(tǒng)團(tuán)隊(duì)可以完全獨(dú)立開(kāi)發(fā)。3.3 代碼執(zhí)行器沙箱里的“數(shù)字算力”除了外部 API 工具框架還提供了一個(gè)內(nèi)置的代碼執(zhí)行工具。這個(gè)工具有個(gè)很實(shí)際的使用場(chǎng)景需要計(jì)算但模型不擅長(zhǎng)精確計(jì)算時(shí)讓模型寫(xiě)代碼、沙箱執(zhí)行代碼、拿結(jié)果回答。比如用戶問(wèn)“從 1 到 100 里所有能被 7 整除的數(shù)之和是多少”大模型直接心算大概率會(huì)翻車(chē)但讓它寫(xiě)一段 Python 代碼就萬(wàn)無(wú)一失。框架內(nèi)置的代碼執(zhí)行器會(huì)在一個(gè)受限沙箱中運(yùn)行 Python 代碼有一個(gè)獨(dú)立的進(jìn)程環(huán)境會(huì)有資源上限控制并且會(huì)在執(zhí)行完成后把 stdout 和結(jié)果返回給模型。這個(gè)功能在生產(chǎn)環(huán)境要慎用。沙箱不等于絕對(duì)安全如果你的業(yè)務(wù)場(chǎng)景允許用戶間接控制智能體生成代碼并執(zhí)行那一定要在部署層面再做一層隔離比如放到獨(dú)立的容器或虛擬機(jī)。我在內(nèi)部系統(tǒng)里有一個(gè)小工具鏈就是只向白名單用戶開(kāi)放代碼執(zhí)行能力其他人觸發(fā)的代碼執(zhí)行請(qǐng)求一律拒絕。3.4 Agent Card讓智能體“可以被發(fā)現(xiàn)和調(diào)度”這個(gè)組件是比較容易被忽視但架構(gòu)意義很大的一環(huán)。Agent Card 是智能體的“元數(shù)據(jù)描述文件”里面包含智能體的名稱、功能描述、支持的工具列表、輸入輸出格式、使用約束、負(fù)責(zé)人等信息。你可能會(huì)問(wèn)這不就是寫(xiě)個(gè)文檔嗎其實(shí)不然。在多智能體系統(tǒng)里Agent Card 是路由調(diào)度和自動(dòng)協(xié)作的依據(jù)。框架內(nèi)置的 Agent Registry 會(huì)根據(jù) Agent Card 自動(dòng)注冊(cè)所有智能體當(dāng)有一個(gè)新的智能體需要被調(diào)用時(shí)調(diào)用方可以通過(guò)框架的 Agent 發(fā)現(xiàn)機(jī)制按能力描述去查找匹配。簡(jiǎn)單說(shuō)Agent Card 就是在回答“我這個(gè)智能體能干什么、該怎么調(diào)用”。在團(tuán)隊(duì)多人協(xié)作、智能體庫(kù)不斷膨脹的場(chǎng)景下這個(gè)標(biāo)準(zhǔn)化描述的價(jià)值會(huì)越來(lái)越大。我目前的做法是每個(gè)智能體上線前強(qiáng)制要求補(bǔ)全 Agent Card字段缺失不能上生產(chǎn)。4. 多智能體協(xié)作業(yè)務(wù)變復(fù)雜后的必修課4.1 三種主流編排模式各有什么適用場(chǎng)景當(dāng)業(yè)務(wù)復(fù)雜到單個(gè)智能體無(wú)法覆蓋時(shí)就需要多智能體協(xié)作?？蚣艿木幣艑又С秩N主流模式我逐個(gè)說(shuō)一下適用場(chǎng)景。順序編排Sequential任務(wù)嚴(yán)格按步驟走前一個(gè)智能體的輸出作為后一個(gè)智能體的輸入。適合流水線式任務(wù)比如“先做意圖識(shí)別再做信息抽取最后生成回答”。并行編排Parallel多個(gè)智能體同時(shí)處理不同子任務(wù)最后匯總結(jié)果。適合“用戶問(wèn)題涉及多個(gè)獨(dú)立維度”的場(chǎng)景比如同時(shí)查天氣、查交通、查餐廳三個(gè)智能體并行跑最后合并結(jié)果給用戶響應(yīng)耗時(shí)會(huì)顯著下降。層級(jí)編排Hierarchical有一個(gè)主控智能體負(fù)責(zé)任務(wù)分解和調(diào)度下面掛若干子智能體。適合任務(wù)類(lèi)型多、路由規(guī)則復(fù)雜的場(chǎng)景。主控智能體本質(zhì)上是一個(gè)“管理者”它根據(jù)用戶請(qǐng)求判斷該派活給誰(shuí)、怎么合并結(jié)果。我在項(xiàng)目里的實(shí)際經(jīng)驗(yàn)是不要一上來(lái)就做層級(jí)編排。層級(jí)編排雖然靈活但主控智能體的決策質(zhì)量會(huì)直接決定整個(gè)系統(tǒng)的成敗而且排查鏈條非常長(zhǎng)。能用順序或并行解決的優(yōu)先用簡(jiǎn)單方案。4.2 子智能體的通信與狀態(tài)傳遞多智能體之間怎么通信是另一個(gè)容易踩坑的點(diǎn)?？蚣艿耐ㄐ拍Ｐ筒徊捎谩爸悄荏w之間直接發(fā)消息”的方式而是通過(guò)共享的上下文數(shù)據(jù)區(qū)傳遞信息。一個(gè)典型的做法是定義一個(gè)共享的數(shù)據(jù)結(jié)構(gòu)主控智能體在派發(fā)子任務(wù)時(shí)寫(xiě)入任務(wù)描述和輸入?yún)?shù)子智能體執(zhí)行完后把結(jié)果寫(xiě)回同一個(gè)數(shù)據(jù)結(jié)構(gòu)由主控智能體讀取并匯總。from core import Agent, SequentialAgent, ParallelAgent sub_weather Agent(nameweather, ...) sub_traffic Agent(nametraffic, ...) # 并行編排示例 parallel ParallelAgent( agents[sub_weather, sub_traffic], merge_prompt將天氣和交通信息匯總成一段自然語(yǔ)言回復(fù)若信息缺失請(qǐng)注明。, ) result parallel.run(北京明天適合出行嗎)這里關(guān)鍵的“坑”是子智能體的輸出格式必須嚴(yán)格可控。如果子智能體回答一段自由文本主智能體再去做結(jié)構(gòu)化處理很容易丟失信息。我的做法是在子智能體的 instruction 里明確規(guī)定輸出格式例如“必須輸出 JSON 格式包含字段 weather_condition 和 temperature”。這樣主智能體的匯總壓力會(huì)小很多穩(wěn)定性也會(huì)有數(shù)量級(jí)提升。4.3 什么時(shí)候該拆多智能體什么時(shí)候不該拆這是我在項(xiàng)目評(píng)審時(shí)最常被問(wèn)到的問(wèn)題。很多人容易陷入“智能體越多越智能”的誤區(qū)但實(shí)際經(jīng)驗(yàn)是過(guò)度拆分只會(huì)帶來(lái)更多的失效點(diǎn)。我的判斷標(biāo)準(zhǔn)有三條工具集是否有明顯業(yè)務(wù)邊界。比如天氣查詢和訂單查詢完全是兩個(gè)領(lǐng)域的工具拆成兩個(gè) Agent 互不干擾邊界清晰。是否需要不同的模型配置。有的子任務(wù)需要低延遲小模型有的需要強(qiáng)推理大模型拆開(kāi)后可以按需配置。是否會(huì)頻繁出現(xiàn)工具選擇沖突。如果多個(gè)工具之間的調(diào)用關(guān)系經(jīng)常讓模型糾結(jié)比如“該調(diào)訂單接口還是調(diào)物流接口”拆成子智能體反而可以讓每個(gè) Agent 的指令更聚焦。反之如果業(yè)務(wù)工具集不大、調(diào)用關(guān)系簡(jiǎn)單一個(gè) Agent 掛所有工具就是最高效的方案。先單 Agent出現(xiàn)明確問(wèn)題時(shí)再拆分。5. 從 Demo 到生產(chǎn)部署、觀測(cè)與評(píng)估5.1 本地開(kāi)發(fā)調(diào)試從一個(gè)“可復(fù)現(xiàn)的會(huì)話”開(kāi)始本地開(kāi)發(fā)里最容易忽視的就是“可復(fù)現(xiàn)性”。很多做 Agent 的人調(diào)試靠“多聊幾遍碰運(yùn)氣”這樣效率極低?？蚣芴峁┝艘环N持久化的會(huì)話運(yùn)行模式可以保存完整的會(huì)話狀態(tài)到本地文件。from core.session import PersistentSession session PersistentSession(save_path./session_store/) agent Agent(..., session_managersession) # 第一次運(yùn)行后會(huì)話狀態(tài)會(huì)保存到本地目錄 # 后續(xù)調(diào)試可以指定加載某個(gè) session_id 復(fù)現(xiàn)同樣的上下文這個(gè)能力在實(shí)際調(diào)試時(shí)幫了我大忙。之前遇到“模型上一輪正常、這一輪突然開(kāi)始亂答”的問(wèn)題我直接把出問(wèn)題的 session 完整復(fù)現(xiàn)出來(lái)一條條看輸入輸出很快就定位到是上上輪某個(gè)工具返回了異常數(shù)據(jù)污染了上下文。沒(méi)有會(huì)話保存這種間歇性 bug 幾乎沒(méi)法查。5.2 服務(wù)化部署并發(fā)與資源隔離的兩道坎把一個(gè) Agent 從腳本變成線上服務(wù)核心要解決兩件事并發(fā)請(qǐng)求怎么處理、運(yùn)行資源怎么隔離。框架本身是無(wú)狀態(tài)的就是說(shuō)每個(gè)請(qǐng)求可以創(chuàng)建全新的 Agent 實(shí)例來(lái)運(yùn)行這讓橫向擴(kuò)展非常容易。但我在實(shí)踐中的經(jīng)驗(yàn)是一定要做 Agent 實(shí)例池化而不是每次請(qǐng)求都從零創(chuàng)建。原因是 Agent 的初始化階段會(huì)做工具 schema 的組裝和模型接口的預(yù)熱頻繁創(chuàng)建會(huì)白白增加延遲。我的做法是啟動(dòng)時(shí)預(yù)創(chuàng)建一組 Agent 實(shí)例配合一個(gè)簡(jiǎn)單的輪詢分發(fā)器。每個(gè)實(shí)例處理完當(dāng)前請(qǐng)求后回到池中等待下一個(gè)請(qǐng)求。同時(shí)要留意如果用了 Python 的多線程并發(fā)要注意模型客戶端的線程安全性盡量讓每個(gè)實(shí)例持有自己獨(dú)立的客戶端連接。5.3 可觀測(cè)性回調(diào)事件是排查問(wèn)題的“黑匣子”Agent 應(yīng)用跑起來(lái)之后最大的痛點(diǎn)就是“它是一個(gè)黑盒”。用戶問(wèn)了一個(gè)問(wèn)題中間發(fā)生了什么調(diào)用了哪些工具每輪模型輸出了什么如果不做觀測(cè)出了問(wèn)題完全沒(méi)有頭緒。框架提供了完整的回調(diào)機(jī)制可以掛鉤到 Agent 運(yùn)行的各個(gè)階段from core import AgentCallback class LoggingCallback(AgentCallback): def before_model_call(self, agent, session): # 記錄請(qǐng)求發(fā)給模型前的上下文概要 pass def after_tool_call(self, agent, tool_name, args, result): print(f[TOOL] {tool_name} 參數(shù){args} 結(jié)果{result}) def after_agent_completion(self, agent, response): # 記錄最終返回內(nèi)容 pass agent Agent(..., callbacks[LoggingCallback()])我強(qiáng)烈建議從上線的第一天就把全量回調(diào)日志接上。尤其是 after_tool_call 這個(gè)事件工具調(diào)用時(shí)的參數(shù)和結(jié)果一定要落日志這是排查“智能體憑空捏造數(shù)據(jù)”這一類(lèi)問(wèn)題的最快路徑。我有一次接到線上“回答結(jié)果與事實(shí)不符”的投訴打開(kāi)日志一看發(fā)現(xiàn)一個(gè)工具在返回結(jié)果里混入了調(diào)試用的假數(shù)據(jù)模型不知情就直接拿來(lái)用了。沒(méi)有回調(diào)日志這種問(wèn)題只能靠猜。5.4 智能體評(píng)估沒(méi)有評(píng)估體系就沒(méi)有迭代依據(jù)傳統(tǒng)軟件上線前靠單元測(cè)試和集成測(cè)試Agent 應(yīng)用也需要一套“評(píng)估集”。沒(méi)有評(píng)估集的 Agent 項(xiàng)目有一個(gè)通病改了一個(gè) Prompt不知道整體效果是變好了還是變差了只能靠感覺(jué)。框架提供了 Evaluator 模塊可以批量跑評(píng)估用例并且支持自定義評(píng)估指標(biāo)。我目前實(shí)踐的評(píng)估集分三層工具調(diào)用正確率給定一組用戶問(wèn)題檢查模型是否選擇了正確的工具、傳參是否正確。答案完整性對(duì)每個(gè)測(cè)試用例預(yù)設(shè)“必須覆蓋的要點(diǎn)”跑完后檢查回答是否覆蓋。格式合規(guī)性要求輸出必須符合 JSON schema 或特定模板跑完后做 schema 校驗(yàn)。這套評(píng)估集上線后我對(duì) Prompt 的每次調(diào)整都有了量化反饋。有一次我覺(jué)得新 Prompt 的“人設(shè)更好了”結(jié)果評(píng)估數(shù)據(jù)顯示工具誤調(diào)率從 3% 漲到 11%果斷回滾。沒(méi)有評(píng)估就跑生產(chǎn)本質(zhì)上是在裸奔。6. 實(shí)測(cè)踩坑記錄常見(jiàn)問(wèn)題的排查與解法6.1 上下文爆炸長(zhǎng)對(duì)話跑著跑著就“失憶”了這是所有 Agent 項(xiàng)目都會(huì)遇到的問(wèn)題?，F(xiàn)象是會(huì)話持續(xù)幾十輪后智能體開(kāi)始忘記早期用戶提供的關(guān)鍵信息比如用戶第一輪說(shuō)了“我預(yù)算 5000 元以內(nèi)”后面推薦的產(chǎn)品全是超預(yù)算的。排查思路先看框架的上下文管理配置確認(rèn) max_tokens 和裁剪策略是否合理。如果用的是純內(nèi)存上下文長(zhǎng)會(huì)話天然受限。我的解法是兩層策略第一對(duì)關(guān)鍵用戶信息做持久化記憶保存比如用戶的預(yù)算、偏好這類(lèi)信息在會(huì)話中通過(guò)工具調(diào)用寫(xiě)入外部存儲(chǔ)不依賴模型從歷史上下文里“回憶”第二設(shè)置合理的上下文上限超過(guò)上限時(shí)把早期不重要的對(duì)話歷史裁掉而不是一刀切全部保留。6.2 工具死循環(huán)模型在一個(gè)工具上反復(fù)調(diào)用不退出這個(gè)坑我在壓測(cè)時(shí)踩過(guò)。模型拿到一個(gè)工具返回結(jié)果后認(rèn)為結(jié)果不夠“精確”于是反復(fù)調(diào)用同一個(gè)工具每次傳入相似的參數(shù)一直循環(huán)停不下來(lái)?？蚣芾飳?duì)單次 Agent 運(yùn)行有最大工具調(diào)用輪次限制建議一上來(lái)就設(shè)置好agent Agent( ..., max_tool_calls_per_run10, # 單次回答最多調(diào)用 10 次工具 ) # 超過(guò)限制后框架會(huì)終止循環(huán)并返回當(dāng)前已生成的內(nèi)容設(shè)置這個(gè)限制的意義不僅是防死循環(huán)還有一個(gè)隱藏價(jià)值逼著你在設(shè)計(jì)工具時(shí)把工具做強(qiáng)。如果模型老是要通過(guò)多次調(diào)用來(lái)湊出一個(gè)答案經(jīng)常是因?yàn)閱蝹€(gè)工具的返回信息不完整需要通過(guò)合并多次調(diào)用來(lái)補(bǔ)全。與其加循環(huán)次數(shù)不如優(yōu)化工具返回讓一次調(diào)用就把模型需要的完整信息給全。6.3 沙箱代碼執(zhí)行的安全邊界代碼執(zhí)行工具方便但它是最容易出安全問(wèn)題的點(diǎn)。我見(jiàn)過(guò)有的團(tuán)隊(duì)把代碼執(zhí)行工具默認(rèn)打開(kāi)結(jié)果用戶輸入“幫我刪除當(dāng)前目錄所有文件”這種指令智能體真的生成并執(zhí)行了刪除命令。雖然沙箱會(huì)隔離一部分風(fēng)險(xiǎn)但絕不能把它當(dāng)成絕對(duì)保險(xiǎn)箱。我的建議是分層設(shè)防第一層代碼執(zhí)行工具默認(rèn)關(guān)閉只有在明確需要計(jì)算的場(chǎng)景才掛載第二層如果必須開(kāi)放要在工具層做命令白名單和文件路徑安全檢查第三層部署上用獨(dú)立容器跑代碼執(zhí)行服務(wù)與主服務(wù)做網(wǎng)絡(luò)隔離。這三個(gè)層級(jí)都做了才算“可以用”。6.4 并發(fā)下的狀態(tài)串?dāng)_Session 隔離沒(méi)做好的代價(jià)多用戶并發(fā)訪問(wèn)的時(shí)候如果 Session 管理沒(méi)做好最典型的故障是“用戶 A 問(wèn)了自己的問(wèn)題模型回答里卻出現(xiàn)了用戶 B 的訂單信息”。這是嚴(yán)重的事故級(jí)問(wèn)題。根因是 Agent 實(shí)例復(fù)用時(shí)沒(méi)有把 Session 狀態(tài)徹底隔離。排查方法檢查你有沒(méi)有把 Session 作為 Agent 運(yùn)行時(shí)的必傳參數(shù)。如果你在 Agent 實(shí)例上復(fù)用了同一個(gè)會(huì)話管理器不同請(qǐng)求都往同一個(gè)會(huì)話里塞上下文就一定會(huì)串。我的做法是每個(gè)用戶請(qǐng)求創(chuàng)建一個(gè)獨(dú)立的 SessionSession ID 用用戶 ID 加請(qǐng)求 ID 拼接同時(shí)把會(huì)話數(shù)據(jù)放到獨(dú)立的存儲(chǔ)中本地文件/Redis 均可。容器實(shí)例可以復(fù)用但 Session 必須是請(qǐng)求級(jí)的。這個(gè)原則我在代碼評(píng)審時(shí)都會(huì)反復(fù)強(qiáng)調(diào)。6.5 調(diào)試小技巧把“模型視角”打出來(lái)最后一個(gè)很實(shí)用的技巧排查問(wèn)題時(shí)把每次發(fā)送給模型的完整上下文系統(tǒng)指令、歷史消息、工具結(jié)果原樣 dump 出來(lái)看?？蚣艿娜罩灸K支持設(shè)置 debug 級(jí)別開(kāi)啟后每個(gè)請(qǐng)求發(fā)出的完整 payload 都會(huì)輸出。這個(gè)技巧幫你糾正一種常見(jiàn)錯(cuò)覺(jué)你以為是“模型變笨了”實(shí)際上往往是你發(fā)給模型的上下文已經(jīng)是一團(tuán)亂麻了。比如某個(gè)工具返回了一個(gè)超長(zhǎng)的 JSON占了上下文一大半模型自然就會(huì)被帶偏。把模型視角打出來(lái)看一眼很多“玄學(xué) bug”當(dāng)場(chǎng)就能解釋清楚。我現(xiàn)在做 Agent 項(xiàng)目工具箱里最常用的是三件套可復(fù)現(xiàn)的 Session、全量回調(diào)日志、debug 級(jí)別的上下文 dump。這三樣搭起來(lái)90% 的問(wèn)題都能在十分鐘內(nèi)定位到具體環(huán)節(jié)。剩下 10% 是模型本身的行為波動(dòng)那就要靠評(píng)估集來(lái)持續(xù)跟蹤了。