Spring Boot 4.1 + AgentScope 2.x 集成企业级 Agent 平台实战
很多团队做企业 Agent,第一步就走偏了:先起一个独立的 Agent 服务,再让业务系统去调它。我们换了个做法——把智能体内核直接装进一个成熟的中台,让它变成中台里的一个模块。这篇复盘讲清楚三件事:为什么这么做、集成时真正要解决什么、以及我们踩过的坑。
一、不要独立 Agent 服务,要中台长出一个模块
最常见的做法是先搭一个独立的 Agent 服务,再让业务系统去调。问题会在落地半年后集中爆发:两套账号体系、两套权限、两份审计、两次部署——业务方问「这个操作是谁批准的」,答案散在两个系统里。
我们的目标从一开始就很明确:一个进程、一个 jar、一套构建,复用底座的权限、事务、缓存与审计,前端仍是一个 Vue 工程,靠 SSE 拿流式回答。
落点是把 Spring Boot 4.1.1 的 开源中后台底座 当企业底座,在其中新增一个 AI 模块承载全部智能体能力。底座本来就有 RBAC、工作流、调度、文件存储,以及权限与留痕机制——所有「治理」类需求因此都有地方落。
二、选型:内核用 AgentScope,其余尽量复用
| 分类 | 组件 |
|---|---|
| 语言 / 运行时 | Java 21 |
| 业务底座 | Spring Boot 4.1.1(Jetty) |
| 智能体内核 | AgentScope Java Harness 2.0.4 |
| MCP | 官方 MCP Java SDK |
| 状态存储 | Redis(AgentScope RedisAgentStateStore) |
| 向量库 | Milvus 2.6.13 |
| 权限 | Sa-Token 1.46.0 |
| 关系库 | PostgreSQL 14 / MySQL 8.0(并列支持) |
选 AgentScope 的理由是它「够薄」:智能体装配、工具调用、状态存储、暂停恢复都给了稳定抽象,同时不强行接管你的权限与审计——这正是企业场景最需要的留白。2.0.4 相对 2.0.3 是纯增量、无 API 破坏,我们只调了版本号就完成升级。
还有一条容易被忽略:整条链路是纯 Java——没有独立的 Agent 服务、没有 Python 边车、也没有脚本桥,装配、决策与上下文传递都在同一个 JVM 里完成。对企业来说,这意味着依赖收敛、故障面收敛,也可以直接复用 Java 生态里成熟的线程模型与可观测工具。
三、集成要解决的其实只有三件事
装配可控。 框架默认工具箱会附带联网检索、文件、命令等内置能力。企业平台没有沙箱,所以我们在装配期用 allow / deny 双重收敛:非平台登记的工具一律不在白名单,联网检索显式拉黑。工具可见面在装配那一刻就定死,运行期不开后门。
java
// 装配期就把工具可见面定死:白名单之外的工具,模型根本看不到
ToolsConfig tools = new ToolsConfig();
tools.setAllow(registeredCodes); // 平台登记的业务工具 + 技能 / MCP 工具
tools.setDeny(List.of("web_search", "web_fetch")); // 企业环境统一关掉联网检索状态持久。 多轮记忆、人工确认的暂停与恢复,都依赖状态存储。我们直接复用项目已有的 Redis 客户端构建状态存储,键前缀统一收敛,切换实现时键布局不变、无需数据迁移。
java
@Bean
public AgentStateStore aiAgentStateStore(RedissonClient redissonClient) {
return RedisAgentStateStore.builder()
.redissonClient(redissonClient) // 复用项目已有的 Redis 客户端
.keyPrefix("bizbuddy:ai:agentscope") // 键前缀统一收敛
.build();
}边界显式。 技能来源、MCP 工具、技能仓库都要显式接入,框架不会替你猜。技能仓库尤其典型:它按数据源类型自动装配,PostgreSQL 与 MySQL 两套形态都能直接跑。
四、企业级的分水岭:权限、确认、审计
功能能跑通不代表能进生产。真正区分演示与生产的,是下面三件事。
工具级三档授权。 允许、需人工确认、禁止。只读查询放行,写操作默认要人确认,敏感能力干脆不装配。授权支持多来源叠加,越显式的来源优先级越高,「全局从严、个别放宽」因此变成一条可配置项,而不是散落在代码里的硬编码。还有一个容易踩的坑:「记住该工具」这类信任必须是用户级的,一旦写进共享上下文,A 用户点过一次免确认,B 用户就被悄悄放行了。
java
HarnessAgent.builder()
.toolkit(toolkit) // 只放入「允许」与「需确认」的工具
.permissionContext(permissionContext) // 三档授权规则:多来源叠加,越显式优先级越高
.build();人工确认走框架原生链路。 涉及写库或写外部系统的调用会暂停本轮,在对话里等确认,确认后再继续。这样「暂停—恢复」两段属于同一次问答,审计上只算一次、复用同一条链路,不会留下两条互相矛盾的记录。
全程审计链。 会话与消息、工具调用、权限决策、链路追踪、编排运行五类留痕,落库的是执行当时的真实快照,而不是事后拼凑。代价是写入更重,收益是任何一次回答都能被完整还原:用了哪个模型、调了哪些工具、谁批准的、花了多少 Token。
五、三个踩过的坑
坑一:远端 MCP 工具名可能不合模型规范。 外部 MCP 服务器上的工具名常带点号(如 weather.search_local),在严格校验的模型上会导致整轮 400。解法是在装配期做名字归一化:非法字符替换为下划线,撞名时追加原名哈希后缀。小事,但足以让整轮对话失败。
坑二:「配好了」不等于「本轮可用」。 真实用户报过「我配了 MCP 客户端,为什么小Z 还是不会查天气」。排查发现那两个会话的资源列表里一行都没有——平台的工具是会话级的:配置页只是让工具可被选中,新会话默认空集,要在对话底栏显式勾选。产品上必须用 UI 讲清这个区别,否则用户只会认为工具坏了。
坑三:一个只在端到端测试里才暴露的收尾缺陷。 「停止生成」要真正中断后端编排,而不是只停前端消费。第一版修完后,端到端用例仍会间歇失败:日志显示取消分支已进入,但专家调用明细一行都没落库。根因是外层释放对工作线程的中断是异步送达的——它会落在取消收尾期间,让收尾里的 Redis 读写抛异常、直接跳过审计落库。最后的修法不是「多清一次中断标志」,而是立下一个不变量:取消收尾的审计明细不可被跳过——把审计插入提到一切外部调用之前,把预算、子链路这类记账降级为「尽力而为、失败只告警」。修复后两套部署栈各连跑十余次全通过。
六、验证:单测之外,还要能「真的跑起来」
单测全打桩、不起容器,能证明分支正确,但不证明跑起来能用。于是仓库里配了一套零依赖的端到端脚本,对已运行的容器栈发真实 HTTP 请求,覆盖模型连通、知识库检索、对话与专家编排、人工确认闭环、停止生成、安全合规、MCP 双向等十余个层级;另有一组默认跳过的集成测试,专盯「框架 × 配置」这类两边都抓不到的缺陷——真库方言一致性、实体与表结构对齐、技能仓库读写、上下文装配。
两套部署栈(PostgreSQL / MySQL)并列支持,一条命令即可拉起可登录的完整环境,企业可按既有技术栈选型。
七、小结
把 Agent 内核装进中台,真正要解决的只有三件事:装配要可控、状态要持久、边界要显式。而在企业里能不能落地,取决于另外三件事:权限、人工确认、审计。前者决定它能不能用,后者决定它能不能进生产。
关于 BizBuddy
BizBuddy 是一个全量开源的企业级智能体平台(MIT License):Spring Boot 4.1.1 + JDK 21 做底座,AgentScope Java Harness 做智能体内核,纯 Java 全栈、不含 Python。本文这套集成方案就是它的实际实现,代码全量开源,欢迎交流与共建。
欢迎 Star、Issue 与共建。