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