openJiuwen Agent Core Java legacy 多智能体默认路由控制器 DefaultGroupController 深度解析

人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载导读DefaultGroupController是 openJiuwen Agent Core Javaagent-core-java中com.openjiuwen.core.multiagent.legacy包提供的 legacy 分组默认路由控制器负责在旧版ControllerGroup体系内按点对点转发或订阅广播两种模式分发组内消息。本文以官方 API 文档为骨架结合仓库源码DefaultGroupController.java、BaseGroupController.java、ControllerGroup.java深入剖析其构造方式、路由逻辑、底层消息队列机制与订阅管理 API并给出迁移到新版BaseGroup体系的建议。读完本文你将能够判断旧代码中的分组路由行为、正确使用DefaultGroupController并理解它与新版多智能体分组的演进关系。类概览legacy 分组的默认路由策略DefaultGroupController位于 legacy 兼容包其官方定义为Deprecated public class DefaultGroupController extends BaseGroupController它提供 legacy 分组的默认路由策略指定receiverId时执行点对点转发未指定receiverId时按customEventType对应的订阅关系广播。与 BaseGroupController 一样它带有Deprecated注解仅用于承接历史调用入口。legacy 包中的全部类型AgentGroupConfig、AgentGroupSession、BaseGroup、BaseGroupController、ControllerGroup、DefaultGroupController、GroupEvent、LegacyBaseGroup均被标记为废弃仅供兼容历史导入路径使用文档明确建议新代码改用新版BaseGroup体系自行组织路由。与当前仓库源码的关系说明需要注意当前仓库源码中的DefaultGroupController是一个更精简的独立路由类提供subscribe/route/getSubscriptions三个方法并被ControllerGroup直接引用而本文档描述的extends BaseGroupController继承式设计复用其消息队列与订阅管理代表了该类在 API 文档层面的设计意图。两种视角在本文中分别呈现文档描述的是默认路由逻辑的语义源码则给出了当前实际实现的路由载体。理解这一点可以避免在阅读旧代码时产生困惑。构造方法DefaultGroupController提供两个构造入口分别对应创建时绑定分组与延后绑定分组两种场景构造方法说明public DefaultGroupController(LegacyBaseGroup agentGroup)创建并立即绑定指定分组构造后即可直接参与组内路由。public DefaultGroupController()创建暂未绑定分组的默认控制器适合先构建控制器、稍后再与分组关联的使用方式。第二个构造在ControllerGroup中就是默认兜底查看 ControllerGroup.java当其构造参数groupController为空时会自动new DefaultGroupController()保证分组始终有一个可用的默认控制器。分组本身由 LegacyBaseGroup及其子类ControllerGroup承载它基于 AgentGroupConfig 管理成员 Agent。AgentGroupConfig源码AgentGroupConfig.java默认maxAgents 10可通过setMaxAgents(int)调整addAgent时若 Agent ID 重复或数量超出上限会抛出运行时错误见 LegacyBaseGroup.java。路由逻辑receiverId 优先订阅广播兜底文档定义的核心扩展点是protected Object handleEvent(GroupEvent event, AgentGroupSessionApi session)它执行默认路由逻辑整体流程可概括为三步点对点优先当event.getReceiverId()非空时直接调用sendToAgent(...)把消息流式转发给指定的单个 Agent订阅广播兜底否则依据event.getCustomEventType()触发publish(...)将事件分发给订阅了该消息类型的所有 Agent结果归一化广播结果只有一个订阅者时返回单个对象有多个订阅者时返回结果列表。其中handleEvent是 BaseGroupController 声明的抽象扩展点开发者自定义控制器时只需实现该方法的点对点或广播路由决策消息队列与订阅管理等基础设施由基类统一提供。路由决策的数据来源GroupEvent路由决策依赖事件对象 GroupEvent 携带的字段。文档给出的核心字段包括字段说明eventId随机构造的 UUID事件唯一标识query文本化查询内容queryPayload保留原始查询载荷可为字符串或交互输入对象conversationId会话 / 对话标识userId调用用户标识receiverId点对点路由目标 Agent IDcustomEventType广播路由时使用的消息类型metadata事件扩展元数据默认空 Map工厂方法createUserEvent(...)用于以文本内容与会话 ID 创建用户事件fromMap(...)则从兼容的Map输入中抽取content/query、conversation_id、user_id、receiver_id、custom_event_type等字段并把原始 Map 键值全部拷贝进metadata以保留 legacy 输入上下文。从源码看当前仓库的 GroupEvent.java 提供了createUserEvent(payload, sessionId)工厂与customEventType、queryPayload、query、conversationId、userId的读写方法是路由与sendToAgent组装输入的直接数据源。底层机制BaseGroupController 的路由基础设施由于DefaultGroupController完全复用BaseGroupController的消息队列和订阅管理能力理解其默认路由策略必须下沉到基类实现。查看 BaseGroupController.java可以梳理出以下关键机制异步消息队列与惰性启动每个分组对应一个内存消息队列MessageQueueInMemory主题名固定为group_messages_groupId队列在首次调用invoke(GroupEvent, AgentGroupSession)时通过ensureQueueStarted()惰性启动订阅主题、注册消息处理器、启动队列见 BaseGroupController.javainvoke将event与session打包为InvokeQueueMessage投递到队列随后阻塞等待响应结果L96-L122从而实现同步调用语义下的异步处理架构。sendToAgent点对点流式转发sendToAgent(GroupEvent, String agentId, AgentGroupSession)是点对点路径的执行体其实现要点L245-L298从agentGroup.getAgents()中按agentId查找目标BaseAgent找不到时记录告警并返回null以event.getQueryPayload()为空则回退event.getQuery()作为query输入并携带conversationId、userId构造输入 Map创建子AgentSession逐块迭代agent.stream(inputs, childSession, null)的输出并同步session.writeStream(chunk)透传到外层分组会话流若流式块中出现OutputSchema且type INTERACTION交互中断返回完整块列表否则返回最后一个结果块OutputSchema则取其 payload无输出时兜底返回Map.of(output, processed)。publish按订阅关系并发广播publish(GroupEvent, AgentGroupSession)是广播路径的执行体L313-L356以event.getCustomEventType()作为消息类型从订阅表查得订阅者列表类型为空或订阅者为空时直接返回空列表并记录日志所有订阅者通过共享后台执行器并发执行sendToAgent(...)OpenJiuwenExecutors.supplyBackgroundAsync逐个join()汇总结果单个订阅者被调用失败时异常对象本身也会作为结果项返回便于上层感知。这一点对点转发 订阅广播的双路径设计正是DefaultGroupController默认路由策略的底层支撑。订阅管理 APIBaseGroupController提供的订阅管理 API 是广播路由的前提也是使用DefaultGroupController时必须掌握的能力方法说明subscribe(String messageType, ListString agentIds)为指定消息类型登记订阅 Agent内部做去重处理unsubscribe(String messageType, ListString agentIds)取消指定消息类型的订阅getSubscribers(String messageType)返回当前消息类型的订阅者列表getSubscriptionsMap()返回内部订阅映射MapString, ListString从源码看当前仓库的独立版DefaultGroupController同样暴露了subscribe(String eventType, ListString agentIds)、route(GroupEvent event)与getSubscriptions()route以event.getCustomEventType()为键返回订阅者列表event为空或类型为空时返回空列表DefaultGroupController.java订阅列表以不可变快照存储。典型使用链路ControllerGroup DefaultGroupControllerlegacy 模式中分组外观类 ControllerGroup 把invoke(...)/stream(...)的实际路由逻辑委托给控制器。结合源码可以还原一条完整的使用链路创建分组配置new AgentGroupConfig(groupId)必要时调整maxAgents创建默认控制器new DefaultGroupController()ControllerGroup构造时若未显式传入控制器会自动创建创建分组new ControllerGroup(config, controller)向分组addAgent(agentId, agent)注册成员登记订阅groupController.subscribe(task_event, List.of(worker-a, worker-b))为广播路由建立订阅关系发起调用构造GroupEvent设置customEventType走广播或设置receiverId走点对点调用group.invoke(event, session)。从源码看ControllerGroup.invoke直接调用groupController.route(event)获取目标 Agent 列表再逐个以queryevent.getPayload()调用 Agent 的invoke(Map, AgentSessionApi)方法并归一化输出ControllerGroup.java当message是Map时会做兼容转换是String时生成默认会话 ID 为default_session的用户事件调用方未传session时按event.getConversationId()自动创建分组会话。测试佐证与兼容性验证legacy 包的兼容行为有测试覆盖。查看 LegacyCompatibilityAliasTest.java其中legacyAliasTypesMatchPythonImportNames验证LegacyGroupCard、LegacyEventDrivenGroupCard等 schema 别名与BaseGroup类型名仍可按历史入口使用并验证了分组 ID 与订阅映射subscriptions中worker - task的读写分组行为通过匿名BaseGroup子类覆盖invoke/stream得到验证。这些测试印证了 legacy 包兼容历史导入路径的定位旧代码依赖的类型名、会话与订阅行为在 Java 版本中得以保留。迁移建议从 legacy 到新版 BaseGroupDefaultGroupController及其所属 legacy 体系被标记为Deprecated仅用于兼容历史调用入口。在 legacy.README 与 BaseGroupController.md 中均明确建议新代码优先使用新版BaseGroup体系自行组织路由不必依赖 legacy 控制器的消息队列与订阅表存量代码在迁移时可将ControllerGroupDefaultGroupController的点对点 / 订阅广播语义映射到新版分组的路由能力上并同步从GroupEvent携带的receiverId、customEventType字段推导目标 Agent 集合迁移过程中注意AgentGroupConfig的maxAgents限制默认 10在旧版addAgent与新版分组中的一致性。总结DefaultGroupController是理解 openJiuwen legacy 多智能体分组的钥匙它以最小成本提供了指定receiverId点对点转发、按customEventType订阅广播的默认路由语义底层由BaseGroupController的内存消息队列、惰性队列启动、流式sendToAgent与并发publish支撑。虽然当前仓库源码中的实现已演进为更精简的subscribe/route路由器并被ControllerGroup直接使用但其路由决策的本质——按receiverId或customEventType决定目标 Agent 集合——与文档描述完全一致。对于需要维护旧代码的开发者本文提供的构造方式、订阅 API 与调用链路可直接用于排查和改造对于新项目则应遵循官方建议直接采用新版BaseGroup体系。延伸阅读本文涉及的关联文档与源码均可在仓库中继续深入BaseGroupController基类机制、ControllerGroup分组外观、GroupEvent路由事件模型、LegacyBaseGroup分组基类、AgentGroupConfig分组配置、legacy.README包总览。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐openJiuwen agent-core-java ControllerGroup 详解Legacy 控制器驱动分组的路由与流式实现openJiuwen agent core java ControllerGroup 详解Legacy 控制器驱动分组的路由与流式实现 导读 Controll人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen agent-core-java 控制器事件处理深度解析EventHandler 抽象基类与四类控制器事件路由机制openJiuwen agent core java 控制器事件处理深度解析EventHandler 抽象基类与四类控制器事件路由机制 本文围绕 openJi人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习openJiuwen agent-core-java 中 DefaultDbStore基于 JDBC 的默认数据库存储包装器深度解析openJiuwen agent core java 中 DefaultDbStore基于 JDBC 的默认数据库存储包装器深度解析 本文围绕 openJiu人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习上一篇攻克iOS键盘兼容难题objcMembers如何为IQKeyboardManager架起Swift与Objective-C的桥梁下一篇彻底解决Weex手势冲突触摸事件优先级管理指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考