企業(yè)里一接大模型智能體最扎眼的矛盾就來了既要 Agent 快速見效又不能動已經穩(wěn)定跑了三年的業(yè)務主線?？涩F(xiàn)實常常是對話記錄、向量切片、任務流水一股腦塞進主庫模型一超時整條下單鏈路跟著抖。常規(guī)做法之所以不夠用在主服務里直接寫 LLM 調用、復用主庫表存會話、同步等待模型返回會讓依賴膨脹、事務邊界被打穿Agent 每迭代一次就得帶著整個系統(tǒng)重新發(fā)版。本文分享一套可直接落地的側掛式方案獨立 Agent 服務 獨立數(shù)據(jù)庫 主線零侵入的事件契約前端組件松耦合掛載、隨拆隨上。一、架構選型智能體側掛而不是嵌入主干先做一次選型對照再決定 Agent 到底落在哪一側維度嵌入主服務側掛獨立服務發(fā)版節(jié)奏隨業(yè)務系統(tǒng)全量發(fā)布獨立灰度、獨立回滾依賴引入主工程引入模型 SDK主線僅留一個出站接口故障半徑模型超時拖垮業(yè)務線程池Agent 掛掉后主線無感數(shù)據(jù)歸屬會話與業(yè)務表混放獨立庫獨立生命周期側掛定義Agent 作為旁路服務存在主線只認「事件進、結果回」兩條通道。主線保留只留一個輕量出站適配器代碼里不出現(xiàn)任何模型 SDK、提示詞與解析邏輯。判定標準把 Agent 目錄整個刪掉主線仍能正常下單收款才算真正零侵入。核心結論把智能體當外部協(xié)作方接入而不是當業(yè)務代碼的延伸。二、服務邊界網關與業(yè)務域各管一段拆分之前先把職責切干凈邊界模糊比跑得慢更致命業(yè)務服務只負責產生事實數(shù)據(jù)發(fā)出order.paid之類的領域事件完全不關心誰來消費。Agent 網關承接鑒權、會話路由、模型適配與限流對內統(tǒng)一暴露POST /agent/run。結果回流通過回調或事件寫回業(yè)務側主線只按任務號冪等落賬不做二次加工。事件進 → 網關編排 → 模型執(zhí)行 → 結果回流 → 主線落賬核心結論邊界越硬后期換模型、換向量庫的代價就越低。三、數(shù)據(jù)隔離會話與向量落獨立庫智能體的數(shù)據(jù)有自己的生命周期先列清單再決定建幾個庫數(shù)據(jù)類別歸屬庫保留策略會話與消息agent_db90 天滾動清理向量與切片agent_vector隨文檔版本重建任務流水agent_db按審計要求歸檔業(yè)務事實數(shù)據(jù)原業(yè)務庫不復制、不冗余不跨庫事務主線與 Agent 之間只追求最終一致靠taskId做對賬與補償。只讀共享確需業(yè)務上下文時用只讀賬號同步一份快照表嚴禁 Agent 反向寫主庫。核心結論數(shù)據(jù)一旦同庫所謂零侵入就只剩一句口號。四、零侵入對接事件驅動與異步回調解耦主線要的從來不是能力而是穩(wěn)定接入方式直接決定侵入程度同步直調模型動輒十幾秒長期占用業(yè)務線程池一次抖動會被放大成全局故障。事件異步主線發(fā)完事件即可返回Agent 慢、掛、重試都不影響主流程的響應時間?；卣{冪等回寫結果必須帶taskId上游重復投遞時按狀態(tài)機去重避免重復落賬。領域事件 → 消息隊列 → Agent 消費 → 執(zhí)行任務 → 回調主線 → 冪等落庫核心結論主線代碼里只出現(xiàn)「發(fā)」和「收」兩個動作這就是零侵入的可驗證標準。五、接口契約三類端點撐起前后端約定前后端能并行開發(fā)靠的是一張穩(wěn)定的契約表端點方法用途關鍵參數(shù)/agent/sessionPOST創(chuàng)建會話bizType、bizId/agent/runPOST觸發(fā)任務taskId、prompt、stream/agent/task/{id}GET查詢進度status、resultUrl契約穩(wěn)定字段只增不改后端升級模型版本不會波及任何前端代碼。狀態(tài)可查任務永不阻塞請求前端拿到taskId后按節(jié)奏輪詢。下面這段是 Vue3 Vite 前端里觸發(fā)任務并輪詢狀態(tài)的最小可用封裝// 觸發(fā)智能體任務并輪詢其狀態(tài)適配 Vue3 瀏覽器環(huán)境asyncfunctionrunAgent(bizType,bizId){constresawaitfetch(/agent/run,{method:POST,headers:{Content-Type:application/json},body:JSON.stringify({bizType,bizId,prompt:生成本周經營簡報})});const{taskId}awaitres.json();returnpollTask(taskId,2000);}發(fā)任務拿 taskId → 定時輪詢 → 狀態(tài)變 SUCCESS 取 resultUrl核心結論契約一旦凍結前后端就能各自獨立發(fā)版。六、前端掛載側邊欄組件松耦合接入組件接入要做到拔掉就恢復原樣成本只有一行代碼獨立目錄Agent 組件單獨放components/agent-panel主頁面只保留一行引用。props 傳上下文業(yè)務方只傳bizType與bizId組件內部自己建會話、自己拉狀態(tài)。事件回拋需要主線刷新時用emit(done)組件里不 import 任何業(yè)務 store。業(yè)務頁面里唯一的接入代碼刪掉這一行即可整塊下線template AgentPanel v-ifagentEnabled :biz-typeorder :biz-idorder.id donereload / /template核心結論一個v-if開關加一次emit就是前端側零侵入的全部成本。七、任務編排狀態(tài)機保證可重試可追蹤任務一旦異步化就必須有明確的狀態(tài)流轉與落庫記錄-- agent_db 中的任務主表status 字段驅動重試與補償CREATETABLEagent_task(task_idVARCHAR(64)PRIMARYKEY,statusTINYINTNOTNULLDEFAULT0,-- 0待執(zhí)行 1執(zhí)行中 2成功 3失敗 4補償中retryINTNOTNULLDEFAULT0,created_atDATETIMENOTNULL);狀態(tài)機PENDING → RUNNING → SUCCESS / FAILED連續(xù)失敗超閾值進入COMPENSATING自動補償。防雙跑同一task_id只允許一個執(zhí)行者搶鎖靠數(shù)據(jù)庫行鎖避免并發(fā)重復調用模型。核心結論有狀態(tài)機才有可追責的執(zhí)行鏈失敗任務才能被自動撿起來重跑。八、安全配額密鑰隔離、限流與審計留痕能力放開之前先把風險面收住這三件事缺一不可密鑰隔離模型 Key 只存在 Agent 服務的配置中心業(yè)務側與前端永遠拿不到明文。調用配額按bizType 租戶統(tǒng)計 token 消耗超閾值自動降級為規(guī)則模板回答。審計留痕每次執(zhí)行落prompt 摘要、模型版本、耗時、token 數(shù)供事后復盤與追責。核心結論沒有配額與審計的智能體上線那天就是失控那天。九、部署排錯容器拆分與高頻故障對照部署形態(tài)直接決定回滾速度先看拓撲再看故障清單# docker-compose 片段Agent 獨立成組可單獨重啟與回滾services:agent-svc:image:registry.local/agent-svc:1.4.0environment:-SPRING_PROFILES_ACTIVEproddepends_on:[agent-db]現(xiàn)象可能原因處置動作任務長期 PENDING消費者未啟動或隊列積壓查消費者實例數(shù)與積壓量回調重復落庫上游重復投遞校驗 taskId 冪等鍵主線接口變慢誤改回同步調用恢復事件異步并加超時核心結論服務與庫都獨立排錯時才能做到單點重啟、整體無感。十、可觀測性鏈路追蹤與效果回歸評估上線只是開始還得能拿出證據(jù)說明它真的有用鏈路串聯(lián)事件、任務、回調統(tǒng)一攜帶traceId taskId把主線與 Agent 兩段日志串成一條鏈。指標看板盯住任務成功率、平均耗時、token 成本、降級次數(shù)四條曲線異常自動告警。效果回歸固定一批樣例問題每周跑一遍回答質量掉檔就直接攔住發(fā)版。核心結論可觀測做到位智能體才從演示效果變成可運營能力。結語這套側掛架構把智能體的改動收斂在三處一個獨立 Agent 服務、一組獨立數(shù)據(jù)庫、一個前端掛載組件。主線只保留事件與回調兩條通道既拿到了大模型的能力又不必承擔它的不穩(wěn)定性要下線時關掉一個開關、停掉一個容器組即可業(yè)務代碼一行不改。真正難的從來不是調通一次模型而是讓智能體在企業(yè)里長期可控地跑下去——可回滾、可對賬、可限流、可追責。獨立服務、獨立數(shù)據(jù)庫、事件契約三件事湊齊智能體才算真正接進了企業(yè)系統(tǒng)。