如果你在項目里接觸過 Agent Framework大概率對RunAsync這個入口不陌生。它是 Agent 從接收消息到產(chǎn)出回復(fù)的“一次執(zhí)行周期”也是理解 Agent 生命周期最重要的方法之一。這系列第二篇我用一個差旅助手作為例子完整拆解一次RunAsync到底是怎么跑完的消息進來之后去了哪、模型怎么決策、工具怎么被調(diào)用、什么時候停止、結(jié)果怎么返回。適合剛看完 Agent Framework 基礎(chǔ)概念、正準(zhǔn)備上手寫真實 Agent 的開發(fā)者也適合想搞清楚“框架到底幫我做了什么”的讀者。先說結(jié)論RunAsync并不是簡單地把用戶消息丟給大模型然后等回復(fù)它內(nèi)部包含上下文恢復(fù)、指令組裝、模型調(diào)用、工具執(zhí)行、終止判斷、狀態(tài)持久化等多個階段。只有把這些階段拆開看明白你才能在遇到“Agent 不聽話”“工具反復(fù)調(diào)用”“上下文越聊越亂”這類問題時快速定位到底哪一環(huán)出了問題。1. 從 RunAsync 的入口開始一次調(diào)用的全貌1.1 RunAsync 是什么RunAsync 本質(zhì)上是 Agent Framework 對外暴露的異步執(zhí)行入口。你調(diào)用它傳入用戶的輸入消息框架負責(zé)把這條消息變成一組模型調(diào)用和工具執(zhí)行序列最后把結(jié)果返回給你。它之所以叫“Async”是因為整個過程不阻塞調(diào)用線程內(nèi)部會通過異步迭代、流式回調(diào)等方式把模型輸出、工具執(zhí)行進度逐步推送出來。很多剛開始接觸 Agent Framework 的同學(xué)會把 RunAsync 理解成“發(fā)一條消息給 ChatGPT 然后拿到回復(fù)”。這個理解方向沒錯但漏掉了最關(guān)鍵的部分Agent 不是單次模型調(diào)用它是一個循環(huán)。RunAsync 內(nèi)部會反復(fù)執(zhí)行“模型生成 → 如果有工具調(diào)用就執(zhí)行工具 → 把工具結(jié)果放回上下文 → 再次調(diào)用模型”這個循環(huán)直到模型不再產(chǎn)生工具調(diào)用或者滿足預(yù)設(shè)的終止條件為止。所以一次 RunAsync 可能包含多次模型調(diào)用。例如差旅助手處理“周五從上海去北京出差幫我安排一下行程”時可能先調(diào)用航班查詢工具再調(diào)用天氣查詢工具最后還要調(diào)用預(yù)算計算工具每次工具調(diào)用后模型都要重新“想”一次。這些工具調(diào)用和模型思考都發(fā)生在同一次 RunAsync 里。這也就引出一個實際問題如果你把 RunAsync 當(dāng)成“單輪對話”那你對 Agent 的所有預(yù)期都會錯位。你需要把它當(dāng)成“一個任務(wù)執(zhí)行器”而不是“一個聊天接口”。1.2 差旅助手這個例子為什么合適選差旅助手做例子是因為它的工具調(diào)用路徑非常典型幾乎覆蓋了 RunAsync 的所有關(guān)鍵階段。我先把這個例子的業(yè)務(wù)設(shè)定說清楚差旅助手是一個 Agent它能幫用戶完成差旅安排相關(guān)的任務(wù)。它手里有四個工具查詢航班輸入出發(fā)地、目的地、日期返回航班列表航班號、時間、價格。查詢天氣輸入城市、日期返回天氣狀況和溫度。查詢酒店輸入城市、日期返回可預(yù)訂酒店及價格。計算總價輸入一組費用明細返回總額。用戶輸入“我周五從上海去北京出差幫我看看航班和天氣再幫我訂個酒店預(yù)算控制在3000以內(nèi)?！边@個需求看起來簡單但模型如果直接回答它并不知道真實的航班、天氣和酒店數(shù)據(jù)所以必須依次調(diào)用三個查詢工具最后還要通過計算總價來確認預(yù)算是否滿足。這個“多工具按順序調(diào)用”的過程恰好可以把 RunAsync 內(nèi)部的模型調(diào)用循環(huán)完整地暴露出來。為什么這個例子“合適”因為它不涉及多 Agent 協(xié)同、群聊這類高級特性聚焦在單個 Agent 的一次異步執(zhí)行上。這樣你能看清楚最本質(zhì)的執(zhí)行鏈路后面再去理解多 Agent 編排時會輕松很多。2. 一次 RunAsync 的完整生命周期拆解2.1 第一步消息從哪來上下文怎么恢復(fù)RunAsync 的第一步不是“調(diào)用模型”而是“準(zhǔn)備對話上下文”。Agent Framework 會從你創(chuàng)建的 Agent 實例和線程Thread中恢復(fù)歷史消息。你可以把 Agent 理解成一個“有系統(tǒng)指令、有工具能力的角色”把 Thread 理解成“這個角色和用戶之間的連續(xù)會話記錄”。差旅助手就是 Agent它和用戶之間所有歷史消息都放在 Thread 里。用戶新發(fā)來一句話RunAsync 會先把這句話追加到 Thread 的消息列表中然后把這個列表整體交給模型。這個過程有一個容易踩的坑很多人以為每次 RunAsync 都是獨立無狀態(tài)的其實框架默認會帶上歷史消息。如果用戶前面說“我從上海出發(fā)”后面說“幫我看看北京航班怎么樣”模型因為能看到歷史才知道出發(fā)地是上海。但代價是歷史越長每次調(diào)用的 token 消耗越大。所以一次 RunAsync 的開始階段實際做的是從 Thread 中讀取當(dāng)前會話的歷史消息。把用戶的新輸入封裝成 ChatMessage 追加到上下文中。把 Agent 的系統(tǒng)指令、工具定義和會話歷史一起組裝成模型請求。在這一步框架還會做一些輔助工作比如給消息生成 ID、記錄時間戳有的實現(xiàn)里還會對消息內(nèi)容做序列化。整個過程對開發(fā)者是透明的如果你自己調(diào)試過 API 請求體你會發(fā)現(xiàn)發(fā)出去的 messages 數(shù)組里歷史消息、工具定義、系統(tǒng)提示詞都在。2.2 第二步指令系統(tǒng)和工具聲明的組裝RunAsync 內(nèi)部會把你創(chuàng)建 Agent 時配置的 SystemPrompt、工具定義等全部組裝進請求里。這步看似簡單卻是決定 Agent“聽不聽話”的核心。差旅助手的系統(tǒng)指令大概長這樣“你是差旅助手負責(zé)幫用戶安排差旅行程。你必須使用工具獲取實時信息只有工具返回結(jié)果后才能回答用戶問題。預(yù)算不足時需要向用戶說明并給出備選方案。”工具聲明則更關(guān)鍵。在差旅助手例子里查詢航班、查詢天氣、查詢酒店、計算總價這4個工具會被轉(zhuǎn)成模型能理解的結(jié)構(gòu)化描述。Agent Framework 支持多種工具注冊方式比如直接引用函數(shù)、加載 OpenAPI 文檔、或者用預(yù)定義的 Tool 類型。這里我要特別強調(diào)一下工具聲明里的描述信息為什么重要。以“查詢航班”為例function_name: search_flights description: 查詢指定日期從出發(fā)地到目的地的航班列表 parameters: departure: 出發(fā)地城市名 destination: 目的地城市名 date: 日期格式為 YYYY-MM-DD描述寫得越準(zhǔn)確模型就越可能用正確參數(shù)調(diào)用工具。如果你只寫“航班查詢”模型可能搞不清日期格式甚至不知道該把出發(fā)地和目的地放在哪個字段。另一個值得注意的細節(jié)是Agent Framework 會把工具聲明和系統(tǒng)指令放在請求的不同位置但都會參與模型生成。你可以在調(diào)試日志里看到一條 RunAsync 請求實際上由三塊內(nèi)容構(gòu)成系統(tǒng)指令、工具定義、會話歷史。這三塊組裝完模型才會被調(diào)用。2.3 第三步模型調(diào)用與首輪決策組裝完請求之后RunAsync 進入真正的模型調(diào)用階段。這個階段沒什么神秘感就是把請求發(fā)到模型服務(wù)拿到第一輪輸出。但這里有一個關(guān)鍵點模型的第一輪輸出通常不是最終答案而是一個“決策結(jié)果”。決策結(jié)果有兩種可能模型直接生成最終回答文本這說明模型認為不需要調(diào)用任何工具就能回答問題。模型生成一個或多個 ToolCall 指令說明模型決定調(diào)用工具來獲取更多信息。差旅助手的場景里如果用戶問“你是什么”模型可能直接回答“我是差旅助手”不需要工具。但如果用戶問“周五上海到北京的航班”模型必須生成一個 ToolCall調(diào)用 search_flights 工具。在實際開發(fā)中你會在這一階段明顯感受到 Agent 與普通 Chat 接口的區(qū)別。普通 Chat 接口返回一條文本任務(wù)就結(jié)束了。而 Agent Framework 的 RunAsync 在拿到模型第一輪輸出后會先檢查里面有沒有 ToolCall 字段。有工具調(diào)用就進入工具執(zhí)行階段沒有工具調(diào)用才把文本輸出作為最終結(jié)果。首輪決策的質(zhì)量很大程度上取決于系統(tǒng)指令和工具描述是否清晰。差旅助手如果系統(tǒng)指令里沒說“工具返回結(jié)果后才能回答”模型很可能在拿到工具結(jié)果之前就憑記憶編造一個航班信息導(dǎo)致虛構(gòu)答案出現(xiàn)。2.4 第四步工具調(diào)用循環(huán)工具調(diào)用循環(huán)是 RunAsync 最核心的機制也是它和普通 API 調(diào)用最本質(zhì)的區(qū)別?？蚣軝z測到模型返回了 ToolCall 之后會做三件事根據(jù) ToolCall 里的工具名找到對應(yīng)實現(xiàn)。解析出參數(shù)執(zhí)行工具函數(shù)。把工具執(zhí)行結(jié)果作為一條“工具消息”追加回會話上下文。然后框架會拿著包含工具結(jié)果的完整上下文再次調(diào)用模型。模型看到工具結(jié)果后可能再發(fā)起新的 ToolCall也可能就此生成最終回答。這個過程會反復(fù)循環(huán)直到模型不再發(fā)起新的工具調(diào)用。差旅助手的典型調(diào)用序列可能是這樣的用戶周五上海到北京查下航班和天氣 模型調(diào)用 search_flights(departure上海, destination北京, date2025-01-10) 框架執(zhí)行 search_flights返回航班列表 模型調(diào)用 search_weather(city北京, date2025-01-10) 框架執(zhí)行 search_weather返回天氣結(jié)果 模型調(diào)用 search_hotels(city北京, date2025-01-10) 框架執(zhí)行 search_hotels返回酒店列表 模型根據(jù)以上工具結(jié)果生成最終回答整個序列里模型被調(diào)用了4次工具被執(zhí)行了3次但對外部來說用戶只發(fā)起了一次 RunAsync。這就是 Agent 和普通 Chat 接口體驗上的最大差別。這里有一個常見的疑問為什么框架不一次性把所有工具結(jié)果都交給模型原因是模型并不知道你的工具具體會返回什么它只能根據(jù)用戶需求“逐步探索”。這種逐步探索的機制也帶來了一個副作用就是執(zhí)行時間變長、token 消耗變多。后面我會專門聊怎么限制這個循環(huán)。3. 核心細節(jié)流式輸出、終止條件與狀態(tài)管理3.1 為什么要有終止條件前面說了 RunAsync 內(nèi)部是一個“模型調(diào)用 → 工具執(zhí)行 → 再調(diào)用模型”的循環(huán)。如果沒有終止條件模型可能永遠在調(diào)用工具永遠不生成最終答案。這種問題在實際項目中很常見比如模型反復(fù)查詢同一個航班或者查完一個城市又去查另一個城市始終不收斂。Agent Framework 提供了多種終止條件最常見的有三種最大迭代次數(shù)限制工具調(diào)用循環(huán)最多執(zhí)行多少輪超過就強制停止。模型不再產(chǎn)生 ToolCall模型只返回文本不再要求調(diào)用工具。自定義終止條件開發(fā)者自己寫邏輯比如判斷工具結(jié)果是否滿足用戶需求然后主動中斷循環(huán)。在差旅助手這個例子里最大迭代次數(shù)是非常有必要的。因為用戶需求可能很模糊模型可能反復(fù)調(diào)用工具去“確認”各種信息。我見過一次調(diào)試中模型連續(xù)調(diào)了7次工具就為了確認某個城市的酒店價格最后還是給了個模棱兩可的回答。加了最大迭代次數(shù)之后即使模型不收斂框架也會超時退出把已經(jīng)收集到的信息整合成回復(fù)返回給用戶。關(guān)于終止條件我看過不少實現(xiàn)很多人的做法是把“最多執(zhí)行 N 輪”寫死在代碼里但更推薦的做法是把終止條件同時寫進系統(tǒng)指令。比如差旅助手的系統(tǒng)指令里加上一句“如果一次查詢就能獲得足夠信息不要重復(fù)查詢同一個工具”能有效減少無效工具調(diào)用。3.2 流式回調(diào)與進度事件很多 Agent Framework 的 RunAsync 都有流式版本它和非流式的區(qū)別在于非流式會等所有循環(huán)結(jié)束返回一個完整結(jié)果流式會在執(zhí)行過程中持續(xù)拋出事件比如模型每生成一個 token、每個工具開始執(zhí)行、每個工具執(zhí)行完畢。流式機制對差旅助手這種場景特別有用。你想一下用戶等一個“查航班 查天氣 查酒店 算預(yù)算”的完整流程可能要等幾十秒。如果界面一直沒反應(yīng)用戶會以為程序掛了。用流式回調(diào)前端可以實時顯示“正在查詢航班”“航班數(shù)據(jù)已返回”“正在查詢天氣”這樣的進度狀態(tài)。這里的實操建議是區(qū)分模型增量事件和工具生命周期事件。模型增量是 tokens 的局部輸出用來渲染打字機效果工具生命周期是框架層事件用來驅(qū)動 UI 上的狀態(tài)流轉(zhuǎn)。如果混在一起會出現(xiàn) UI 上一會兒顯示“正在打字”一會兒顯示“正在調(diào)用工具”觀感很混亂。另外要注意流式事件里的數(shù)據(jù)往往不是完整 JSON而是分片到達的。你要在回調(diào)里自己維護緩沖區(qū)和事件順序。Agent Framework 通常會對事件做序列化標(biāo)記但你在業(yè)務(wù)代碼里最好也用一個遞增計數(shù)器記錄事件到達順序防止極端情況下亂序處理。3.3 狀態(tài)保存RunAsync 之間的線程延續(xù)一次 RunAsync 結(jié)束之后會話并沒有馬上消失。Agent Framework 會把這一輪產(chǎn)生的所有消息包括用戶消息、工具調(diào)用、工具結(jié)果、最終回答寫回到 Thread 中。下一次用戶再發(fā)消息新的 RunAsync 會基于這些歷史繼續(xù)。這個機制讓 Agent 有了“記憶”但也帶來了兩個問題。第一個問題歷史消息無限制增長。差旅助手如果被一個用戶連續(xù)用了一個月Thread 里的歷史消息可能有幾千條。每次 RunAsync 都要把這幾千條發(fā)給模型token 成本會越來越高響應(yīng)速度會越來越慢。解決辦法是在合適的時機做消息摘要或截斷把早期的原始消息壓縮成一段摘要文字再與最近的完整消息一起送入模型。第二個問題并發(fā)執(zhí)行導(dǎo)致上下文錯亂。如果一個 Thread 同時被兩個 RunAsync 執(zhí)行兩邊都在往同一個消息列表里追加內(nèi)容最后 Thread 狀態(tài)會變得不可預(yù)測。好的做法是一個 Thread 同一時間只允許一個 RunAsync 執(zhí)行或者為每個執(zhí)行周期創(chuàng)建獨立的快照上下文。在差旅助手這個例子中我建議每個“行程計劃”單獨開一個 Thread不要把所有用戶的差旅需求都塞進同一個會話里。這樣 RunAsync 之間的狀態(tài)保持會清晰很多也方便后續(xù)對單次行程做回溯和分析。4. 實操用差旅助手復(fù)現(xiàn)一次 RunAsync4.1 最小可運行示例代碼下面我用一段簡化了的 .NET 風(fēng)格偽代碼展示差旅助手的 RunAsync 全流程。真實項目里你還需要按具體版本的 API 調(diào)整但核心邏輯是一致的。// 1. 創(chuàng)建 Agent var agent new ChatAgent.Builder() .WithName(TravelAssistant) .WithInstructions( 你是差旅助手。必須使用工具獲取實時數(shù)據(jù)工具返回結(jié)果后才可回答用戶。 預(yù)算不足時應(yīng)說明原因并給出現(xiàn)有方案。 ) .WithTool(search_flights_tool) .WithTool(search_weather_tool) .WithTool(search_hotels_tool) .WithTool(calculate_cost_tool) .Build(); // 2. 創(chuàng)建線程會話上下文 var thread new AgentThread(); // 3. 用戶發(fā)送消息觸發(fā) RunAsync var userMessage new ChatMessage( role: user, content: 周五上海到北京出差查下航班、天氣和酒店預(yù)算3000以內(nèi) ); await foreach (var update in agent.RunAsync( message: userMessage, thread: thread, cancellationToken: token)) { // 流式事件處理 switch (update.Type) { case UpdateType.StreamingDelta: RenderToken(update.Content); break; case UpdateType.ToolCall: ShowToolStatus($正在調(diào)用工具{update.ToolName}); break; case UpdateType.ToolResult: ShowToolStatus($工具返回{update.ToolName}); break; case UpdateType.Complete: ShowFinalResponse(update.Content); break; } }這段代碼里有幾個關(guān)鍵點。第一Agent 構(gòu)建時集中聲明了“角色”和“工具”后面 RunAsync 時會自動組裝進模型請求不需要每次手動傳。第二RunAsync 返回的是一個異步事件流你用await foreach來消費。每個事件代表執(zhí)行鏈路中的一個階段模型生成片段、工具開始、工具返回、整個流程完成。第三Thread 對象通過參數(shù)傳入RunAsync 內(nèi)部會修改它的狀態(tài)。如果 Thread 是空的就是開啟新會話如果 Thread 已經(jīng)有歷史消息RunAsync 會先恢復(fù)歷史再追加新消息。4.2 手工推演一次調(diào)用光看代碼不夠直觀我用手工推演的方式帶你走一遍完整流程。這里假設(shè)框架的最大迭代次數(shù)設(shè)置為 6 次。步驟事件上下文變化1用戶消息進入 RunAsync上下文新增用戶消息周五上海到北京出差查航班、天氣、酒店預(yù)算3000以內(nèi)2模型第一次生成輸出 ToolCallsearch_flights(departure上海, destination北京, date2025-01-10)3框架執(zhí)行 search_flights上下文新增工具結(jié)果航班列表MU5101、CA1858等4模型第二次生成輸出 ToolCallsearch_weather(city北京, date2025-01-10)5框架執(zhí)行 search_weather上下文新增工具結(jié)果北京晴-3℃到5℃6模型第三次生成輸出 ToolCallsearch_hotels(city北京, date2025-01-10)7框架執(zhí)行 search_hotels上下文新增工具結(jié)果酒店列表漢庭、如家、全季8模型第四次生成輸出 ToolCallcalculate_cost(flightMU5101價格880, hotel全季價格520*2晚)9框架執(zhí)行 calculate_cost上下文新增工具結(jié)果總價 1920 元10模型第五次生成不再輸出 ToolCall輸出最終回答11RunAsync 結(jié)束最終回答寫入 Thread整個調(diào)用鏈結(jié)束推演完這 11 步你可以發(fā)現(xiàn)幾個規(guī)律。一次 RunAsync 內(nèi)部模型被調(diào)用了 5 次工具被調(diào)用了 4 次。這說明了為什么 Agent 類應(yīng)用比普通的問答接口慢慢不是網(wǎng)絡(luò)延遲而是多輪模型調(diào)用和工具執(zhí)行累積出的事件開銷。第 8、9 步值得單獨說一句。模型把兩個價格加起來的操作本身完全可以用人腦心算但 Agent 仍然選擇了調(diào)用工具因為系統(tǒng)指令要求“工具返回結(jié)果后才能回答”而且調(diào)用工具可以避免算術(shù)錯誤。這其實是模型面對“精確性要求”時的一種合理選擇。推演中隱藏了一個容易被忽略的問題如果某次模型調(diào)用輸出的 ToolCall 里有一個工具名不存在框架會拋異常還是忽略答案取決于具體實現(xiàn)但我強烈建議你在工具執(zhí)行階段做一層 try-catch并在系統(tǒng)指令里告訴模型“如果工具調(diào)用失敗請向用戶說明”。差旅助手如果在查詢航班時上游接口掛了正確行為是告訴用戶“航班查詢暫時不可用”而不是僵死在那里。4.3 工具注冊時容易被忽略的參數(shù)映射工具注冊是 RunAsync 鏈路里很多人第一次踩坑的地方。工具函數(shù)的參數(shù)名、類型、描述要和模型生成的 ToolCall 參數(shù)嚴格對應(yīng)。差旅助手的 search_flights 工具如果你把參數(shù)寫成parameters: from_city: 出發(fā)地 to_city: 目的地而你在函數(shù)實現(xiàn)里用的是departure和destination那模型生成 ToolCall 時可能會直接寫 from_city 和 to_city。如果你的框架沒有做參數(shù)映射函數(shù)調(diào)用就會因為缺少參數(shù)而失敗。我建議你在注冊工具時做一個嚴格的參數(shù) schema 校驗并加上默認值和容錯邏輯。比如日期字段允許傳“周五”這種相對表達時框架需要先把相對表達轉(zhuǎn)成具體日期再傳給工具函數(shù)。這一步轉(zhuǎn)換邏輯通常放在工具內(nèi)部做不要讓模型替你做。另外工具返回值最好統(tǒng)一成結(jié)構(gòu)化 JSON不要返回“一切正?！边@種自然語言。因為模型需要從工具結(jié)果中提取信息來生成最終回答結(jié)構(gòu)化 JSON 對它來說更友好也能減少幻覺。差旅助手的航班查詢返回{ flights: [ {flight_no: MU5101, departure: 上海虹橋, arrival: 北京首都, departure_time: 08:00, arrival_time: 10:15, price: 880} ] }這種結(jié)構(gòu)模型只需簡單提取就能回答用戶出錯率會低很多。5. 常見問題與排查實錄5.1 模型拿到工具結(jié)果后不收斂這是 RunAsync 實踐中最常見的問題模型調(diào)用工具之后拿著工具結(jié)果又發(fā)起一個新的 ToolCall反復(fù)多次也不給最終答案。在差旅助手場景里典型表現(xiàn)是查完航班之后又查一遍航班或者查完航班去查天氣查完天氣又跑回來查酒店始終不組織最終回答。我排查這類問題時一般分三步。第一步確認系統(tǒng)指令里是否有明確的“收尾”指令。只寫“幫助用戶”是不夠的要寫清楚“當(dāng)所需信息收集完成后直接給出完整回答不要繼續(xù)調(diào)用工具”。第二步限制最大迭代次數(shù)。把運行上限設(shè)成實際需要工具數(shù)量的兩倍左右差旅助手設(shè) 6 次足夠。不要設(shè)成 100 次那不是給真實用戶用的配置。第三步在工具結(jié)果里附上“這條結(jié)果的用途提示”。例如酒店查詢工具返回時可以加一行“若用戶預(yù)算允許可直接推薦本列表第一個酒店”引導(dǎo)模型盡早收尾。從我的實測經(jīng)驗看80% 的不收斂問題都能通過系統(tǒng)指令和 max_iteration 解決剩下 20% 是模型本身在復(fù)雜多目標(biāo)場景下的規(guī)劃能力不足需要拆成多個子任務(wù)分別執(zhí)行。5.2 工具異常導(dǎo)致整輪 RunAsync 失敗工具不是永遠可靠的。差旅助手的天氣服務(wù)可能超時航班接口可能限流酒店庫存可能已滿。默認情況下一次工具異常可能直接導(dǎo)致整個 RunAsync 失敗用戶只看到一句“系統(tǒng)錯誤”這體驗非常糟糕。解決思路是在工具執(zhí)行層統(tǒng)一做故障隔離。核心做法有兩層。第一層是工具內(nèi)部兜底。每個工具都返回一個固定結(jié)構(gòu)的數(shù)據(jù)即使查詢失敗也返回{error: 上游服務(wù)超時, fallback: []}而不是拋異常。這樣模型至少能知道“天氣查不到”然后決定是繼續(xù)嘗試還是告知用戶。第二層是框架層面降級。在工具執(zhí)行階段捕獲異常把錯誤消息轉(zhuǎn)成一條工具結(jié)果消息標(biāo)記為失敗。你可以在系統(tǒng)指令里補充工具返回 error 字段時說明該信息不可用請明確告知用戶并基于現(xiàn)有信息給出建議。差旅助手如果查不到周五的航班但能查到周六的航班模型就應(yīng)該回答“周五航班信息暫時不可用周六有航班是否調(diào)整行程”而不是卡在那里反復(fù)重試。5.3 并發(fā)問題多個用戶同時觸發(fā) RunAsync當(dāng)一個 Agent 被多個用戶同時使用時你會遇到一類很隱蔽的問題用戶 A 的 RunAsync 和用戶 B 的 RunAsync 都往同一個 Thread 里追加消息最終模型看到的上下文是兩段對話混在一起的。為什么會發(fā)生因為 Thread 是共享狀態(tài)。如果你把一個 Thread 傳給兩個并發(fā) RunAsync框架內(nèi)部如果沒有鎖或者快照機制兩邊都會認為自己拿到了最新上下文然后各自寫入最后相互覆蓋。我在差旅助手里的做法是每個用戶維護獨立 Thread并且一個 Thread 同一時間只允許一個 RunAsync 執(zhí)行?？蚣軐用婵梢约右粋€簡單的信號量或分布式鎖Thread ID 作為鎖的 key。用戶如果連續(xù)快速發(fā)送兩條消息后一條消息應(yīng)該排隊等待而不是并發(fā)執(zhí)行。還有一種更徹底的做法不在 Thread 對象上做狀態(tài)管理而是把每次 RunAsync 的輸入輸出顯式保存到外部存儲RunAsync 開始時重建上下文結(jié)束時持久化上下文。這樣并發(fā)控制就變成了存儲層的版本管理問題比在內(nèi)存線程里做鎖要健壯得多。5.4 排查實錄一次 RunAsync 突然多出一次“幽靈工具調(diào)用”有一次我在調(diào)試差旅助手時發(fā)現(xiàn)用戶只問了“北京天氣怎么樣”模型卻在第一輪調(diào)用了 search_hotels。我一度以為是模型發(fā)瘋了后來打開調(diào)試日志才發(fā)現(xiàn)Thread 里殘留了上一輪對話中的“酒店”討論模型在做上下文關(guān)聯(lián)認為這次問天氣前應(yīng)該先確認酒店還在不在。這正是 RunAsync 恢復(fù) Thread 歷史消息特性帶來的副作用。歷史消息不僅給模型提供記憶也會影響模型對當(dāng)前任務(wù)的判斷。排查這類“幽靈工具調(diào)用”時第一步是檢查 Thread 里的歷史消息第二步是看系統(tǒng)指令是否足夠清晰地把當(dāng)前任務(wù)和歷史任務(wù)隔離開。我后來在差旅助手的代碼里加了一條處理規(guī)則每次用戶發(fā)起新行程安排時先在一個新的 Thread 中運行不讓上一次行程的上下文干擾當(dāng)前任務(wù)。這樣雖然少了“連續(xù)性”的便利但換來了更高的可控性。實際產(chǎn)品里你需要在這兩者之間做取舍。6. 避坑總結(jié)與個人體會寫到這里我對 RunAsync 的完整鏈路已經(jīng)做了比較細致的拆解。最后再分享幾個我實際使用 Agent Framework 時踩過坑之后攢下的經(jīng)驗。第一個經(jīng)驗調(diào)試 RunAsync 一定要開完整日志尤其是模型原始請求和響應(yīng)。你只看最終結(jié)果是看不懂 Agent 行為的因為最終結(jié)果可能經(jīng)過了 5 輪內(nèi)部循環(huán)。只有看到每一輪模型返回了什么 ToolCall、工具結(jié)果是什么、下一輪模型如何引用這些結(jié)果才能定位問題。Agent Framework 通常提供回調(diào)或中間件機制來打印這些信息別省這一步。第二個經(jīng)驗系統(tǒng)指令不是寫在開頭就完事了。差旅助手這種多工具場景最好在系統(tǒng)指令末尾再加一段“輸出規(guī)范”明確告訴模型最終回答必須列出航班時間、價格、天氣情況和酒店價格并對預(yù)算給出結(jié)論。否則模型很容易漏掉某項信息你要花很長時間在提示詞上調(diào)優(yōu)。第三個經(jīng)驗也是我認為最重要的一點不要把 RunAsync 想成一個黑盒。當(dāng)你把 Agent 當(dāng)成黑盒遇到問題就只能“換提示詞”或者“換模型”。但當(dāng)你把 RunAsync 拆成上下文恢復(fù)、指令組裝、模型決策、工具循環(huán)、終止判斷這幾個階段你會發(fā)現(xiàn)自己能定位到具體環(huán)節(jié)然后針對性地修改。差旅助手這個例子做完之后我對 Agent 的理解改變了很多。以前我覺得 Agent 就是“API 提示詞”但其實 RunAsync 的整個執(zhí)行框架才是靈魂。模型負責(zé)“思考”框架負責(zé)“循環(huán)”工具負責(zé)“行動”三者缺一不可。后續(xù)如果你開始研究多 Agent 編排你會發(fā)現(xiàn)多個 Agent 之間的 RunAsync 協(xié)作會更加復(fù)雜但底層仍然離不開今天拆解的這些基礎(chǔ)環(huán)節(jié)。最后再給一個能立刻用得上的小技巧在你自己的 Agent 代碼里試著給每個 RunAsync 加一個 traceId把整個循環(huán)中的模型調(diào)用、工具調(diào)用都記錄到同一個 traceId 下。排查問題的時候你只需要按 traceId 搜索就能看到一次 RunAsync 的完整生命周期比翻一堆零散日志高效得多。這也是我推薦所有 Agent 應(yīng)用都盡早做好的可觀測性建設(shè)。