前两篇讲了「是什么」和「权限怎么落地」。这一篇讲工程智能体内核怎么与一个成熟的 Java 中台对接以及我们踩过的坑。一、目标让中台「长出」智能体内核我们不想要一个独立的 Agent 服务再让业务系统去调它。目标是把智能体能力做成中台的一个模块一个进程、一个 jar、一套构建复用底座的权限、事务、缓存、审计前端仍是一个 Vue 工程通过 SSE 拿流式回答。落点就是ruoyi-modules/ruoyi-ai包org.dromara.ai。二、依赖与版本分类组件版本语言 / 运行时Java21业务框架Spring Boot4.1.1Jetty智能体内核AgentScope Harness2.0.3MCP官方 MCP Java SDK0.17.2状态存储Redis经 RedissonAgentScopeRedisAgentStateStore技能仓库PostgreSQLAgentScopePostgresSkillRepository向量库Milvusv2.6.13权限Sa-Token1.46.0三、装配一个 HarnessAgent装配集中在AgentRegistry。它的职责是按「智能体定义 × 会话资源集」把模型、工具、权限、中间件、策略拼成一个可复用的HarnessAgent实例并按指纹缓存——定义或资源组合变化时自动重建避免每轮对话都新建模型 HTTP 客户端。装配主干大致是这样HarnessAgent.BuilderbuilderHarnessAgent.builder().name(definition.getAgentCode()).description(...).sysPrompt(...)// 智能体提示词专家装配时追加「技能优先」纪律.model(model)// OpenAI 兼容客户端含超时与重试.toolkit(toolkit)// 业务工具 MCP 工具 协议工具.stateStore(stateStore)// Redis 状态存储多轮记忆.workspace(workspace)// 每个智能体一个工作目录.maxIters(maxIters)// 单轮最大迭代次数.toolsConfig(buildToolsConfig(...))// allow / deny 白名单裁剪.permissionContext(...)// 三档授权规则.middlewares(buildMiddlewares(definition));// 关闭平台不需要的能力无沙箱禁文件/命令工具builder.disableFilesystemTools().disableShellTool().disableMemoryTools();// 技能来自本项目数据库关闭框架默认的工作区技能来源builder.skillRepositories(List.of(aiSkillRepository)).skillFilter(SkillFilter.only(skillNames));builder.disableDefaultWorkspaceSkills();几个值得展开的点。3.1 工具白名单裁剪allow / deny框架的默认工具箱会附带联网检索、文件、命令等内置工具。企业平台没有沙箱所以必须双重收敛privateToolsConfigbuildToolsConfig(ListStringregisteredCodes,ListStringskillNames,McpClientAssemblymcpAssembly){ListStringallownewArrayList(registeredCodes);if(!skillNames.isEmpty()){allow.addAll(SKILL_BUILTIN_TOOLS);// 技能内置工具须显式放行}if(!mcpAssembly.toolNames().isEmpty()){allow.addAll(mcpAssembly.toolNames());// MCP 工具名同样须显式放行}ToolsConfigconfignewToolsConfig();config.setAllow(allow);// 白名单非平台工具一律移除config.setDeny(List.of(web_search,web_fetch));// 显式黑名单禁联网检索returnconfig;}教训技能内置工具、MCP 工具都必须显式放进 allow 名单否则会被框架的ToolFilter直接裁掉——模型看不到你还找不到原因。3.2 中间件注入平台级中间件对所有智能体自动生效CurrentTimeMiddleware每轮现算当前时间日期 星期 时分 时区注入 system prompt。模型自己不知道「今天几号」框架原生注入的又是英文日期。ExpertRosterMiddleware只对入口智能体注入「本轮候选专家清单」。SlotInheritanceMiddleware只对入口智能体注入「槽位继承」。中间件的好处是每轮现算、不进装配指纹——清单变了不必重建 Agent 实例。四、状态与持久化4.1 会话状态Redis多轮记忆、暂停恢复都依赖状态存储。我们直接复用项目已有的RedissonClientBeanpublicAgentStateStoreaiAgentStateStore(RedissonClientredissonClient){returnRedisAgentStateStore.builder().redissonClient(redissonClient).keyPrefix(bizbuddy:ai:agentscope).build();}用的是RedisAgentStateStore而非已Deprecated的RedissonAgentStateStore两者键布局一致切换无需数据迁移。4.2 技能仓库复用业务表技能的建表与写入由项目自己的 SQL 与服务负责保留审计列与生效范围治理框架侧只读returnPostgresSkillRepository.builder(dataSource).schemaName(public).skillsTableName(ai_skill).resourcesTableName(ai_skill_resource).createIfNotExist(false)// 不让框架建表.writeable(false)// 框架只读.build();五、工具接入业务工具工厂平台的工具注册表ai_tool只存元数据编码、名称、描述、参数 Schema、类型、实现标识真正的实现必须存在于代码侧// 注册页只登记元数据implName 对应代码侧已实现的 AgentTooltoolFactory.create(definition,kbIds).ifPresent(toolkit::registerAgentTool);这道设计有意为之避免出现「裸 SQL / 裸 Shell / 裸 HTTP」的万能工具。目前代码侧登记了 25 个工具实现覆盖部门 / 用户 / 公告 / 角色 / 菜单权限 / 知识库检索等其中写入类工具统一走 HITL。六、MCP 双向集成6.1 出口把只读工具暴露出去平台自建/mcp服务端不依赖 spring-ai可把标记为「对外暴露」的只读工具提供给外部调用方并支持访问口令校验Authorization: Bearer token或X-MCP-Token。6.2 接入外部 MCP 工具接入外部 MCP Server 时我们没有走框架的ToolsConfig.mcpServers而是自行注册「归一化名装饰后」的客户端// 与框架 McpServerRegistrar 内部一致registerMcpClient(...).block()// 且在 build() 之前完成故仍受 ToolFilter 的 allow 名单管辖toolkit.registerMcpClient(client).block(Duration.ofSeconds(20));原因远端工具名可能不满足 LLM 的 function name 规范例如weather.search_local带点号在严格校验的模型上会整轮 400。平台因此在装配期做工具名归一化合法名原样保留非法字符替换为下划线撞名时追加原名哈希后缀。这样weather.search_local会以weather_search_local注册模型即可正常调用。另外框架的McpClientManager不负责关闭客户端所以注册失败时必须由装配方close()否则连接泄漏。七、装配单元从「智能体 × 场景包」到「智能体 × 资源集签名」入口智能体「小Z」不绑定业务工具它的工具来自会话级资源集对话底栏选择专家 / 场景包 / 工具 / 技能 / MCP 工具。由于工具集是装配期决定的allow 名单在装配时固定运行期没有等价的「工具可见面覆盖」通道。所以资源集被压成确定性签名直接进装配缓存键小Z agentId # R:sig // sig SHA-256(排序后的 type:key 列表) 前 8 字节 专家 agentId # __expert__ # R:sig好处是完全复用既有的装配与权限机制改选择后下一轮即重新装配生效代价是装配实例数随「资源组合种类」增长同组合的多个会话共享实例。八、踩坑记录坑 1状态版本 CAS 与实例复用冲突框架的AgentState走版本化 CASsaveIfVersion → getVersioned。当某个实例先服务过某会话、随后该会话状态被另一实例推进时再复用这个实例会反序列化失败Failed to get versioned state: agent_state。规避方式为每个会话记录「最近一次装配用的资源集签名」会话内切换资源组合时主动丢弃目标实例下次新建即可。坑 2MCP 工具名不合规导致整轮 400见 §6.2。归一化是同款问题的通用解法。坑 3框架不释放 MCP 连接见 §6.2。注册失败路径必须自行关闭。坑 4「我配了 MCP 客户端为什么小Z 还是不知道天气」这是一个被真实用户报上来的问题很典型。用户已经在「MCP 客户端」页配好了天气工具于是认为小Z 应该会用。排查后发现那两个报「不知道」的会话ai_session_resource里一行资源都没有装配日志显示mcpTools[]、空集签名而更早一个会话当时通过底栏选中了该 MCP 工具确实成功调用过天气工具。结论MCP 工具是「会话级」的。「MCP 客户端」页的配置只是让工具可被选中新会话默认是空集必须在底栏里勾选。这是平台既定的会话级设计不是缺陷。这个坑值得所有做企业 Agent 的团队注意「配置好了」和「对本轮可用」是两件事产品上要用 UI 把这个区别讲清楚否则用户会认为工具坏了。九、小结把 Harness 装进中台核心就三件事装配要可控allow / deny 白名单 装配期权限规则工具可见面在装配时定死状态要持久Redis 状态存储承载多轮记忆与 HITL 暂停恢复边界要显式技能工具、MCP 工具、技能仓库都要显式接入框架不会替你猜。再叠加前两篇讲的「三层权限」一个纯 Java 的企业级 Agent 平台就立起来了。相关仓库代码https://gitee.com/zl3624/biz-buddy作者AI架构师张磊