在不少企业尝试引入 AI 智能体时，常见做法是单独部署一个 Agent 服务，再让业务系统调用。但如果目标是让智能体成为中台能力的一部分，问题就会从“能不能跑起来”变成“如何与既有 Java 工程体系融合”。近期，AI架构师张磊在掘金分享了一个基于 RuoYi-Vue-Plus 集成 AgentScope Harness 的实践，重点涉及装配机制、工具白名单、MCP 适配以及会话级资源组合管理。该案例将智能体模块放在 ruoyi-modules/ruoyi-ai 下的 org.dromara.ai 包中，使 Agent 能力直接成为中台的一个模块。
AgentRegistry 负责装配，避免每轮对话重建客户端
这一集成方案的核心入口是 AgentRegistry。它的职责并不是简单创建一个智能体，而是根据“智能体定义 × 会话资源集”组合，把模型、工具、权限、中间件和策略拼装成一个可复用的 HarnessAgent 实例，并按指纹缓存。当定义或资源组合发生变化时，实例会自动重建；否则沿用已有实例，避免每轮对话都重新创建模型 HTTP 客户端。
从素材披露的装配主干看，Agent 的构建内容包括名称、描述、系统提示词、OpenAI 兼容模型客户端、工具集、Redis 状态存储、独立工作目录、单轮最大迭代次数、工具 allow/deny 配置、三档授权规则以及平台中间件。由于企业平台没有沙箱，框架默认的文件系统工具、Shell 工具和 Memory 工具被显式关闭。技能来源也不使用框架默认工作区技能，而是来自项目自身数据库，并通过 SkillFilter 限定可用技能。
白名单裁剪是关键：MCP 工具不显式放行就会被过滤
在工具管理上，框架默认工具箱会附带联网检索、文件、命令等内置工具。对于没有沙箱环境的企业平台来说，这类能力必须收敛。该项目在 buildToolsConfig 中同时设置 allow 与 deny：允许列表包含注册工具、技能内置工具以及 MCP 工具名；黑名单则显式禁用 web_search 与 web_fetch。
素材中提到一个容易被忽略的坑：技能内置工具和 MCP 工具都必须显式加入 allow 名单，否则会被框架的 ToolFilter 直接裁掉。此时模型看不到相关工具，开发者却很难从表面现象判断原因。这种“工具不可见”的问题，在企业级 Agent 集成中往往比报错更难排查。
MCP 双向适配：工具名归一化与连接泄漏处理
MCP 是这次集成中的另一条主线。平台自建了 /mcp 服务端，不依赖 spring-ai，可把标记为“对外暴露”的只读工具提供给外部调用方，并支持访问口令校验，例如 Authorization: Bearer <token> 或 X-MCP-Token。
在接入外部 MCP Server 时，项目没有直接使用框架的 ToolsConfig.mcpServers，而是自行注册经过“归一化名装饰”的 MCP 客户端。原因是远端工具名可能不符合大模型 function name 规范，例如 weather.search_local 中的点号，在严格校验的模型上会导致整轮 400。为此，平台在装配期进行工具名归一化：合法名称原样保留，非法字符替换为下划线；若发生撞名，则追加原名哈希后缀。这样，weather.search_local 会以 weather_search_local 注册，模型即可正常调用。
素材还指出，框架的 McpClientManager 不负责关闭客户端，因此注册失败时必须由装配方主动调用 close()，否则会造成连接泄漏。这类问题通常不会在正常流程中暴露，只有在异常路径下才会变成隐患。
会话级资源集带来灵活性，也引入实例管理成本
在入口智能体“小Z”的设计上，平台没有直接绑定业务工具，而是让工具来自会话级资源集。用户可以在对话底栏选择专家、场景包、工具、技能或 MCP 工具。由于工具可见面是在装配期确定的，运行期没有等价的覆盖通道，项目将资源集压缩为确定性签名，并写入装配缓存键：小Z 使用 agentId#R:<sig>，专家使用 agentId#__expert__#R:<sig>。其中 sig 为排序后的 type:key 列表经 SHA-256 计算后取前 8 字节。
这种设计的好处是完全复用既有装配与权限机制，用户切换资源组合后，下一轮对话即可重新装配生效；代价则是装配实例数量会随资源组合种类增长，同组合的多个会话可以共享实例。素材还提到一个与状态版本有关的问题：框架的 AgentState 采用版本化 CAS，如果某个实例服务过某会话后，该会话状态被另一实例推进，再复用旧实例可能出现反序列化失败。规避方式是为每个会话记录最近一次装配使用的资源集签名，会话内切换资源组合时主动丢弃目标实例。
一个真实用户反馈也体现了会话级设计带来的理解成本。用户在“MCP 客户端”页面配置好天气工具后，认为入口智能体应该可以直接使用。但排查后发现，MCP 工具属于会话级资源，“MCP 客户端”页的配置只表示工具可被选中，新会话默认是空集，仍需在对话底栏勾选。素材认为，这不是缺陷，但产品层面需要用 UI 清楚说明“配置好了”和“对本轮可用”是两件事，否则用户容易误以为工具失效。
对 Java 企业 Agent 平台的启示
这次实践没有追求一个炫目的独立 Agent 产品，而是把智能体能力嵌入成熟中台。工具实现必须存在于代码侧，注册表只保存元数据，避免“裸 SQL / 裸 Shell / 裸 HTTP”式的万能工具；目前代码侧登记了 25 个工具实现，覆盖部门、用户、公告、角色、菜单权限、知识库检索等场景，其中写入类工具统一走 HITL。状态存储则复用项目已有 RedissonClient，使用 RedisAgentStateStore 替代已废弃的 RedissonAgentStateStore，两者键布局一致，切换无需数据迁移。
这些细节共同指向一个结论：企业级 Agent 平台的难点不只是接入模型，而是如何把工具权限、资源组合、状态管理和异常处理纳入既有工程规范。对于正在使用 Java 中台体系探索 AI 智能体落地的团队而言，这类集成经验比单纯的功能展示更有参考价值。
原创文章，作者：点点，如若转载，请注明出处：https://www.dian8dian.com/java-zhong-tai-ru-he-nei-qian-agent-neng-li-agentscope
