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