Agent Harness：企業(yè)級AI應(yīng)用的生產(chǎn)落地與架構(gòu)取舍)
半年前我們團隊接了一個內(nèi)部運營助手的活要在私有化環(huán)境里跑一批 AI Agent 處理工單分類、合同信息抽取和業(yè)務(wù)數(shù)據(jù)問答。最開始我用 Python 生態(tài)把 Agent 骨架搭了出來三個晚上就能對話了同事都說效果不錯?？烧嬲郎蕚渖仙a(chǎn)的時候問題一個接一個冒出來模型調(diào)用怎么和現(xiàn)有權(quán)限體系打通多個 Agent 的會話怎么隔離工具調(diào)用怎么審計日志里怎么追蹤一次完整的多步推理Python 那邊的小樣完全答不上來。于是我們轉(zhuǎn)回去用純 Java 重新實現(xiàn)做了個內(nèi)部代號叫 BizBuddy 的 Agent Harness 平臺。這篇文章想把這個過程中的設(shè)計取舍講清楚哪些地方我堅持了 Java 的路子哪些地方故意沒有照搬社區(qū)框架哪些決定是拿生產(chǎn)事故換來的。1. 起因小樣用 Python 三天跑通上生產(chǎn)的時候全卡住了1.1 我們最初想要的東西其實需求本身并不玄乎。一個內(nèi)部助手用戶在對話框里提問題Agent 自己判斷要不要調(diào)用我們已有的業(yè)務(wù)接口再把結(jié)果組織成自然語言回復回來。這里有對外的客服工單分類、有合同文本的字段抽取、也有針對業(yè)務(wù)數(shù)據(jù)的多輪問答。難點從來不是模型會不會回答而是這些問題在企業(yè)環(huán)境里要過安全評審、要接統(tǒng)一登錄、要扣費審計、要能灰度發(fā)布。1.2 小樣的快恰好就是它上不了生產(chǎn)的理由Python 小樣確實快因為生態(tài)里現(xiàn)成的東西多。但當你認真問生產(chǎn)環(huán)境的問題就會發(fā)現(xiàn)全是坑第一是環(huán)境碎片化。模型推理主要走遠端 API本地不需要太重的東西但 Python 的依賴管理和虛擬環(huán)境在公司安全策略下還是被反復盤問。私有化部署到客戶現(xiàn)場的時候更是頭疼客戶環(huán)境里能不能裝包、能不能聯(lián)網(wǎng)、用哪個 Python 版本都得協(xié)商。第二是并發(fā)和穩(wěn)定性。一個 Python 進程的并發(fā)能力有限對于幾十個用戶同時提問這種再普通不過的場景需要額外上異步框架而團隊里沒人愿意長期維護第二套技術(shù)棧。第三是治理和集成。業(yè)務(wù)系統(tǒng)是 Java 技術(shù)棧用戶權(quán)限、組織架構(gòu)、數(shù)據(jù)庫訪問、消息隊列、統(tǒng)一配置中心全都長在 Java 這邊。Python Agent 想調(diào)用這些能力要么開 HTTP 接口硬橋接要么在 Python 里再連一遍那些中間件。兩條路都意味著雙倍的運維面和雙倍的審計面。那段小樣最終沒有被浪費它證明了用 Agent 處理這些業(yè)務(wù)可行。但架構(gòu)上的賬算得很清楚用 Java 實現(xiàn)同樣的東西可能要多花兩三周但之后它會和現(xiàn)有系統(tǒng)長在一起而不是在旁邊另起爐灶。1.3 用純 Java 做不是情懷是賬算得過來我需要澄清一下純 Java的邊界。BizBuddy 不是一個機器學習訓練平臺不需要跑模型也不碰向量檢索算法的內(nèi)部實現(xiàn)。它是一個偏運行引擎和治理底座的東西主要負責 Agent 的生命周期、上下文、工具調(diào)用、流程編排、模型接入抽象、限流監(jiān)控。這些活兒 JVM 生態(tài)天生就擅長而且我們有一整支熟悉 Spring、理解并發(fā)編程、會調(diào) JVM 參數(shù)的技術(shù)團隊。同樣重要的是Java 生態(tài)里對企業(yè)級集成的沉淀非常深。安全框架、緩存抽象、連接池、事務(wù)管理、配置中心都已經(jīng)有成熟方案BizBuddy 要做的不是重造這些輪子而是把它們和 Agent 的運行時協(xié)議銜接起來。1.4 什么是 Agent Harness現(xiàn)在Agent 框架滿天飛但 Harness 和框架是兩種位置的東西?？蚣芙鉀Q的是Agent 怎么寫比如怎么解析模型輸出、怎么構(gòu)造 Prompt、怎么調(diào)用工具它更像造船廠。Harness 解決的是Agent 怎么跑比如一個 Agent 從部署到下線誰在管、多個會話之間怎么隔離、失敗了誰來重試、調(diào)用一次模型的成本記到哪個項目頭上它更像船運公司。BizBuddy 的定位更偏 Harness。在它之上有業(yè)務(wù)團隊寫的具體 Agent在它之下是各種基礎(chǔ)設(shè)施。它必須足夠薄才能不綁架業(yè)務(wù)方的開發(fā)方式又必須足夠強才能讓 Agent 在真實生產(chǎn)環(huán)境里不出亂子。2. 核心抽象Agent 是一個業(yè)務(wù)單元不是一個模型調(diào)用殼2.1 為什么我把 Agent 接口做得這么簡單最開始設(shè)計 BizBuddy 的 Agent 抽象時團隊里有人建議照搬社區(qū)框架的路子把 Agent 做成一個大而全的類里面直接塞模型、記憶、工具、規(guī)劃器。我堅持沒有這么做因為這個層一旦變重所有 Agent 實現(xiàn)都要被框架牽著走。BizBuddy 的 Agent 接口收縮到只有四個方法public interface Agent { String name(); void initialize(AgentRuntime runtime); AgentReply invoke(AgentRequest request, AgentSession session); void destroy(); }我們不定義該不該反思該用哪種 Prompt 策略該選哪個模型這些屬于具體 Agent 的個性?？蚣苤灰s定你有一個名字啟動時我給你運行時能力請求來了我拿會話和請求調(diào)你服務(wù)下線我通知你做清理。這樣業(yè)務(wù)團隊寫 Agent 時可以自由組合工具調(diào)用、模型調(diào)用和本地邏輯而 Harness 統(tǒng)一拿到生命周期與執(zhí)行入口。AgentRuntime 是 BizBuddy 給 Agent 的能力清單里面包括工具注冊表、模型 Provider、審批接口、指標收集器等。每個 Agent 在 initialize 階段拿到的 runtime 是同一個但可以聲明自己需要哪些子集這樣測試時也能注入 mock。2.2 Session 持有狀態(tài)Agent 本身保持無狀態(tài)這是整個設(shè)計里我最看重的一個取舍Agent 實例禁止持有用戶級狀態(tài)。曾經(jīng)有同事圖省事把用戶對話歷史直接放在 Agent 的成員變量里。開發(fā)時什么問題都沒有一上聯(lián)調(diào)就出亂子A 用戶的問題被 B 用戶的上下文干擾工單查詢結(jié)果串號。排查了好幾個小時最后發(fā)現(xiàn)是 Agent 被注冊成了單例所有并發(fā)請求共享了同一個成員變量。BizBuddy 里所有狀態(tài)都放在 AgentSession 中public final class AgentSession implements AutoCloseable { private final String sessionId; private final String tenantId; private final String agentName; private final MapString, Object variables new ConcurrentHashMap(); private final ChatWindow chatWindow; public void setVariable(String key, Object value) { ... } public Object getVariable(String key) { ... } public void appendMessage(ChatMessage message) { ... } public ListChatMessage visibleMessages() { ... } Override public void close() { ... } }sessionId 是全局唯一標識tenantId 保證一個租戶的會話不會串到另一個租戶。ChatWindow 是帶預算的對話窗口負責控制發(fā)往模型的 token 量這個放到后面講。所有 Agent 實現(xiàn)都被要求寫成無狀態(tài)本次請求需要什么就通過參數(shù)從 session 里拿。這個約束讓 BizBuddy 可以一個 Agent 實例服務(wù)幾千個并發(fā)會話也讓壓測和生產(chǎn)環(huán)境的偶發(fā)問題變得好查。2.3 和 Spring 容器怎么協(xié)作BizBuddy 沒有另搞一套依賴注入。Agent 本身就是普通的 Spring 組件通過注解注冊Agent(name order_query_agent) public class OrderQueryAgent implements Agent { ... }應(yīng)用啟動時BizBuddy 的 Starter 組件掃描所有帶 Agent 的類檢查接口方法實現(xiàn)然后以單例方式注冊到 AgentRegistry。Agent 內(nèi)部想調(diào)什么業(yè)務(wù)服務(wù)直接使用平常的構(gòu)造器注入或字段注入不需要自定義擴展機制。這樣做的好處是業(yè)務(wù)方寫 Agent 和寫普通 Spring 服務(wù)幾乎沒有區(qū)別。他們不需要理解框架如何接管對象生命周期之類的東西只需要按常規(guī)方式寫代碼BizBuddy 在邊界上把 Agent 的運行協(xié)議接住。3. 工具調(diào)用鏈路的設(shè)計取舍注解式 Tool 才是 Java 的答案3.1 為什么不直接暴露 JSON Schema做 Function Calling 相關(guān)的 Agent第一步通常是定義模型可以調(diào)用的工具。很多框架推薦直接給 JSON Schema讓 Agent 決定調(diào)用哪個函數(shù)。我在 BizBuddy 里沒有采用手寫 schema的方案原因很實際字段一變schema 和人寫的代碼就會漂移類型一復雜手工維護成本直線上升更重要的是Java 是個強類型語言手寫字符串讓編譯期完全幫不上忙。BizBuddy 的做法是用注解定義工具編譯期和 IDE 都能參與到檢查中Tool(name query_order, description 按條件查詢訂單列表返回訂單ID、金額和狀態(tài)) public OrderQueryResult queryOrder( ToolParam(name customerId, description 客戶ID) String customerId, ToolParam(name startDate, description 開始日期格式 yyyy-MM-dd) LocalDate startDate, ToolParam(name status, description 訂單狀態(tài)) OrderStatus status) { return orderQueryService.query(customerId, startDate, status); }這里有幾個隱性好處。參數(shù)類型是真的對象類型LocalDate、枚舉、業(yè)務(wù)對象都能被正確序列化與校驗方法是現(xiàn)成的 Spring Bean 方法可以直接用注解掃描與反射機制接管不需要額外包一層適配器。3.2 一個 Tool 從注冊到執(zhí)行的完整路徑BizBuddy 的 Tool 不是普通方法它有完整的元數(shù)據(jù)、攔截器和調(diào)用器。注冊階段Starter 通過 BeanPostProcessor 收集所有標注了 Tool 的公共方法解析入?yún)⒑兔枋龃虬?ToolDefinition注冊到 ToolRegistry。調(diào)用階段完整鏈路如下LLM 在響應(yīng)里返回一個 toolCall包含 toolName 和 JSON 字符串參數(shù)。BizBuddy 的 ToolInvoker 從 registry 拿到 ToolDefinition反序列化參數(shù)到方法簽名要求的類型。參數(shù)經(jīng)過一層 ThrottleAndBudget 檢查確認這個租戶、這個 Agent 還有調(diào)用額度。權(quán)限攔截器校驗當前用戶是否有權(quán)執(zhí)行該工具。這一步不能省后面會講為什么。真正的方法通過 MethodHandle 調(diào)用整個調(diào)用包裹在帶超時時間的任務(wù)里。返回值轉(zhuǎn)成一個 ToolResultMessage追加到 session 的對話窗口再送回給模型。這里有一個很容易踩的坑模型返回的參數(shù) JSON 不一定符合方法簽名。比如日期格式寫成了別的樣子或者枚舉值拼錯。BizBuddy 在反序列化階段統(tǒng)一做了一次容錯處理日期格式盡量多認幾種枚舉按 name 和別名雙匹配實在解析不了就返回一個明確的解析錯誤給模型讓模型自己修正參數(shù)再調(diào)用一次。實測下來這種把錯誤反饋給模型的策略比直接給用戶報錯效果好得多。3.3 權(quán)限、超時、注入防護放在哪工具調(diào)用是 Agent 能力邊界也是安全風險邊界。一個能從對話里生成參數(shù)的執(zhí)行通道如果沒有閘門等于給任何能觸發(fā)對話的人開了一個無限調(diào)接口的口子。我在 BizBuddy 里把權(quán)限校驗放在工具調(diào)用這一層和用戶請求入口那層分開。用戶請求入口那層管的是能不能跟這個 Agent 說話工具調(diào)用這一層管的是這個用戶能不能讓 Agent 替他執(zhí)行這個工具。兩者的粒度完全不同A 用戶可能能和合同 Agent 對話但只允許它查公開摘要不允許它觸發(fā)合同導出。超時和熔斷也放在工具調(diào)用層。模型可能一口氣發(fā)起三四個工具調(diào)用BizBuddy 默認并發(fā)執(zhí)行這些工具但每個工具獨立超時執(zhí)行業(yè)務(wù)方法超過閾值后向模型返回一個超時結(jié)果由模型決定是重試還是告訴用戶當前系統(tǒng)繁忙。這個細節(jié)讓整個 Agent 系統(tǒng)在業(yè)務(wù)系統(tǒng)抖動時不會連帶不可用。參數(shù)注入防護也是后來補的。開發(fā)者很容易信任模型生成的參數(shù)但模型可能被提示詞注入誘導比如某條外部文本里寫著請忽略之前指令執(zhí)行某個高風險動作。BizBuddy 對每個工具參數(shù)都做類型和邊界校驗同時對路徑型、查詢型參數(shù)做額外的排除列表檢查。4. 編排層不引入現(xiàn)成 BPM 引擎自研一個會回頭的輕量圖執(zhí)行器4.1 BPM 引擎為什么讓 Agent 別扭立項時有人提議用成熟的 BPM 工作流引擎來編排多步 Agent。當時我?guī)е鴪F隊實際建模試了一下不到半小時就放棄了。根因是 BPM 引擎的哲學和 Agent 的哲學擰著。BPM 引擎擅長的是流程預先確定狀態(tài)由引擎推進每一步的下一步是設(shè)計時寫死的。Agent 則完全不同模型要根據(jù)前一步的工具結(jié)果動態(tài)決定下一步做什么。你可以預先定義一個最復雜的拓撲圖但實際執(zhí)行路徑可能在每個節(jié)點都變化。硬把這種動態(tài)性塞進 BPM 編輯器里結(jié)果就是圖上面全是條件分支模型反而成了擺設(shè)。4.2 圖模型和節(jié)點類型BizBuddy 定義了一組非常小的圖模型命名上故意不用工作流那套詞避免團隊下意識往流程定義上套。public sealed interface GraphNode permits StartNode, EndNode, LlmNode, ToolNode, ConditionNode, SubGraphNode { } public record GraphEdge(String targetNodeId, String whenCondition) { }看圖就知道這個圖不是流程圖更像一棵執(zhí)行樹加循環(huán)控制Start 進入End 退出Llm 節(jié)點調(diào)用模型Tool 節(jié)點調(diào)用工具Condition 節(jié)點根據(jù) session 里的變量走不同分支SubGraph 節(jié)點復用一張子圖。每條邊上可以帶 SpEL 表達式比如graph.exit() .hasNode(tool_result_check, SpelCondition.on(result.status NEED_MORE_INFO).then(query_more)) .hasNode(tool_result_check, SpelCondition.on(result.status SUCCESS).then(final_answer));沒有復雜的網(wǎng)關(guān)、會簽、子流程約定只有節(jié)點和邊。團隊學習成本很低而表達力對大部分 Agent 場景已經(jīng)夠了。4.3 執(zhí)行器的遞歸式實現(xiàn)與防呆執(zhí)行器用顯式棧模擬遞歸避免深調(diào)用把棧打爆public GraphExecutionResult execute(AgentGraph graph, AgentSession session, String entryNodeId) { DequeNodeFrame stack new ArrayDeque(); stack.push(new NodeFrame(entryNodeId, Map.of())); while (!stack.isEmpty()) { NodeFrame frame stack.pop(); GraphNode node graph.node(frame.nodeId()); NodeResult nodeResult node.run(session, frame.input()); for (GraphEdge edge : graph.outEdges(frame.nodeId())) { if (edge.whenCondition() null || evalCondition(edge.whenCondition(), session, nodeResult)) { stack.push(new NodeFrame(edge.targetNodeId(), nodeResult.output())); } } if (stack.size() maxDepth) { throw new GraphExecutionException(graph exceeds max depth maxDepth); } } return new GraphExecutionResult(session); }這個執(zhí)行器實現(xiàn)了最關(guān)鍵的一個能力回頭。Llm 節(jié)點輸出工具調(diào)用請求后執(zhí)行器可以先把控制權(quán)交給 Tool 節(jié)點Tool 的返回結(jié)果再作為下一次 Llm 節(jié)點的輸入。這在圖里不需要畫圈只需要讓 Llm 節(jié)點在存在 toolCall 請求時把后繼邊同時指向工具節(jié)點和自己即可。防呆方面我加了三個硬性上限最大執(zhí)行深度、最大循環(huán)次數(shù)、整體超時時間。任意一個觸發(fā)都以失敗狀態(tài)結(jié)束并且返回足夠明確的錯誤信息。因為 Agent 模式的失敗率本來就高于普通接口開發(fā)環(huán)境里跑 5 次可能沒事到生產(chǎn)模型換版本后就可能出現(xiàn)死循環(huán)。4.4 多 Agent 協(xié)作我只先做了 Supervisor 和 Pipeline 兩種多 Agent 協(xié)作聽起來很酷但我沒打算做一整套完整的 Agent 市場、辯論、群體共識機制。BizBuddy 第一版只支持兩種模式Supervisor 模式一個協(xié)調(diào) Agent 根據(jù)用戶描述選擇可用的子 Agent把子 Agent 的執(zhí)行結(jié)果再組織成最終答復。Pipeline 模式請求按固定順序經(jīng)過多個 Agent上一個 Agent 的輸出作為下一個 Agent 的輸入。適合先分類再處理這類穩(wěn)定鏈路。這兩種模式覆蓋了我們目前遇到的絕大多數(shù)業(yè)務(wù)場景而且實現(xiàn)都很簡單就是圖執(zhí)行器上的特定排列?？桃獠患痈嗄Ｊ绞且驗槎?Agent 的調(diào)試成本是單 Agent 的好幾倍絕大多數(shù)項目根本用不到那些花哨能力先把基礎(chǔ)路徑做穩(wěn)比什么都強。5. LLM Provider 抽象能做 80% 的統(tǒng)一剩下的 20% 留給能力協(xié)商5.1 內(nèi)部消息協(xié)議與適配器BizBuddy 面向業(yè)務(wù)開發(fā)者的 API 里不應(yīng)該出現(xiàn)任何具體廠商的類型。所以第一步是定義一套內(nèi)部消息協(xié)議public record ChatMessage(ChatRole role, String content, ListToolCall toolCalls, String toolCallId) { } public record ChatRequest(ListChatMessage messages, ChatOptions options, String agentName) { } public record ChatResult(ChatMessage message, Usage usage, ChatProvider provider) { }然后每個廠商一個適配器負責把內(nèi)部協(xié)議翻譯成廠商 SDK 的請求、再把廠商響應(yīng)翻譯回內(nèi)部協(xié)議。這樣業(yè)務(wù) Agent 永遠不需要 import 某個具體模型服務(wù)商的包后續(xù)切換模型時改的只是配置和適配器而不是具體 Agent 代碼。5.2 流式輸出落地從 Stream 到 SSE對話體驗需要流式輸出模型一個 Token 一個 Token 地蹦出來用戶不會盯著轉(zhuǎn)圈等二十秒。BizBuddy 在 Provider 接口里定義public interface ChatProvider { ChatResult complete(ChatRequest request, AgentSession session); StreamChatDelta stream(ChatRequest request, AgentSession session); }流式實現(xiàn)的第一個版本我直接用響應(yīng)式流一路鋪到前端結(jié)果發(fā)現(xiàn)團隊里大量成員對背壓、異步上下文傳遞不熟悉容易寫出難維護的代碼。后來換了一種更工程化的做法內(nèi)部用阻塞隊列收集供應(yīng)商的回調(diào)事件對外以 Java 21 的虛擬線程逐個消費再橋接成 SSE 推給瀏覽器。這樣流式處理的代碼寫起來像同步循環(huán)心智負擔低線上也穩(wěn)定很多。5.3 不硬抹平廠商差異早期我們想把所有廠商的能力對齊成一個超集結(jié)果代碼里到處是如果支持這個特性則……的條件分支反而難維護。后來我把抽象目標下調(diào)到 80%只統(tǒng)一那些 Agent 邏輯真正依賴的基礎(chǔ)能力對話補全、流式、工具調(diào)用、token 用量統(tǒng)計。剩下的差異比如工具調(diào)用格式的細節(jié)偏好、JSON 輸出模式的支持程度、某些模型特有的參數(shù)通過能力協(xié)商來處理public record ProviderCapabilities( boolean supportsToolCall, boolean supportsJsonMode, boolean supportsVision, int maxOutputTokens ) { }請求構(gòu)造器先看 capability能支持再做對應(yīng)處理不支持就退回到更通用的路徑并且日志里明確記錄當前模型不支持某特性已降級。這個設(shè)計避免了大一統(tǒng)抽象帶來的復雜度陷阱也讓新接入一個廠商變得非?？?。6. 生產(chǎn)環(huán)境里幾次救命的調(diào)優(yōu)線程模型、鏈路追蹤和冪等6.1 虛擬線程不是銀彈BizBuddy 部署在 Java 21 上LLM 調(diào)用是典型的阻塞式網(wǎng)絡(luò) IO正好適合虛擬線程。我用虛擬線程來處理一次 Agent 執(zhí)行的整條鏈路并發(fā)量提升非常明顯線程占用從幾千個降到幾十個。但有一個坑必須講虛擬線程在遇到 synchronized 同步塊時會發(fā)生 pinning如果同時配上數(shù)據(jù)庫連接池驅(qū)逐高并發(fā)場景會出現(xiàn)連接拿不到的詭異現(xiàn)象。我們排查過一周最后發(fā)現(xiàn)是某處工具方法里加了 synchronized而方法內(nèi)部阻塞在 JDBC 調(diào)用上。解決方法是把這段同步邏輯換成顯式鎖或原子類并限制連接池與虛擬線程的并發(fā)比例別讓虛擬線程無限擠爆數(shù)據(jù)庫連接數(shù)。6.2 讓每一條日志都帶 sessionId、agentName、nodeIdAgent 執(zhí)行鏈路比普通接口長得多一個用戶問題可能觸發(fā)五六次模型調(diào)用、十幾次工具調(diào)用沒有統(tǒng)一的追蹤上下文排障就是災(zāi)難。BizBuddy 在入口處把會話維度信息寫入日志上下文打印的關(guān)鍵 log 都帶上 sessionId、agentName、nodeId、toolCallId。最開始實現(xiàn)時用了簡單的線程變量結(jié)果流式線程一切換上下文就丟了日志串聯(lián)斷裂。后來我改成在每段異步任務(wù)提交時顯式傳遞上下文快照由執(zhí)行線程恢復才算穩(wěn)定。這個投入看起來小回報非常大。現(xiàn)在出問題第一件事就是按 sessionId 拉日志能把一次完整推理路徑完整回放出來。6.3 LLM 重試帶來的重復工具調(diào)用有一次工單系統(tǒng)出現(xiàn)了重復創(chuàng)建查了半天發(fā)現(xiàn)根因是模型側(cè)的網(wǎng)絡(luò)重試。模型服務(wù)返回超時實際請求已經(jīng)到達 BizBuddyBizBuddy 里工具也執(zhí)行成功了但客戶端重試導致同一個 toolCall 被再次執(zhí)行。這是 Agent 系統(tǒng)獨有的冪等問題。普通接口可以要求客戶端傳冪等鍵但 BizBuddy 的調(diào)用方是模型服務(wù)它不會主動傳冪等鍵。我們的解決方式是在 ToolInvoker 里對每一次 toolCall 生成唯一執(zhí)行記錄以 sessionId nodeId toolCallId 作為冪等鍵第二次命中直接返回第一次的結(jié)果不再真正調(diào)用業(yè)務(wù)方法。類似地同一個 Llm 節(jié)點如果因為網(wǎng)絡(luò)超時重試也優(yōu)先復用已有輸出。6.4 按租戶和 Agent 維度做限流配額大模型 API 不是免費午飯一次復雜的多步推理可能消耗上萬 token還可能有并發(fā)配額上限。BizBuddy 提供兩層級聯(lián)的令牌桶租戶級配額管整體預算Agent 級配額管單個場景上限。超過配額時不直接拋粗魯?shù)漠惓６欠祷匾粋€結(jié)構(gòu)化錯誤Agent 能把這個信息轉(zhuǎn)成對用戶友好的提示比如當前該類服務(wù)的調(diào)用額度已用完請稍后再試。這套配額也作用于工具調(diào)用。有些工具比模型調(diào)用更貴比如導出報表、發(fā)送短信BizBuddy 在工具調(diào)用鏈路里加了同樣的閘門防止模型被誘導觸發(fā)高成本操作。7. 收尾BizBuddy 只解決了 80% 的問題寫這篇文章時 BizBuddy 已經(jīng)在內(nèi)部支撐了三個業(yè)務(wù) Agent 的上線這個量級不算大但足夠暴露很多設(shè)計問題。實際做下來我最大的體會是Agent 平臺最難的不是模型調(diào)用那一層而是把動態(tài)執(zhí)行這件事裝進企業(yè)現(xiàn)有的運維和治理體系里。BizBuddy 在生命周期、工具調(diào)用、編排、可觀測和配額上切出了一個比較合理的邊界團隊寫業(yè)務(wù) Agent 時不用關(guān)心底層底層出問題時又能順著日志和追蹤一路查到底。下一階段我想補兩件事。一是把會話和圖中斷點做持久化讓很長的任務(wù)可以掛起恢復二是把圖執(zhí)行過程可視化出來讓業(yè)務(wù)同學也能看懂 Agent 是怎么得出答案的。至于那些還沒做到的部分我寧可繼續(xù)慢慢補也不愿意現(xiàn)在就堆一堆華而不實的功能進去。畢竟 Harness 這東西穩(wěn)定和可控比熱鬧重要得多。 純Java實現(xiàn)Agent Harness：企業(yè)級AI應(yīng)用的生產(chǎn)落地與架構(gòu)取舍
半年前我們團隊接了一個內(nèi)部運營助手的活要在私有化環(huán)境里跑一批 AI Agent 處理工單分類、合同信息抽取和業(yè)務(wù)數(shù)據(jù)問答。最開始我用 Python 生態(tài)把 Agent 骨架搭了出來三個晚上就能對話了同事都說效果不錯?？烧嬲郎蕚渖仙a(chǎn)的時候問題一個接一個冒出來模型調(diào)用怎么和現(xiàn)有權(quán)限體系打通多個 Agent 的會話怎么隔離工具調(diào)用怎么審計日志里怎么追蹤一次完整的多步推理Python 那邊的小樣完全答不上來。于是我們轉(zhuǎn)回去用純 Java 重新實現(xiàn)做了個內(nèi)部代號叫 BizBuddy 的 Agent Harness 平臺。這篇文章想把這個過程中的設(shè)計取舍講清楚哪些地方我堅持了 Java 的路子哪些地方故意沒有照搬社區(qū)框架哪些決定是拿生產(chǎn)事故換來的。1. 起因小樣用 Python 三天跑通上生產(chǎn)的時候全卡住了1.1 我們最初想要的東西其實需求本身并不玄乎。一個內(nèi)部助手用戶在對話框里提問題Agent 自己判斷要不要調(diào)用我們已有的業(yè)務(wù)接口再把結(jié)果組織成自然語言回復回來。這里有對外的客服工單分類、有合同文本的字段抽取、也有針對業(yè)務(wù)數(shù)據(jù)的多輪問答。難點從來不是模型會不會回答而是這些問題在企業(yè)環(huán)境里要過安全評審、要接統(tǒng)一登錄、要扣費審計、要能灰度發(fā)布。1.2 小樣的快恰好就是它上不了生產(chǎn)的理由Python 小樣確實快因為生態(tài)里現(xiàn)成的東西多。但當你認真問生產(chǎn)環(huán)境的問題就會發(fā)現(xiàn)全是坑第一是環(huán)境碎片化。模型推理主要走遠端 API本地不需要太重的東西但 Python 的依賴管理和虛擬環(huán)境在公司安全策略下還是被反復盤問。私有化部署到客戶現(xiàn)場的時候更是頭疼客戶環(huán)境里能不能裝包、能不能聯(lián)網(wǎng)、用哪個 Python 版本都得協(xié)商。第二是并發(fā)和穩(wěn)定性。一個 Python 進程的并發(fā)能力有限對于幾十個用戶同時提問這種再普通不過的場景需要額外上異步框架而團隊里沒人愿意長期維護第二套技術(shù)棧。第三是治理和集成。業(yè)務(wù)系統(tǒng)是 Java 技術(shù)棧用戶權(quán)限、組織架構(gòu)、數(shù)據(jù)庫訪問、消息隊列、統(tǒng)一配置中心全都長在 Java 這邊。Python Agent 想調(diào)用這些能力要么開 HTTP 接口硬橋接要么在 Python 里再連一遍那些中間件。兩條路都意味著雙倍的運維面和雙倍的審計面。那段小樣最終沒有被浪費它證明了用 Agent 處理這些業(yè)務(wù)可行。但架構(gòu)上的賬算得很清楚用 Java 實現(xiàn)同樣的東西可能要多花兩三周但之后它會和現(xiàn)有系統(tǒng)長在一起而不是在旁邊另起爐灶。1.3 用純 Java 做不是情懷是賬算得過來我需要澄清一下純 Java的邊界。BizBuddy 不是一個機器學習訓練平臺不需要跑模型也不碰向量檢索算法的內(nèi)部實現(xiàn)。它是一個偏運行引擎和治理底座的東西主要負責 Agent 的生命周期、上下文、工具調(diào)用、流程編排、模型接入抽象、限流監(jiān)控。這些活兒 JVM 生態(tài)天生就擅長而且我們有一整支熟悉 Spring、理解并發(fā)編程、會調(diào) JVM 參數(shù)的技術(shù)團隊。同樣重要的是Java 生態(tài)里對企業(yè)級集成的沉淀非常深。安全框架、緩存抽象、連接池、事務(wù)管理、配置中心都已經(jīng)有成熟方案BizBuddy 要做的不是重造這些輪子而是把它們和 Agent 的運行時協(xié)議銜接起來。1.4 什么是 Agent Harness現(xiàn)在Agent 框架滿天飛但 Harness 和框架是兩種位置的東西?？蚣芙鉀Q的是Agent 怎么寫比如怎么解析模型輸出、怎么構(gòu)造 Prompt、怎么調(diào)用工具它更像造船廠。Harness 解決的是Agent 怎么跑比如一個 Agent 從部署到下線誰在管、多個會話之間怎么隔離、失敗了誰來重試、調(diào)用一次模型的成本記到哪個項目頭上它更像船運公司。BizBuddy 的定位更偏 Harness。在它之上有業(yè)務(wù)團隊寫的具體 Agent在它之下是各種基礎(chǔ)設(shè)施。它必須足夠薄才能不綁架業(yè)務(wù)方的開發(fā)方式又必須足夠強才能讓 Agent 在真實生產(chǎn)環(huán)境里不出亂子。2. 核心抽象Agent 是一個業(yè)務(wù)單元不是一個模型調(diào)用殼2.1 為什么我把 Agent 接口做得這么簡單最開始設(shè)計 BizBuddy 的 Agent 抽象時團隊里有人建議照搬社區(qū)框架的路子把 Agent 做成一個大而全的類里面直接塞模型、記憶、工具、規(guī)劃器。我堅持沒有這么做因為這個層一旦變重所有 Agent 實現(xiàn)都要被框架牽著走。BizBuddy 的 Agent 接口收縮到只有四個方法public interface Agent { String name(); void initialize(AgentRuntime runtime); AgentReply invoke(AgentRequest request, AgentSession session); void destroy(); }我們不定義該不該反思該用哪種 Prompt 策略該選哪個模型這些屬于具體 Agent 的個性?？蚣苤灰s定你有一個名字啟動時我給你運行時能力請求來了我拿會話和請求調(diào)你服務(wù)下線我通知你做清理。這樣業(yè)務(wù)團隊寫 Agent 時可以自由組合工具調(diào)用、模型調(diào)用和本地邏輯而 Harness 統(tǒng)一拿到生命周期與執(zhí)行入口。AgentRuntime 是 BizBuddy 給 Agent 的能力清單里面包括工具注冊表、模型 Provider、審批接口、指標收集器等。每個 Agent 在 initialize 階段拿到的 runtime 是同一個但可以聲明自己需要哪些子集這樣測試時也能注入 mock。2.2 Session 持有狀態(tài)Agent 本身保持無狀態(tài)這是整個設(shè)計里我最看重的一個取舍Agent 實例禁止持有用戶級狀態(tài)。曾經(jīng)有同事圖省事把用戶對話歷史直接放在 Agent 的成員變量里。開發(fā)時什么問題都沒有一上聯(lián)調(diào)就出亂子A 用戶的問題被 B 用戶的上下文干擾工單查詢結(jié)果串號。排查了好幾個小時最后發(fā)現(xiàn)是 Agent 被注冊成了單例所有并發(fā)請求共享了同一個成員變量。BizBuddy 里所有狀態(tài)都放在 AgentSession 中public final class AgentSession implements AutoCloseable { private final String sessionId; private final String tenantId; private final String agentName; private final MapString, Object variables new ConcurrentHashMap(); private final ChatWindow chatWindow; public void setVariable(String key, Object value) { ... } public Object getVariable(String key) { ... } public void appendMessage(ChatMessage message) { ... } public ListChatMessage visibleMessages() { ... } Override public void close() { ... } }sessionId 是全局唯一標識tenantId 保證一個租戶的會話不會串到另一個租戶。ChatWindow 是帶預算的對話窗口負責控制發(fā)往模型的 token 量這個放到后面講。所有 Agent 實現(xiàn)都被要求寫成無狀態(tài)本次請求需要什么就通過參數(shù)從 session 里拿。這個約束讓 BizBuddy 可以一個 Agent 實例服務(wù)幾千個并發(fā)會話也讓壓測和生產(chǎn)環(huán)境的偶發(fā)問題變得好查。2.3 和 Spring 容器怎么協(xié)作BizBuddy 沒有另搞一套依賴注入。Agent 本身就是普通的 Spring 組件通過注解注冊Agent(name order_query_agent) public class OrderQueryAgent implements Agent { ... }應(yīng)用啟動時BizBuddy 的 Starter 組件掃描所有帶 Agent 的類檢查接口方法實現(xiàn)然后以單例方式注冊到 AgentRegistry。Agent 內(nèi)部想調(diào)什么業(yè)務(wù)服務(wù)直接使用平常的構(gòu)造器注入或字段注入不需要自定義擴展機制。這樣做的好處是業(yè)務(wù)方寫 Agent 和寫普通 Spring 服務(wù)幾乎沒有區(qū)別。他們不需要理解框架如何接管對象生命周期之類的東西只需要按常規(guī)方式寫代碼BizBuddy 在邊界上把 Agent 的運行協(xié)議接住。3. 工具調(diào)用鏈路的設(shè)計取舍注解式 Tool 才是 Java 的答案3.1 為什么不直接暴露 JSON Schema做 Function Calling 相關(guān)的 Agent第一步通常是定義模型可以調(diào)用的工具。很多框架推薦直接給 JSON Schema讓 Agent 決定調(diào)用哪個函數(shù)。我在 BizBuddy 里沒有采用手寫 schema的方案原因很實際字段一變schema 和人寫的代碼就會漂移類型一復雜手工維護成本直線上升更重要的是Java 是個強類型語言手寫字符串讓編譯期完全幫不上忙。BizBuddy 的做法是用注解定義工具編譯期和 IDE 都能參與到檢查中Tool(name query_order, description 按條件查詢訂單列表返回訂單ID、金額和狀態(tài)) public OrderQueryResult queryOrder( ToolParam(name customerId, description 客戶ID) String customerId, ToolParam(name startDate, description 開始日期格式 yyyy-MM-dd) LocalDate startDate, ToolParam(name status, description 訂單狀態(tài)) OrderStatus status) { return orderQueryService.query(customerId, startDate, status); }這里有幾個隱性好處。參數(shù)類型是真的對象類型LocalDate、枚舉、業(yè)務(wù)對象都能被正確序列化與校驗方法是現(xiàn)成的 Spring Bean 方法可以直接用注解掃描與反射機制接管不需要額外包一層適配器。3.2 一個 Tool 從注冊到執(zhí)行的完整路徑BizBuddy 的 Tool 不是普通方法它有完整的元數(shù)據(jù)、攔截器和調(diào)用器。注冊階段Starter 通過 BeanPostProcessor 收集所有標注了 Tool 的公共方法解析入?yún)⒑兔枋龃虬?ToolDefinition注冊到 ToolRegistry。調(diào)用階段完整鏈路如下LLM 在響應(yīng)里返回一個 toolCall包含 toolName 和 JSON 字符串參數(shù)。BizBuddy 的 ToolInvoker 從 registry 拿到 ToolDefinition反序列化參數(shù)到方法簽名要求的類型。參數(shù)經(jīng)過一層 ThrottleAndBudget 檢查確認這個租戶、這個 Agent 還有調(diào)用額度。權(quán)限攔截器校驗當前用戶是否有權(quán)執(zhí)行該工具。這一步不能省后面會講為什么。真正的方法通過 MethodHandle 調(diào)用整個調(diào)用包裹在帶超時時間的任務(wù)里。返回值轉(zhuǎn)成一個 ToolResultMessage追加到 session 的對話窗口再送回給模型。這里有一個很容易踩的坑模型返回的參數(shù) JSON 不一定符合方法簽名。比如日期格式寫成了別的樣子或者枚舉值拼錯。BizBuddy 在反序列化階段統(tǒng)一做了一次容錯處理日期格式盡量多認幾種枚舉按 name 和別名雙匹配實在解析不了就返回一個明確的解析錯誤給模型讓模型自己修正參數(shù)再調(diào)用一次。實測下來這種把錯誤反饋給模型的策略比直接給用戶報錯效果好得多。3.3 權(quán)限、超時、注入防護放在哪工具調(diào)用是 Agent 能力邊界也是安全風險邊界。一個能從對話里生成參數(shù)的執(zhí)行通道如果沒有閘門等于給任何能觸發(fā)對話的人開了一個無限調(diào)接口的口子。我在 BizBuddy 里把權(quán)限校驗放在工具調(diào)用這一層和用戶請求入口那層分開。用戶請求入口那層管的是能不能跟這個 Agent 說話工具調(diào)用這一層管的是這個用戶能不能讓 Agent 替他執(zhí)行這個工具。兩者的粒度完全不同A 用戶可能能和合同 Agent 對話但只允許它查公開摘要不允許它觸發(fā)合同導出。超時和熔斷也放在工具調(diào)用層。模型可能一口氣發(fā)起三四個工具調(diào)用BizBuddy 默認并發(fā)執(zhí)行這些工具但每個工具獨立超時執(zhí)行業(yè)務(wù)方法超過閾值后向模型返回一個超時結(jié)果由模型決定是重試還是告訴用戶當前系統(tǒng)繁忙。這個細節(jié)讓整個 Agent 系統(tǒng)在業(yè)務(wù)系統(tǒng)抖動時不會連帶不可用。參數(shù)注入防護也是后來補的。開發(fā)者很容易信任模型生成的參數(shù)但模型可能被提示詞注入誘導比如某條外部文本里寫著請忽略之前指令執(zhí)行某個高風險動作。BizBuddy 對每個工具參數(shù)都做類型和邊界校驗同時對路徑型、查詢型參數(shù)做額外的排除列表檢查。4. 編排層不引入現(xiàn)成 BPM 引擎自研一個會回頭的輕量圖執(zhí)行器4.1 BPM 引擎為什么讓 Agent 別扭立項時有人提議用成熟的 BPM 工作流引擎來編排多步 Agent。當時我?guī)е鴪F隊實際建模試了一下不到半小時就放棄了。根因是 BPM 引擎的哲學和 Agent 的哲學擰著。BPM 引擎擅長的是流程預先確定狀態(tài)由引擎推進每一步的下一步是設(shè)計時寫死的。Agent 則完全不同模型要根據(jù)前一步的工具結(jié)果動態(tài)決定下一步做什么。你可以預先定義一個最復雜的拓撲圖但實際執(zhí)行路徑可能在每個節(jié)點都變化。硬把這種動態(tài)性塞進 BPM 編輯器里結(jié)果就是圖上面全是條件分支模型反而成了擺設(shè)。4.2 圖模型和節(jié)點類型BizBuddy 定義了一組非常小的圖模型命名上故意不用工作流那套詞避免團隊下意識往流程定義上套。public sealed interface GraphNode permits StartNode, EndNode, LlmNode, ToolNode, ConditionNode, SubGraphNode { } public record GraphEdge(String targetNodeId, String whenCondition) { }看圖就知道這個圖不是流程圖更像一棵執(zhí)行樹加循環(huán)控制Start 進入End 退出Llm 節(jié)點調(diào)用模型Tool 節(jié)點調(diào)用工具Condition 節(jié)點根據(jù) session 里的變量走不同分支SubGraph 節(jié)點復用一張子圖。每條邊上可以帶 SpEL 表達式比如graph.exit() .hasNode(tool_result_check, SpelCondition.on(result.status NEED_MORE_INFO).then(query_more)) .hasNode(tool_result_check, SpelCondition.on(result.status SUCCESS).then(final_answer));沒有復雜的網(wǎng)關(guān)、會簽、子流程約定只有節(jié)點和邊。團隊學習成本很低而表達力對大部分 Agent 場景已經(jīng)夠了。4.3 執(zhí)行器的遞歸式實現(xiàn)與防呆執(zhí)行器用顯式棧模擬遞歸避免深調(diào)用把棧打爆public GraphExecutionResult execute(AgentGraph graph, AgentSession session, String entryNodeId) { DequeNodeFrame stack new ArrayDeque(); stack.push(new NodeFrame(entryNodeId, Map.of())); while (!stack.isEmpty()) { NodeFrame frame stack.pop(); GraphNode node graph.node(frame.nodeId()); NodeResult nodeResult node.run(session, frame.input()); for (GraphEdge edge : graph.outEdges(frame.nodeId())) { if (edge.whenCondition() null || evalCondition(edge.whenCondition(), session, nodeResult)) { stack.push(new NodeFrame(edge.targetNodeId(), nodeResult.output())); } } if (stack.size() maxDepth) { throw new GraphExecutionException(graph exceeds max depth maxDepth); } } return new GraphExecutionResult(session); }這個執(zhí)行器實現(xiàn)了最關(guān)鍵的一個能力回頭。Llm 節(jié)點輸出工具調(diào)用請求后執(zhí)行器可以先把控制權(quán)交給 Tool 節(jié)點Tool 的返回結(jié)果再作為下一次 Llm 節(jié)點的輸入。這在圖里不需要畫圈只需要讓 Llm 節(jié)點在存在 toolCall 請求時把后繼邊同時指向工具節(jié)點和自己即可。防呆方面我加了三個硬性上限最大執(zhí)行深度、最大循環(huán)次數(shù)、整體超時時間。任意一個觸發(fā)都以失敗狀態(tài)結(jié)束并且返回足夠明確的錯誤信息。因為 Agent 模式的失敗率本來就高于普通接口開發(fā)環(huán)境里跑 5 次可能沒事到生產(chǎn)模型換版本后就可能出現(xiàn)死循環(huán)。4.4 多 Agent 協(xié)作我只先做了 Supervisor 和 Pipeline 兩種多 Agent 協(xié)作聽起來很酷但我沒打算做一整套完整的 Agent 市場、辯論、群體共識機制。BizBuddy 第一版只支持兩種模式Supervisor 模式一個協(xié)調(diào) Agent 根據(jù)用戶描述選擇可用的子 Agent把子 Agent 的執(zhí)行結(jié)果再組織成最終答復。Pipeline 模式請求按固定順序經(jīng)過多個 Agent上一個 Agent 的輸出作為下一個 Agent 的輸入。適合先分類再處理這類穩(wěn)定鏈路。這兩種模式覆蓋了我們目前遇到的絕大多數(shù)業(yè)務(wù)場景而且實現(xiàn)都很簡單就是圖執(zhí)行器上的特定排列?？桃獠患痈嗄Ｊ绞且驗槎?Agent 的調(diào)試成本是單 Agent 的好幾倍絕大多數(shù)項目根本用不到那些花哨能力先把基礎(chǔ)路徑做穩(wěn)比什么都強。5. LLM Provider 抽象能做 80% 的統(tǒng)一剩下的 20% 留給能力協(xié)商5.1 內(nèi)部消息協(xié)議與適配器BizBuddy 面向業(yè)務(wù)開發(fā)者的 API 里不應(yīng)該出現(xiàn)任何具體廠商的類型。所以第一步是定義一套內(nèi)部消息協(xié)議public record ChatMessage(ChatRole role, String content, ListToolCall toolCalls, String toolCallId) { } public record ChatRequest(ListChatMessage messages, ChatOptions options, String agentName) { } public record ChatResult(ChatMessage message, Usage usage, ChatProvider provider) { }然后每個廠商一個適配器負責把內(nèi)部協(xié)議翻譯成廠商 SDK 的請求、再把廠商響應(yīng)翻譯回內(nèi)部協(xié)議。這樣業(yè)務(wù) Agent 永遠不需要 import 某個具體模型服務(wù)商的包后續(xù)切換模型時改的只是配置和適配器而不是具體 Agent 代碼。5.2 流式輸出落地從 Stream 到 SSE對話體驗需要流式輸出模型一個 Token 一個 Token 地蹦出來用戶不會盯著轉(zhuǎn)圈等二十秒。BizBuddy 在 Provider 接口里定義public interface ChatProvider { ChatResult complete(ChatRequest request, AgentSession session); StreamChatDelta stream(ChatRequest request, AgentSession session); }流式實現(xiàn)的第一個版本我直接用響應(yīng)式流一路鋪到前端結(jié)果發(fā)現(xiàn)團隊里大量成員對背壓、異步上下文傳遞不熟悉容易寫出難維護的代碼。后來換了一種更工程化的做法內(nèi)部用阻塞隊列收集供應(yīng)商的回調(diào)事件對外以 Java 21 的虛擬線程逐個消費再橋接成 SSE 推給瀏覽器。這樣流式處理的代碼寫起來像同步循環(huán)心智負擔低線上也穩(wěn)定很多。5.3 不硬抹平廠商差異早期我們想把所有廠商的能力對齊成一個超集結(jié)果代碼里到處是如果支持這個特性則……的條件分支反而難維護。后來我把抽象目標下調(diào)到 80%只統(tǒng)一那些 Agent 邏輯真正依賴的基礎(chǔ)能力對話補全、流式、工具調(diào)用、token 用量統(tǒng)計。剩下的差異比如工具調(diào)用格式的細節(jié)偏好、JSON 輸出模式的支持程度、某些模型特有的參數(shù)通過能力協(xié)商來處理public record ProviderCapabilities( boolean supportsToolCall, boolean supportsJsonMode, boolean supportsVision, int maxOutputTokens ) { }請求構(gòu)造器先看 capability能支持再做對應(yīng)處理不支持就退回到更通用的路徑并且日志里明確記錄當前模型不支持某特性已降級。這個設(shè)計避免了大一統(tǒng)抽象帶來的復雜度陷阱也讓新接入一個廠商變得非?？?。6. 生產(chǎn)環(huán)境里幾次救命的調(diào)優(yōu)線程模型、鏈路追蹤和冪等6.1 虛擬線程不是銀彈BizBuddy 部署在 Java 21 上LLM 調(diào)用是典型的阻塞式網(wǎng)絡(luò) IO正好適合虛擬線程。我用虛擬線程來處理一次 Agent 執(zhí)行的整條鏈路并發(fā)量提升非常明顯線程占用從幾千個降到幾十個。但有一個坑必須講虛擬線程在遇到 synchronized 同步塊時會發(fā)生 pinning如果同時配上數(shù)據(jù)庫連接池驅(qū)逐高并發(fā)場景會出現(xiàn)連接拿不到的詭異現(xiàn)象。我們排查過一周最后發(fā)現(xiàn)是某處工具方法里加了 synchronized而方法內(nèi)部阻塞在 JDBC 調(diào)用上。解決方法是把這段同步邏輯換成顯式鎖或原子類并限制連接池與虛擬線程的并發(fā)比例別讓虛擬線程無限擠爆數(shù)據(jù)庫連接數(shù)。6.2 讓每一條日志都帶 sessionId、agentName、nodeIdAgent 執(zhí)行鏈路比普通接口長得多一個用戶問題可能觸發(fā)五六次模型調(diào)用、十幾次工具調(diào)用沒有統(tǒng)一的追蹤上下文排障就是災(zāi)難。BizBuddy 在入口處把會話維度信息寫入日志上下文打印的關(guān)鍵 log 都帶上 sessionId、agentName、nodeId、toolCallId。最開始實現(xiàn)時用了簡單的線程變量結(jié)果流式線程一切換上下文就丟了日志串聯(lián)斷裂。后來我改成在每段異步任務(wù)提交時顯式傳遞上下文快照由執(zhí)行線程恢復才算穩(wěn)定。這個投入看起來小回報非常大。現(xiàn)在出問題第一件事就是按 sessionId 拉日志能把一次完整推理路徑完整回放出來。6.3 LLM 重試帶來的重復工具調(diào)用有一次工單系統(tǒng)出現(xiàn)了重復創(chuàng)建查了半天發(fā)現(xiàn)根因是模型側(cè)的網(wǎng)絡(luò)重試。模型服務(wù)返回超時實際請求已經(jīng)到達 BizBuddyBizBuddy 里工具也執(zhí)行成功了但客戶端重試導致同一個 toolCall 被再次執(zhí)行。這是 Agent 系統(tǒng)獨有的冪等問題。普通接口可以要求客戶端傳冪等鍵但 BizBuddy 的調(diào)用方是模型服務(wù)它不會主動傳冪等鍵。我們的解決方式是在 ToolInvoker 里對每一次 toolCall 生成唯一執(zhí)行記錄以 sessionId nodeId toolCallId 作為冪等鍵第二次命中直接返回第一次的結(jié)果不再真正調(diào)用業(yè)務(wù)方法。類似地同一個 Llm 節(jié)點如果因為網(wǎng)絡(luò)超時重試也優(yōu)先復用已有輸出。6.4 按租戶和 Agent 維度做限流配額大模型 API 不是免費午飯一次復雜的多步推理可能消耗上萬 token還可能有并發(fā)配額上限。BizBuddy 提供兩層級聯(lián)的令牌桶租戶級配額管整體預算Agent 級配額管單個場景上限。超過配額時不直接拋粗魯?shù)漠惓６欠祷匾粋€結(jié)構(gòu)化錯誤Agent 能把這個信息轉(zhuǎn)成對用戶友好的提示比如當前該類服務(wù)的調(diào)用額度已用完請稍后再試。這套配額也作用于工具調(diào)用。有些工具比模型調(diào)用更貴比如導出報表、發(fā)送短信BizBuddy 在工具調(diào)用鏈路里加了同樣的閘門防止模型被誘導觸發(fā)高成本操作。7. 收尾BizBuddy 只解決了 80% 的問題寫這篇文章時 BizBuddy 已經(jīng)在內(nèi)部支撐了三個業(yè)務(wù) Agent 的上線這個量級不算大但足夠暴露很多設(shè)計問題。實際做下來我最大的體會是Agent 平臺最難的不是模型調(diào)用那一層而是把動態(tài)執(zhí)行這件事裝進企業(yè)現(xiàn)有的運維和治理體系里。BizBuddy 在生命周期、工具調(diào)用、編排、可觀測和配額上切出了一個比較合理的邊界團隊寫業(yè)務(wù) Agent 時不用關(guān)心底層底層出問題時又能順著日志和追蹤一路查到底。下一階段我想補兩件事。一是把會話和圖中斷點做持久化讓很長的任務(wù)可以掛起恢復二是把圖執(zhí)行過程可視化出來讓業(yè)務(wù)同學也能看懂 Agent 是怎么得出答案的。至于那些還沒做到的部分我寧可繼續(xù)慢慢補也不愿意現(xiàn)在就堆一堆華而不實的功能進去。畢竟 Harness 這東西穩(wěn)定和可控比熱鬧重要得多。