框架全解析：核心組件、多智能體協(xié)作與生產(chǎn)實(shí)踐)
1. 先說清楚為什么智能體開發(fā)需要一套獨(dú)立框架最近半年我一直在折騰智能體應(yīng)用從最開始的“調(diào)個(gè)大模型 API 然后寫死 Prompt”一路做到真正能穩(wěn)定跑業(yè)務(wù)的系統(tǒng)。中間踩了不少坑也把市面主流的幾套方案都過了一遍。最后在某大廠開源的智能體開發(fā)套件上停了下來從 demo 一直推到生產(chǎn)環(huán)境?；剡^頭看這套框架解決的問題不是“能不能調(diào)模型”而是“怎么讓智能體像一個(gè)正規(guī)軟件一樣被開發(fā)、調(diào)試、運(yùn)維”。如果你自己從頭寫過 Agent一定體會(huì)過那種失控感。早期我做過一個(gè)簡(jiǎn)單的問答機(jī)器人邏輯就是一個(gè) while 循環(huán)把用戶問題拼進(jìn) Prompt調(diào)模型看返回結(jié)果里有沒有工具調(diào)用請(qǐng)求如果有就去執(zhí)行工具把結(jié)果再拼回去再調(diào)一次模型。兩三個(gè)工具的時(shí)候還好等工具到了十幾個(gè)模型開始亂選工具、上下文越拼越長(zhǎng)、多輪對(duì)話狀態(tài)經(jīng)常串場(chǎng)代碼基本就成了一坨只能跑通 demo 的“一次性腳本”。這套開源套件把上面這些臟活抽象成了標(biāo)準(zhǔn)組件模型統(tǒng)一接入、工具自動(dòng)分發(fā)、上下文自動(dòng)管理、回調(diào)事件追蹤、多智能體編排、沙箱代碼執(zhí)行、Agent 能力描述等等。你要做的只是定義 Agent 的行為和工具框架負(fù)責(zé)把模型推理循環(huán)跑順。這篇文章我就以這套架構(gòu)為主線把核心組件逐個(gè)拆開講最后給一份可以直接抄作業(yè)的落地實(shí)踐。適合看的同學(xué)有三類一是已經(jīng)用 LangChain 這類通用編排框架但覺得不夠底層的二是準(zhǔn)備把 Agent 從 demo 推向生產(chǎn)的后端或算法工程師三是想搞懂智能體框架內(nèi)部設(shè)計(jì)的產(chǎn)品或技術(shù)負(fù)責(zé)人?；A(chǔ)要求不高只要會(huì) Python、知道大模型 API 大概怎么調(diào)用就能跟著走完。2. 先記住這張組件地圖一個(gè) Agent 從啟動(dòng)到跑完的完整鏈條2.1 Agent 抽象框架里的“一切皆 Agent”這套框架最核心的抽象就是 Agent 類。你可以把它理解成“一個(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 工具回答用戶問題。, tools[get_weather], )這段代碼里有一個(gè)容易被忽略的關(guān)鍵點(diǎn)Agent 的 name 不是隨便起的。它在框架里承擔(dān)兩個(gè)職能一是日志和追蹤的標(biāo)識(shí)二是在多智能體協(xié)作時(shí)作為路由尋址的 ID。我見過有團(tuán)隊(duì)把 name 全寫成 default結(jié)果部署到線上出了故障根本沒法定位是哪個(gè)子智能體在跑排查成本直接翻倍。instruction 的作用也值得展開說。它不只是一個(gè)“人設(shè)提示詞”框架在設(shè)計(jì)上把它當(dāng)作智能體“系統(tǒng)級(jí)行為約束”來用。每輪推理時(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í)我沒太在意覺得“不就是封裝一層 API 調(diào)用嗎”后來在對(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í)際問題統(tǒng)一接口不同大模型的請(qǐng)求格式差異被抹平業(yè)務(wù)代碼里永遠(yuǎn)不用寫 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 的人都逃不過一個(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)壓縮或裁剪過期消息在每輪工具調(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)我后來做壓測(cè)時(shí)體會(huì)很深——簡(jiǎn)單的先進(jìn)先出策略在長(zhǎng)對(duì)話場(chǎng)景會(huì)讓智能體“失憶”而框架的保留策略明顯更合理。如果你有更復(fù)雜的記憶訴求框架也支持通過 Memory 類接入外部記憶存儲(chǔ)比如向量數(shù)據(jù)庫(kù)?；A(chǔ)場(chǎng)景下用內(nèi)置內(nèi)存就夠只有一個(gè)注意點(diǎn)內(nèi)置上下文默認(rèn)不會(huì)跨 Session 持久化重啟服務(wù)后對(duì)話歷史就沒了。需要持久化的場(chǎng)景得自己接存儲(chǔ)。2.4 推理循環(huán)框架替你寫好了那個(gè) while 循環(huán)我前面提到自己手寫的 while 循環(huán)框架內(nèi)部其實(shí)也是類似的循環(huán)但它多做了幾件關(guān)鍵的事?？蚣艿耐评硌h(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ì)展開講“死循環(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), 支持模糊匹配 # 這里寫真實(shí)的業(yè)務(wù)查詢邏輯 return {order_id: order_id, status: 已發(fā)貨, logistics: SF123456}但這里有個(gè)容易被忽略的重點(diǎn)工具的函數(shù)名和 docstring 就是模型決定“什么時(shí)候該用這個(gè)工具”的唯一依據(jù)。很多開發(fā)把 docstring 寫得很隨意結(jié)果就是模型在真實(shí)場(chǎng)景里不知道該不該調(diào)用這個(gè)工具或者亂調(diào)用。我的實(shí)戰(zhàn)經(jīng)驗(yàn)是 docstring 要寫清楚三件事工具職責(zé)是什么、什么場(chǎng)景下使用、參數(shù)的單位和邊界是什么。比如上面這個(gè) query_orderdocstring 里應(yīng)當(dāng)補(bǔ)充“當(dāng)用戶詢問訂單物流、發(fā)貨狀態(tài)、簽收情況時(shí)使用。order_id 支持完整或部分訂單號(hào)。” 寫清楚之后模型選工具的準(zhǔn)確率會(huì)明顯上升。這個(gè)經(jīng)驗(yàn)我在后面的評(píng)估章節(jié)還會(huì)提到。3.2 MCP 標(biāo)準(zhǔn)協(xié)議從此告別“每個(gè)系統(tǒng)寫一套連接器”MCPModel Context Protocol在這套架構(gòu)里是一個(gè)連接外部系統(tǒng)的標(biāo)準(zhǔn)協(xié)議層。如果你接觸過的系統(tǒng)多一定會(huì)遇到這種情況企業(yè)內(nèi)部有 CRM、工單系統(tǒng)、數(shù)據(jù)庫(kù)、知識(shí)庫(kù)每個(gè)系統(tǒng)都要給智能體寫一套 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)展開成當(dāng)前模型的工具 schema模型調(diào)用后通過 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ú)立開發(fā)。3.3 代碼執(zhí)行器沙箱里的“數(shù)字算力”除了外部 API 工具框架還提供了一個(gè)內(nèi)置的代碼執(zhí)行工具。這個(gè)工具有個(gè)很實(shí)際的使用場(chǎng)景需要計(jì)算但模型不擅長(zhǎng)精確計(jì)算時(shí)讓模型寫代碼、沙箱執(zhí)行代碼、拿結(jié)果回答。比如用戶問“從 1 到 100 里所有能被 7 整除的數(shù)之和是多少”大模型直接心算大概率會(huì)翻車但讓它寫一段 Python 代碼就萬無一失?？蚣軆?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è)小工具鏈就是只向白名單用戶開放代碼執(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ì)問這不就是寫個(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)用方可以通過框架的 Agent 發(fā)現(xiàn)機(jī)制按能力描述去查找匹配。簡(jiǎn)單說Agent Card 就是在回答“我這個(gè)智能體能干什么、該怎么調(diào)用”。在團(tuán)隊(duì)多人協(xié)作、智能體庫(kù)不斷膨脹的場(chǎng)景下這個(gè)標(biāo)準(zhǔn)化描述的價(jià)值會(huì)越來越大。我目前的做法是每個(gè)智能體上線前強(qiáng)制要求補(bǔ)全 Agent Card字段缺失不能上生產(chǎn)。4. 多智能體協(xié)作業(yè)務(wù)變復(fù)雜后的必修課4.1 三種主流編排模式各有什么適用場(chǎng)景當(dāng)業(yè)務(wù)復(fù)雜到單個(gè)智能體無法覆蓋時(shí)就需要多智能體協(xié)作?？蚣艿木幣艑又С秩N主流模式我逐個(gè)說一下適用場(chǎng)景。順序編排Sequential任務(wù)嚴(yán)格按步驟走前一個(gè)智能體的輸出作為后一個(gè)智能體的輸入。適合流水線式任務(wù)比如“先做意圖識(shí)別再做信息抽取最后生成回答”。并行編排Parallel多個(gè)智能體同時(shí)處理不同子任務(wù)最后匯總結(jié)果。適合“用戶問題涉及多個(gè)獨(dú)立維度”的場(chǎng)景比如同時(shí)查天氣、查交通、查餐廳三個(gè)智能體并行跑最后合并結(jié)果給用戶響應(yīng)耗時(shí)會(huì)顯著下降。層級(jí)編排Hierarchical有一個(gè)主控智能體負(fù)責(zé)任務(wù)分解和調(diào)度下面掛若干子智能體。適合任務(wù)類型多、路由規(guī)則復(fù)雜的場(chǎng)景。主控智能體本質(zhì)上是一個(gè)“管理者”它根據(jù)用戶請(qǐng)求判斷該派活給誰、怎么合并結(jié)果。我在項(xiàng)目里的實(shí)際經(jīng)驗(yàn)是不要一上來就做層級(jí)編排。層級(jí)編排雖然靈活但主控智能體的決策質(zhì)量會(huì)直接決定整個(gè)系統(tǒng)的成敗而且排查鏈條非常長(zhǎng)。能用順序或并行解決的優(yōu)先用簡(jiǎn)單方案。4.2 子智能體的通信與狀態(tài)傳遞多智能體之間怎么通信是另一個(gè)容易踩坑的點(diǎn)。框架的通信模型不采用“智能體之間直接發(fā)消息”的方式而是通過共享的上下文數(shù)據(jù)區(qū)傳遞信息。一個(gè)典型的做法是定義一個(gè)共享的數(shù)據(jù)結(jié)構(gòu)主控智能體在派發(fā)子任務(wù)時(shí)寫入任務(wù)描述和輸入?yún)?shù)子智能體執(zhí)行完后把結(jié)果寫回同一個(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將天氣和交通信息匯總成一段自然語言回復(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í)最常被問到的問題。很多人容易陷入“智能體越多越智能”的誤區(qū)但實(shí)際經(jīng)驗(yàn)是過度拆分只會(huì)帶來更多的失效點(diǎn)。我的判斷標(biāo)準(zhǔn)有三條工具集是否有明顯業(yè)務(wù)邊界。比如天氣查詢和訂單查詢完全是兩個(gè)領(lǐng)域的工具拆成兩個(gè) Agent 互不干擾邊界清晰。是否需要不同的模型配置。有的子任務(wù)需要低延遲小模型有的需要強(qiáng)推理大模型拆開后可以按需配置。是否會(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)明確問題時(shí)再拆分。5. 從 Demo 到生產(chǎn)部署、觀測(cè)與評(píng)估5.1 本地開發(fā)調(diào)試從一個(gè)“可復(fù)現(xiàn)的會(huì)話”開始本地開發(fā)里最容易忽視的就是“可復(fù)現(xiàn)性”。很多做 Agent 的人調(diào)試靠“多聊幾遍碰運(yù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í)幫了我大忙。之前遇到“模型上一輪正常、這一輪突然開始亂答”的問題我直接把出問題的 session 完整復(fù)現(xiàn)出來一條條看輸入輸出很快就定位到是上上輪某個(gè)工具返回了異常數(shù)據(jù)污染了上下文。沒有會(huì)話保存這種間歇性 bug 幾乎沒法查。5.2 服務(wù)化部署并發(fā)與資源隔離的兩道坎把一個(gè) Agent 從腳本變成線上服務(wù)核心要解決兩件事并發(fā)請(qǐng)求怎么處理、運(yùn)行資源怎么隔離?？蚣鼙旧硎菬o狀態(tài)的就是說每個(gè)請(qǐng)求可以創(chuàng)建全新的 Agent 實(shí)例來運(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)事件是排查問題的“黑匣子”Agent 應(yīng)用跑起來之后最大的痛點(diǎn)就是“它是一個(gè)黑盒”。用戶問了一個(gè)問題中間發(fā)生了什么調(diào)用了哪些工具每輪模型輸出了什么如果不做觀測(cè)出了問題完全沒有頭緒?？蚣芴峁┝送暾幕卣{(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ù)”這一類問題的最快路徑。我有一次接到線上“回答結(jié)果與事實(shí)不符”的投訴打開日志一看發(fā)現(xiàn)一個(gè)工具在返回結(jié)果里混入了調(diào)試用的假數(shù)據(jù)模型不知情就直接拿來用了。沒有回調(diào)日志這種問題只能靠猜。5.4 智能體評(píng)估沒有評(píng)估體系就沒有迭代依據(jù)傳統(tǒng)軟件上線前靠單元測(cè)試和集成測(cè)試Agent 應(yīng)用也需要一套“評(píng)估集”。沒有評(píng)估集的 Agent 項(xiàng)目有一個(gè)通病改了一個(gè) Prompt不知道整體效果是變好了還是變差了只能靠感覺。框架提供了 Evaluator 模塊可以批量跑評(píng)估用例并且支持自定義評(píng)估指標(biāo)。我目前實(shí)踐的評(píng)估集分三層工具調(diào)用正確率給定一組用戶問題檢查模型是否選擇了正確的工具、傳參是否正確。答案完整性對(duì)每個(gè)測(cè)試用例預(yù)設(shè)“必須覆蓋的要點(diǎn)”跑完后檢查回答是否覆蓋。格式合規(guī)性要求輸出必須符合 JSON schema 或特定模板跑完后做 schema 校驗(yàn)。這套評(píng)估集上線后我對(duì) Prompt 的每次調(diào)整都有了量化反饋。有一次我覺得新 Prompt 的“人設(shè)更好了”結(jié)果評(píng)估數(shù)據(jù)顯示工具誤調(diào)率從 3% 漲到 11%果斷回滾。沒有評(píng)估就跑生產(chǎn)本質(zhì)上是在裸奔。6. 實(shí)測(cè)踩坑記錄常見問題的排查與解法6.1 上下文爆炸長(zhǎng)對(duì)話跑著跑著就“失憶”了這是所有 Agent 項(xiàng)目都會(huì)遇到的問題?，F(xiàn)象是會(huì)話持續(xù)幾十輪后智能體開始忘記早期用戶提供的關(guān)鍵信息比如用戶第一輪說了“我預(yù)算 5000 元以內(nèi)”后面推薦的產(chǎn)品全是超預(yù)算的。排查思路先看框架的上下文管理配置確認(rèn) max_tokens 和裁剪策略是否合理。如果用的是純內(nèi)存上下文長(zhǎng)會(huì)話天然受限。我的解法是兩層策略第一對(duì)關(guān)鍵用戶信息做持久化記憶保存比如用戶的預(yù)算、偏好這類信息在會(huì)話中通過工具調(diào)用寫入外部存儲(chǔ)不依賴模型從歷史上下文里“回憶”第二設(shè)置合理的上下文上限超過上限時(shí)把早期不重要的對(duì)話歷史裁掉而不是一刀切全部保留。6.2 工具死循環(huán)模型在一個(gè)工具上反復(fù)調(diào)用不退出這個(gè)坑我在壓測(cè)時(shí)踩過。模型拿到一個(gè)工具返回結(jié)果后認(rèn)為結(jié)果不夠“精確”于是反復(fù)調(diào)用同一個(gè)工具每次傳入相似的參數(shù)一直循環(huán)停不下來?？蚣芾飳?duì)單次 Agent 運(yùn)行有最大工具調(diào)用輪次限制建議一上來就設(shè)置好agent Agent( ..., max_tool_calls_per_run10, # 單次回答最多調(diào)用 10 次工具 ) # 超過限制后框架會(huì)終止循環(huán)并返回當(dāng)前已生成的內(nèi)容設(shè)置這個(gè)限制的意義不僅是防死循環(huán)還有一個(gè)隱藏價(jià)值逼著你在設(shè)計(jì)工具時(shí)把工具做強(qiáng)。如果模型老是要通過多次調(diào)用來湊出一個(gè)答案經(jīng)常是因?yàn)閱蝹€(gè)工具的返回信息不完整需要通過合并多次調(diào)用來補(bǔ)全。與其加循環(huán)次數(shù)不如優(yōu)化工具返回讓一次調(diào)用就把模型需要的完整信息給全。6.3 沙箱代碼執(zhí)行的安全邊界代碼執(zhí)行工具方便但它是最容易出安全問題的點(diǎn)。我見過有的團(tuán)隊(duì)把代碼執(zhí)行工具默認(rèn)打開結(jié)果用戶輸入“幫我刪除當(dāng)前目錄所有文件”這種指令智能體真的生成并執(zhí)行了刪除命令。雖然沙箱會(huì)隔離一部分風(fēng)險(xiǎn)但絕不能把它當(dāng)成絕對(duì)保險(xiǎn)箱。我的建議是分層設(shè)防第一層代碼執(zhí)行工具默認(rèn)關(guān)閉只有在明確需要計(jì)算的場(chǎng)景才掛載第二層如果必須開放要在工具層做命令白名單和文件路徑安全檢查第三層部署上用獨(dú)立容器跑代碼執(zhí)行服務(wù)與主服務(wù)做網(wǎng)絡(luò)隔離。這三個(gè)層級(jí)都做了才算“可以用”。6.4 并發(fā)下的狀態(tài)串?dāng)_Session 隔離沒做好的代價(jià)多用戶并發(fā)訪問的時(shí)候如果 Session 管理沒做好最典型的故障是“用戶 A 問了自己的問題模型回答里卻出現(xiàn)了用戶 B 的訂單信息”。這是嚴(yán)重的事故級(jí)問題。根因是 Agent 實(shí)例復(fù)用時(shí)沒有把 Session 狀態(tà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)試小技巧把“模型視角”打出來最后一個(gè)很實(shí)用的技巧排查問題時(shí)把每次發(fā)送給模型的完整上下文系統(tǒng)指令、歷史消息、工具結(jié)果原樣 dump 出來看?？蚣艿娜罩灸K支持設(shè)置 debug 級(jí)別開啟后每個(gè)請(qǐng)求發(fā)出的完整 payload 都會(huì)輸出。這個(gè)技巧幫你糾正一種常見錯(cuò)覺你以為是“模型變笨了”實(shí)際上往往是你發(fā)給模型的上下文已經(jīng)是一團(tuán)亂麻了。比如某個(gè)工具返回了一個(gè)超長(zhǎng)的 JSON占了上下文一大半模型自然就會(huì)被帶偏。把模型視角打出來看一眼很多“玄學(xué) bug”當(dāng)場(chǎng)就能解釋清楚。我現(xiàn)在做 Agent 項(xiàng)目工具箱里最常用的是三件套可復(fù)現(xiàn)的 Session、全量回調(diào)日志、debug 級(jí)別的上下文 dump。這三樣搭起來90% 的問題都能在十分鐘內(nèi)定位到具體環(huán)節(jié)。剩下 10% 是模型本身的行為波動(dòng)那就要靠評(píng)估集來持續(xù)跟蹤了。 智能體開發(fā)框架全解析：核心組件、多智能體協(xié)作與生產(chǎn)實(shí)踐
1. 先說清楚為什么智能體開發(fā)需要一套獨(dú)立框架最近半年我一直在折騰智能體應(yīng)用從最開始的“調(diào)個(gè)大模型 API 然后寫死 Prompt”一路做到真正能穩(wěn)定跑業(yè)務(wù)的系統(tǒng)。中間踩了不少坑也把市面主流的幾套方案都過了一遍。最后在某大廠開源的智能體開發(fā)套件上停了下來從 demo 一直推到生產(chǎn)環(huán)境?；剡^頭看這套框架解決的問題不是“能不能調(diào)模型”而是“怎么讓智能體像一個(gè)正規(guī)軟件一樣被開發(fā)、調(diào)試、運(yùn)維”。如果你自己從頭寫過 Agent一定體會(huì)過那種失控感。早期我做過一個(gè)簡(jiǎn)單的問答機(jī)器人邏輯就是一個(gè) while 循環(huán)把用戶問題拼進(jìn) Prompt調(diào)模型看返回結(jié)果里有沒有工具調(diào)用請(qǐng)求如果有就去執(zhí)行工具把結(jié)果再拼回去再調(diào)一次模型。兩三個(gè)工具的時(shí)候還好等工具到了十幾個(gè)模型開始亂選工具、上下文越拼越長(zhǎng)、多輪對(duì)話狀態(tài)經(jīng)常串場(chǎng)代碼基本就成了一坨只能跑通 demo 的“一次性腳本”。這套開源套件把上面這些臟活抽象成了標(biāo)準(zhǔn)組件模型統(tǒng)一接入、工具自動(dòng)分發(fā)、上下文自動(dòng)管理、回調(diào)事件追蹤、多智能體編排、沙箱代碼執(zhí)行、Agent 能力描述等等。你要做的只是定義 Agent 的行為和工具框架負(fù)責(zé)把模型推理循環(huán)跑順。這篇文章我就以這套架構(gòu)為主線把核心組件逐個(gè)拆開講最后給一份可以直接抄作業(yè)的落地實(shí)踐。適合看的同學(xué)有三類一是已經(jīng)用 LangChain 這類通用編排框架但覺得不夠底層的二是準(zhǔn)備把 Agent 從 demo 推向生產(chǎn)的后端或算法工程師三是想搞懂智能體框架內(nèi)部設(shè)計(jì)的產(chǎn)品或技術(shù)負(fù)責(zé)人?；A(chǔ)要求不高只要會(huì) Python、知道大模型 API 大概怎么調(diào)用就能跟著走完。2. 先記住這張組件地圖一個(gè) Agent 從啟動(dòng)到跑完的完整鏈條2.1 Agent 抽象框架里的“一切皆 Agent”這套框架最核心的抽象就是 Agent 類。你可以把它理解成“一個(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 工具回答用戶問題。, tools[get_weather], )這段代碼里有一個(gè)容易被忽略的關(guān)鍵點(diǎn)Agent 的 name 不是隨便起的。它在框架里承擔(dān)兩個(gè)職能一是日志和追蹤的標(biāo)識(shí)二是在多智能體協(xié)作時(shí)作為路由尋址的 ID。我見過有團(tuán)隊(duì)把 name 全寫成 default結(jié)果部署到線上出了故障根本沒法定位是哪個(gè)子智能體在跑排查成本直接翻倍。instruction 的作用也值得展開說。它不只是一個(gè)“人設(shè)提示詞”框架在設(shè)計(jì)上把它當(dāng)作智能體“系統(tǒng)級(jí)行為約束”來用。每輪推理時(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í)我沒太在意覺得“不就是封裝一層 API 調(diào)用嗎”后來在對(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í)際問題統(tǒng)一接口不同大模型的請(qǐng)求格式差異被抹平業(yè)務(wù)代碼里永遠(yuǎn)不用寫 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 的人都逃不過一個(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)壓縮或裁剪過期消息在每輪工具調(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)我后來做壓測(cè)時(shí)體會(huì)很深——簡(jiǎn)單的先進(jìn)先出策略在長(zhǎng)對(duì)話場(chǎng)景會(huì)讓智能體“失憶”而框架的保留策略明顯更合理。如果你有更復(fù)雜的記憶訴求框架也支持通過 Memory 類接入外部記憶存儲(chǔ)比如向量數(shù)據(jù)庫(kù)?；A(chǔ)場(chǎng)景下用內(nèi)置內(nèi)存就夠只有一個(gè)注意點(diǎn)內(nèi)置上下文默認(rèn)不會(huì)跨 Session 持久化重啟服務(wù)后對(duì)話歷史就沒了。需要持久化的場(chǎng)景得自己接存儲(chǔ)。2.4 推理循環(huán)框架替你寫好了那個(gè) while 循環(huán)我前面提到自己手寫的 while 循環(huán)框架內(nèi)部其實(shí)也是類似的循環(huán)但它多做了幾件關(guān)鍵的事?？蚣艿耐评硌h(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ì)展開講“死循環(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), 支持模糊匹配 # 這里寫真實(shí)的業(yè)務(wù)查詢邏輯 return {order_id: order_id, status: 已發(fā)貨, logistics: SF123456}但這里有個(gè)容易被忽略的重點(diǎn)工具的函數(shù)名和 docstring 就是模型決定“什么時(shí)候該用這個(gè)工具”的唯一依據(jù)。很多開發(fā)把 docstring 寫得很隨意結(jié)果就是模型在真實(shí)場(chǎng)景里不知道該不該調(diào)用這個(gè)工具或者亂調(diào)用。我的實(shí)戰(zhàn)經(jīng)驗(yàn)是 docstring 要寫清楚三件事工具職責(zé)是什么、什么場(chǎng)景下使用、參數(shù)的單位和邊界是什么。比如上面這個(gè) query_orderdocstring 里應(yīng)當(dāng)補(bǔ)充“當(dāng)用戶詢問訂單物流、發(fā)貨狀態(tài)、簽收情況時(shí)使用。order_id 支持完整或部分訂單號(hào)。” 寫清楚之后模型選工具的準(zhǔn)確率會(huì)明顯上升。這個(gè)經(jīng)驗(yàn)我在后面的評(píng)估章節(jié)還會(huì)提到。3.2 MCP 標(biāo)準(zhǔn)協(xié)議從此告別“每個(gè)系統(tǒng)寫一套連接器”MCPModel Context Protocol在這套架構(gòu)里是一個(gè)連接外部系統(tǒng)的標(biāo)準(zhǔn)協(xié)議層。如果你接觸過的系統(tǒng)多一定會(huì)遇到這種情況企業(yè)內(nèi)部有 CRM、工單系統(tǒng)、數(shù)據(jù)庫(kù)、知識(shí)庫(kù)每個(gè)系統(tǒng)都要給智能體寫一套 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)展開成當(dāng)前模型的工具 schema模型調(diào)用后通過 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ú)立開發(fā)。3.3 代碼執(zhí)行器沙箱里的“數(shù)字算力”除了外部 API 工具框架還提供了一個(gè)內(nèi)置的代碼執(zhí)行工具。這個(gè)工具有個(gè)很實(shí)際的使用場(chǎng)景需要計(jì)算但模型不擅長(zhǎng)精確計(jì)算時(shí)讓模型寫代碼、沙箱執(zhí)行代碼、拿結(jié)果回答。比如用戶問“從 1 到 100 里所有能被 7 整除的數(shù)之和是多少”大模型直接心算大概率會(huì)翻車但讓它寫一段 Python 代碼就萬無一失?？蚣軆?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è)小工具鏈就是只向白名單用戶開放代碼執(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ì)問這不就是寫個(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)用方可以通過框架的 Agent 發(fā)現(xiàn)機(jī)制按能力描述去查找匹配。簡(jiǎn)單說Agent Card 就是在回答“我這個(gè)智能體能干什么、該怎么調(diào)用”。在團(tuán)隊(duì)多人協(xié)作、智能體庫(kù)不斷膨脹的場(chǎng)景下這個(gè)標(biāo)準(zhǔn)化描述的價(jià)值會(huì)越來越大。我目前的做法是每個(gè)智能體上線前強(qiáng)制要求補(bǔ)全 Agent Card字段缺失不能上生產(chǎn)。4. 多智能體協(xié)作業(yè)務(wù)變復(fù)雜后的必修課4.1 三種主流編排模式各有什么適用場(chǎng)景當(dāng)業(yè)務(wù)復(fù)雜到單個(gè)智能體無法覆蓋時(shí)就需要多智能體協(xié)作?？蚣艿木幣艑又С秩N主流模式我逐個(gè)說一下適用場(chǎng)景。順序編排Sequential任務(wù)嚴(yán)格按步驟走前一個(gè)智能體的輸出作為后一個(gè)智能體的輸入。適合流水線式任務(wù)比如“先做意圖識(shí)別再做信息抽取最后生成回答”。并行編排Parallel多個(gè)智能體同時(shí)處理不同子任務(wù)最后匯總結(jié)果。適合“用戶問題涉及多個(gè)獨(dú)立維度”的場(chǎng)景比如同時(shí)查天氣、查交通、查餐廳三個(gè)智能體并行跑最后合并結(jié)果給用戶響應(yīng)耗時(shí)會(huì)顯著下降。層級(jí)編排Hierarchical有一個(gè)主控智能體負(fù)責(zé)任務(wù)分解和調(diào)度下面掛若干子智能體。適合任務(wù)類型多、路由規(guī)則復(fù)雜的場(chǎng)景。主控智能體本質(zhì)上是一個(gè)“管理者”它根據(jù)用戶請(qǐng)求判斷該派活給誰、怎么合并結(jié)果。我在項(xiàng)目里的實(shí)際經(jīng)驗(yàn)是不要一上來就做層級(jí)編排。層級(jí)編排雖然靈活但主控智能體的決策質(zhì)量會(huì)直接決定整個(gè)系統(tǒng)的成敗而且排查鏈條非常長(zhǎng)。能用順序或并行解決的優(yōu)先用簡(jiǎn)單方案。4.2 子智能體的通信與狀態(tài)傳遞多智能體之間怎么通信是另一個(gè)容易踩坑的點(diǎn)。框架的通信模型不采用“智能體之間直接發(fā)消息”的方式而是通過共享的上下文數(shù)據(jù)區(qū)傳遞信息。一個(gè)典型的做法是定義一個(gè)共享的數(shù)據(jù)結(jié)構(gòu)主控智能體在派發(fā)子任務(wù)時(shí)寫入任務(wù)描述和輸入?yún)?shù)子智能體執(zhí)行完后把結(jié)果寫回同一個(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將天氣和交通信息匯總成一段自然語言回復(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í)最常被問到的問題。很多人容易陷入“智能體越多越智能”的誤區(qū)但實(shí)際經(jīng)驗(yàn)是過度拆分只會(huì)帶來更多的失效點(diǎn)。我的判斷標(biāo)準(zhǔn)有三條工具集是否有明顯業(yè)務(wù)邊界。比如天氣查詢和訂單查詢完全是兩個(gè)領(lǐng)域的工具拆成兩個(gè) Agent 互不干擾邊界清晰。是否需要不同的模型配置。有的子任務(wù)需要低延遲小模型有的需要強(qiáng)推理大模型拆開后可以按需配置。是否會(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)明確問題時(shí)再拆分。5. 從 Demo 到生產(chǎn)部署、觀測(cè)與評(píng)估5.1 本地開發(fā)調(diào)試從一個(gè)“可復(fù)現(xiàn)的會(huì)話”開始本地開發(fā)里最容易忽視的就是“可復(fù)現(xiàn)性”。很多做 Agent 的人調(diào)試靠“多聊幾遍碰運(yù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í)幫了我大忙。之前遇到“模型上一輪正常、這一輪突然開始亂答”的問題我直接把出問題的 session 完整復(fù)現(xiàn)出來一條條看輸入輸出很快就定位到是上上輪某個(gè)工具返回了異常數(shù)據(jù)污染了上下文。沒有會(huì)話保存這種間歇性 bug 幾乎沒法查。5.2 服務(wù)化部署并發(fā)與資源隔離的兩道坎把一個(gè) Agent 從腳本變成線上服務(wù)核心要解決兩件事并發(fā)請(qǐng)求怎么處理、運(yùn)行資源怎么隔離?？蚣鼙旧硎菬o狀態(tài)的就是說每個(gè)請(qǐng)求可以創(chuàng)建全新的 Agent 實(shí)例來運(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)事件是排查問題的“黑匣子”Agent 應(yīng)用跑起來之后最大的痛點(diǎn)就是“它是一個(gè)黑盒”。用戶問了一個(gè)問題中間發(fā)生了什么調(diào)用了哪些工具每輪模型輸出了什么如果不做觀測(cè)出了問題完全沒有頭緒?？蚣芴峁┝送暾幕卣{(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ù)”這一類問題的最快路徑。我有一次接到線上“回答結(jié)果與事實(shí)不符”的投訴打開日志一看發(fā)現(xiàn)一個(gè)工具在返回結(jié)果里混入了調(diào)試用的假數(shù)據(jù)模型不知情就直接拿來用了。沒有回調(diào)日志這種問題只能靠猜。5.4 智能體評(píng)估沒有評(píng)估體系就沒有迭代依據(jù)傳統(tǒng)軟件上線前靠單元測(cè)試和集成測(cè)試Agent 應(yīng)用也需要一套“評(píng)估集”。沒有評(píng)估集的 Agent 項(xiàng)目有一個(gè)通病改了一個(gè) Prompt不知道整體效果是變好了還是變差了只能靠感覺。框架提供了 Evaluator 模塊可以批量跑評(píng)估用例并且支持自定義評(píng)估指標(biāo)。我目前實(shí)踐的評(píng)估集分三層工具調(diào)用正確率給定一組用戶問題檢查模型是否選擇了正確的工具、傳參是否正確。答案完整性對(duì)每個(gè)測(cè)試用例預(yù)設(shè)“必須覆蓋的要點(diǎn)”跑完后檢查回答是否覆蓋。格式合規(guī)性要求輸出必須符合 JSON schema 或特定模板跑完后做 schema 校驗(yàn)。這套評(píng)估集上線后我對(duì) Prompt 的每次調(diào)整都有了量化反饋。有一次我覺得新 Prompt 的“人設(shè)更好了”結(jié)果評(píng)估數(shù)據(jù)顯示工具誤調(diào)率從 3% 漲到 11%果斷回滾。沒有評(píng)估就跑生產(chǎn)本質(zhì)上是在裸奔。6. 實(shí)測(cè)踩坑記錄常見問題的排查與解法6.1 上下文爆炸長(zhǎng)對(duì)話跑著跑著就“失憶”了這是所有 Agent 項(xiàng)目都會(huì)遇到的問題?，F(xiàn)象是會(huì)話持續(xù)幾十輪后智能體開始忘記早期用戶提供的關(guān)鍵信息比如用戶第一輪說了“我預(yù)算 5000 元以內(nèi)”后面推薦的產(chǎn)品全是超預(yù)算的。排查思路先看框架的上下文管理配置確認(rèn) max_tokens 和裁剪策略是否合理。如果用的是純內(nèi)存上下文長(zhǎng)會(huì)話天然受限。我的解法是兩層策略第一對(duì)關(guān)鍵用戶信息做持久化記憶保存比如用戶的預(yù)算、偏好這類信息在會(huì)話中通過工具調(diào)用寫入外部存儲(chǔ)不依賴模型從歷史上下文里“回憶”第二設(shè)置合理的上下文上限超過上限時(shí)把早期不重要的對(duì)話歷史裁掉而不是一刀切全部保留。6.2 工具死循環(huán)模型在一個(gè)工具上反復(fù)調(diào)用不退出這個(gè)坑我在壓測(cè)時(shí)踩過。模型拿到一個(gè)工具返回結(jié)果后認(rèn)為結(jié)果不夠“精確”于是反復(fù)調(diào)用同一個(gè)工具每次傳入相似的參數(shù)一直循環(huán)停不下來?？蚣芾飳?duì)單次 Agent 運(yùn)行有最大工具調(diào)用輪次限制建議一上來就設(shè)置好agent Agent( ..., max_tool_calls_per_run10, # 單次回答最多調(diào)用 10 次工具 ) # 超過限制后框架會(huì)終止循環(huán)并返回當(dāng)前已生成的內(nèi)容設(shè)置這個(gè)限制的意義不僅是防死循環(huán)還有一個(gè)隱藏價(jià)值逼著你在設(shè)計(jì)工具時(shí)把工具做強(qiáng)。如果模型老是要通過多次調(diào)用來湊出一個(gè)答案經(jīng)常是因?yàn)閱蝹€(gè)工具的返回信息不完整需要通過合并多次調(diào)用來補(bǔ)全。與其加循環(huán)次數(shù)不如優(yōu)化工具返回讓一次調(diào)用就把模型需要的完整信息給全。6.3 沙箱代碼執(zhí)行的安全邊界代碼執(zhí)行工具方便但它是最容易出安全問題的點(diǎn)。我見過有的團(tuán)隊(duì)把代碼執(zhí)行工具默認(rèn)打開結(jié)果用戶輸入“幫我刪除當(dāng)前目錄所有文件”這種指令智能體真的生成并執(zhí)行了刪除命令。雖然沙箱會(huì)隔離一部分風(fēng)險(xiǎn)但絕不能把它當(dāng)成絕對(duì)保險(xiǎn)箱。我的建議是分層設(shè)防第一層代碼執(zhí)行工具默認(rèn)關(guān)閉只有在明確需要計(jì)算的場(chǎng)景才掛載第二層如果必須開放要在工具層做命令白名單和文件路徑安全檢查第三層部署上用獨(dú)立容器跑代碼執(zhí)行服務(wù)與主服務(wù)做網(wǎng)絡(luò)隔離。這三個(gè)層級(jí)都做了才算“可以用”。6.4 并發(fā)下的狀態(tài)串?dāng)_Session 隔離沒做好的代價(jià)多用戶并發(fā)訪問的時(shí)候如果 Session 管理沒做好最典型的故障是“用戶 A 問了自己的問題模型回答里卻出現(xiàn)了用戶 B 的訂單信息”。這是嚴(yán)重的事故級(jí)問題。根因是 Agent 實(shí)例復(fù)用時(shí)沒有把 Session 狀態(tà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)試小技巧把“模型視角”打出來最后一個(gè)很實(shí)用的技巧排查問題時(shí)把每次發(fā)送給模型的完整上下文系統(tǒng)指令、歷史消息、工具結(jié)果原樣 dump 出來看?？蚣艿娜罩灸K支持設(shè)置 debug 級(jí)別開啟后每個(gè)請(qǐng)求發(fā)出的完整 payload 都會(huì)輸出。這個(gè)技巧幫你糾正一種常見錯(cuò)覺你以為是“模型變笨了”實(shí)際上往往是你發(fā)給模型的上下文已經(jīng)是一團(tuán)亂麻了。比如某個(gè)工具返回了一個(gè)超長(zhǎng)的 JSON占了上下文一大半模型自然就會(huì)被帶偏。把模型視角打出來看一眼很多“玄學(xué) bug”當(dāng)場(chǎng)就能解釋清楚。我現(xiàn)在做 Agent 項(xiàng)目工具箱里最常用的是三件套可復(fù)現(xiàn)的 Session、全量回調(diào)日志、debug 級(jí)別的上下文 dump。這三樣搭起來90% 的問題都能在十分鐘內(nèi)定位到具體環(huán)節(jié)。剩下 10% 是模型本身的行為波動(dòng)那就要靠評(píng)估集來持續(xù)跟蹤了。