企业里一接大模型智能体最扎眼的矛盾就来了既要 Agent 快速见效又不能动已经稳定跑了三年的业务主线。可现实常常是对话记录、向量切片、任务流水一股脑塞进主库模型一超时整条下单链路跟着抖。常规做法之所以不够用在主服务里直接写 LLM 调用、复用主库表存会话、同步等待模型返回会让依赖膨胀、事务边界被打穿Agent 每迭代一次就得带着整个系统重新发版。本文分享一套可直接落地的侧挂式方案独立 Agent 服务 独立数据库 主线零侵入的事件契约前端组件松耦合挂载、随拆随上。一、架构选型智能体侧挂而不是嵌入主干先做一次选型对照再决定 Agent 到底落在哪一侧维度嵌入主服务侧挂独立服务发版节奏随业务系统全量发布独立灰度、独立回滚依赖引入主工程引入模型 SDK主线仅留一个出站接口故障半径模型超时拖垮业务线程池Agent 挂掉后主线无感数据归属会话与业务表混放独立库独立生命周期侧挂定义Agent 作为旁路服务存在主线只认「事件进、结果回」两条通道。主线保留只留一个轻量出站适配器代码里不出现任何模型 SDK、提示词与解析逻辑。判定标准把 Agent 目录整个删掉主线仍能正常下单收款才算真正零侵入。核心结论把智能体当外部协作方接入而不是当业务代码的延伸。二、服务边界网关与业务域各管一段拆分之前先把职责切干净边界模糊比跑得慢更致命业务服务只负责产生事实数据发出order.paid之类的领域事件完全不关心谁来消费。Agent 网关承接鉴权、会话路由、模型适配与限流对内统一暴露POST /agent/run。结果回流通过回调或事件写回业务侧主线只按任务号幂等落账不做二次加工。事件进 → 网关编排 → 模型执行 → 结果回流 → 主线落账核心结论边界越硬后期换模型、换向量库的代价就越低。三、数据隔离会话与向量落独立库智能体的数据有自己的生命周期先列清单再决定建几个库数据类别归属库保留策略会话与消息agent_db90 天滚动清理向量与切片agent_vector随文档版本重建任务流水agent_db按审计要求归档业务事实数据原业务库不复制、不冗余不跨库事务主线与 Agent 之间只追求最终一致靠taskId做对账与补偿。只读共享确需业务上下文时用只读账号同步一份快照表严禁 Agent 反向写主库。核心结论数据一旦同库所谓零侵入就只剩一句口号。四、零侵入对接事件驱动与异步回调解耦主线要的从来不是能力而是稳定接入方式直接决定侵入程度同步直调模型动辄十几秒长期占用业务线程池一次抖动会被放大成全局故障。事件异步主线发完事件即可返回Agent 慢、挂、重试都不影响主流程的响应时间。回调幂等回写结果必须带taskId上游重复投递时按状态机去重避免重复落账。领域事件 → 消息队列 → Agent 消费 → 执行任务 → 回调主线 → 幂等落库核心结论主线代码里只出现「发」和「收」两个动作这就是零侵入的可验证标准。五、接口契约三类端点撑起前后端约定前后端能并行开发靠的是一张稳定的契约表端点方法用途关键参数/agent/sessionPOST创建会话bizType、bizId/agent/runPOST触发任务taskId、prompt、stream/agent/task/{id}GET查询进度status、resultUrl契约稳定字段只增不改后端升级模型版本不会波及任何前端代码。状态可查任务永不阻塞请求前端拿到taskId后按节奏轮询。下面这段是 Vue3 Vite 前端里触发任务并轮询状态的最小可用封装// 触发智能体任务并轮询其状态适配 Vue3 浏览器环境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);}发任务拿 taskId → 定时轮询 → 状态变 SUCCESS 取 resultUrl核心结论契约一旦冻结前后端就能各自独立发版。六、前端挂载侧边栏组件松耦合接入组件接入要做到拔掉就恢复原样成本只有一行代码独立目录Agent 组件单独放components/agent-panel主页面只保留一行引用。props 传上下文业务方只传bizType与bizId组件内部自己建会话、自己拉状态。事件回抛需要主线刷新时用emit(done)组件里不 import 任何业务 store。业务页面里唯一的接入代码删掉这一行即可整块下线template AgentPanel v-ifagentEnabled :biz-typeorder :biz-idorder.id donereload / /template核心结论一个v-if开关加一次emit就是前端侧零侵入的全部成本。七、任务编排状态机保证可重试可追踪任务一旦异步化就必须有明确的状态流转与落库记录-- agent_db 中的任务主表status 字段驱动重试与补偿CREATETABLEagent_task(task_idVARCHAR(64)PRIMARYKEY,statusTINYINTNOTNULLDEFAULT0,-- 0待执行 1执行中 2成功 3失败 4补偿中retryINTNOTNULLDEFAULT0,created_atDATETIMENOTNULL);状态机PENDING → RUNNING → SUCCESS / FAILED连续失败超阈值进入COMPENSATING自动补偿。防双跑同一task_id只允许一个执行者抢锁靠数据库行锁避免并发重复调用模型。核心结论有状态机才有可追责的执行链失败任务才能被自动捡起来重跑。八、安全配额密钥隔离、限流与审计留痕能力放开之前先把风险面收住这三件事缺一不可密钥隔离模型 Key 只存在 Agent 服务的配置中心业务侧与前端永远拿不到明文。调用配额按bizType 租户统计 token 消耗超阈值自动降级为规则模板回答。审计留痕每次执行落prompt 摘要、模型版本、耗时、token 数供事后复盘与追责。核心结论没有配额与审计的智能体上线那天就是失控那天。九、部署排错容器拆分与高频故障对照部署形态直接决定回滚速度先看拓扑再看故障清单# docker-compose 片段Agent 独立成组可单独重启与回滚services:agent-svc:image:registry.local/agent-svc:1.4.0environment:-SPRING_PROFILES_ACTIVEproddepends_on:[agent-db]现象可能原因处置动作任务长期 PENDING消费者未启动或队列积压查消费者实例数与积压量回调重复落库上游重复投递校验 taskId 幂等键主线接口变慢误改回同步调用恢复事件异步并加超时核心结论服务与库都独立排错时才能做到单点重启、整体无感。十、可观测性链路追踪与效果回归评估上线只是开始还得能拿出证据说明它真的有用链路串联事件、任务、回调统一携带traceId taskId把主线与 Agent 两段日志串成一条链。指标看板盯住任务成功率、平均耗时、token 成本、降级次数四条曲线异常自动告警。效果回归固定一批样例问题每周跑一遍回答质量掉档就直接拦住发版。核心结论可观测做到位智能体才从演示效果变成可运营能力。结语这套侧挂架构把智能体的改动收敛在三处一个独立 Agent 服务、一组独立数据库、一个前端挂载组件。主线只保留事件与回调两条通道既拿到了大模型的能力又不必承担它的不稳定性要下线时关掉一个开关、停掉一个容器组即可业务代码一行不改。真正难的从来不是调通一次模型而是让智能体在企业里长期可控地跑下去——可回滚、可对账、可限流、可追责。独立服务、独立数据库、事件契约三件事凑齐智能体才算真正接进了企业系统。