人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载BaseGroup是 openJiuwen agent-core-javacom.openjiuwen.core.multiagent包新版多 Agent 分组的抽象基类采用GroupCard定义分组是什么 GroupConfig定义分组如何运行的 Card Config 设计模式统一管理 Agent 注册、组配置与同步/流式执行入口。本文将从实例化方式、核心方法语义、成员管理约束、分组引用自动注入、运行配置参数到自定义分组实现结合仓库源码与系统测试逐层展开帮助你基于BaseGroup快速搭建自己的多 Agent 分组并正确接入AgentGroupSession完成消息的分发与聚合。一、设计定位新版分组抽象基类BaseGroup位于 core/src/main/java/com/openjiuwen/core/multiagent/BaseGroup.java定义如下public abstract class BaseGroup它的设计原则与BaseAgent对齐从源码注释中可以提炼出三条核心约定Card 是必选项GroupCard定义分组身份分组是什么Config 是可选GroupConfig定义运行参数分组如何运行所有配置方法支持链式调用configure(...)、addAgent(...)均返回BaseGroup自身便于流式搭建。源码注释同时说明该实现对应 Python 版本multi_agent/group.py中的BaseGroup因此了解 Python 版 openJiuwen 的开发者可以无缝迁移。需要留意的是仓库中还保留了一套基于AgentGroupConfig的旧版分组基类core/src/main/java/com/openjiuwen/core/multiagent/legacy/BaseGroup.java标注为 legacy 模式本文聚焦文档所述的新版 Card Config 模式。二、实例化两个受保护的构造方法BaseGroup的构造方法均为protected说明它只能被自定义分组子类在super(...)中调用不能直接new。1.protected BaseGroup(GroupCard card, GroupConfig config)供子类在自定义分组实现中调用。源码实现BaseGroup.javaprotected BaseGroup(GroupCard card, GroupConfig config) { this.card card; this.config config ! null ? config : createDefaultConfig(); this.groupId card.getName(); }当config null时回退到默认GroupConfignew GroupConfig()用card.getName()固化当前groupId之后getGroupId()恒返回该值。2.protected BaseGroup(GroupCard card)供只需要卡片信息的子类使用内部委托到双参数版本并创建默认GroupConfigprotected BaseGroup(GroupCard card) { this(card, null); }3. GroupCard 的构建方式GroupCard继承自TeamCard因此分组与团队共享同一套卡片形状id、name、description、topic、version、tags、agentCards。推荐使用其 Builder 构建core/src/main/java/com/openjiuwen/core/multiagent/schema/GroupCard.java 中 Builder 支持以下字段字段默认值说明id必填null/blank 抛异常分组唯一标识name必填null/blank 抛异常分组名称将固化为groupIddescription分组描述topic分组主题version1.0.0分组版本tags空列表标签列表agentCards空列表初始成员卡片列表GroupCard card GroupCard.builder() .id(group-001) .name(incident-response-group) .description(multiagent system test group) .build();三、核心方法全景文档给出的方法总表如下覆盖分组生命周期、成员管理与执行入口方法返回说明configure(GroupConfig config)BaseGroup覆盖当前运行配置并返回自身以便链式调用。addAgent(BaseAgent agent, String agentId)BaseGroup向分组注册 Agent未显式传入agentId时优先使用agent.getCard().getName()。addAgent(BaseAgent agent)BaseGroup使用 Agent 卡片名称作为 ID 的便捷重载。removeAgent(String agentId)BaseGroup按 ID 移除 Agent并同步删除card.getAgentCards()中同名卡片。removeAgent(BaseAgent agent)BaseGroup通过 Agent 实例推断 ID 后执行移除。getAgent(String agentId)BaseAgent读取指定 ID 的 Agent不存在时返回null。getAgentCount()int返回当前已注册 Agent 数量。listAgents()ListString以注册顺序返回所有 Agent ID。getCard()GroupCard返回当前分组卡片。getConfig()GroupConfig返回当前运行配置。getGroupId()String返回构造阶段固定下来的分组 ID。getAgents()MapString, BaseAgent返回内部 Agent 映射。invoke(Object message, AgentGroupSession session)Object子类实现的同步执行入口。stream(Object message, AgentGroupSession session)IteratorObject子类实现的流式执行入口。配置覆盖configure(GroupConfig)源码实现BaseGroup.java直接替换内部config引用并返回thispublic BaseGroup configure(GroupConfig config) { this.config config; return this; }注意configure是整体替换而非合并因此建议在构造阶段一次性传入配置或在链式搭建时最后调用configure完成覆盖。四、成员管理语义注册、校验与移除1.addAgent的完整注册流程以双参数版本为核心BaseGroup.java流程如下ID 推导agentId null时优先使用agent.getCard().getName()若 Agent 既无卡片名也未显式传 ID抛出AGENT_GROUP_ADD_RUNTIME_ERROR。重复 ID 校验内部agents映射LinkedHashMap已包含该 ID 时抛异常。上限校验getAgentCount() config.getMaxAgents()时抛异常。写入映射agents.put(agentId, agent)。卡片同步若 Agent 有卡片card.getAgentCards().add(agent.getCard())。分组引用自动注入见下文。返回this支持链式调用。单参数addAgent(BaseAgent agent)是addAgent(agent, null)的便捷重载直接使用 Agent 卡片名称作为 ID。2. 异常码与错误信息上述校验抛出的异常统一使用StatusCode.AGENT_GROUP_ADD_RUNTIME_ERROR错误码132000见 core/src/main/java/com/openjiuwen/core/common/exception/StatusCode.java。文档中的三条约束逐一对应源码重复 IDAgent ID agentId already exists超过上限Agent count exceeds max_agents ( config.getMaxAgents() )无法推导 IDAgent must have card.name or provide agentId。3.removeAgent的同步删除按 ID 移除时BaseGroup.java先从agents映射移除实例再通过card.getAgentCards().removeIf(c - agentId.equals(c.getName()))同步删除同名卡片保证内部映射与对外卡片列表始终一致。按实例移除的重载通过agent.getCard().getName()推断 ID 后委托给按 ID 版本若无法推断 ID仅记录 warn 日志并返回this不会误删。4. 查询能力getAgent(String)直接返回agents.get(agentId)不存在返回nullgetAgentCount()返回agents.size()listAgents()基于LinkedHashMap的 key 顺序返回所有 Agent ID保证注册顺序稳定源码 BaseGroup.java 中new ArrayList(agents.keySet())。五、分组引用自动注入反射实现的双向绑定addAgent注册成功后基类会尝试把当前分组引用注入到 Agent 的 ControllerBaseGroup.javatry { var controller agent.getClass().getMethod(getController).invoke(agent); if (controller ! null) { var setGroupMethod controller.getClass().getMethod(setGroup, BaseGroup.class); setGroupMethod.invoke(controller, this); } } catch (NoSuchMethodException e) { // Controller doesnt have setGroup — thats fine }关键语义条件是若 Agent 暴露getController()且 Controller 暴露setGroup(BaseGroup)通过反射调用二者缺一都只静默跳过NoSuchMethodException被显式吞掉其他异常仅记录 debug 日志不会中断注册流程注入成功后Agent 的 Controller 便持有分组引用可在消息处理中感知所属分组上下文日志通过Loggers.MULTI_AGENT输出调试分组注入问题时可关注该日志器。六、运行配置 GroupConfig三个关键参数GroupConfig定义于 core/src/main/java/com/openjiuwen/core/multiagent/GroupConfig.java是分组如何运行的载体默认值与链式配置方法如下字段默认值setter链式方法说明maxAgents10setMaxAgents(int)configureMaxAgents(int)分组可容纳的最大 Agent 数量addAgent的上限校验即依赖此值maxConcurrentMessages100setMaxConcurrentMessages(int)configureConcurrency(int)最大并发消息数供子类执行时约束并发度messageTimeout30.0秒setMessageTimeout(double)configureTimeout(double)消息处理超时时间秒GroupConfig config new GroupConfig() .configureMaxAgents(2) .configureConcurrency(2) .configureTimeout(10.0);值得说明的是BaseGroup本身不直接消费maxConcurrentMessages与messageTimeout这两个参数由子类的执行逻辑如并发扇出、等待聚合读取使用。例如系统测试中的AggregatingGroup就在构造时通过configureConcurrency(2)指定并发度。七、执行入口invoke 与 stream 抽象方法BaseGroup将分组执行收敛为两个抽象方法BaseGroup.java由子类实现具体的编排策略public abstract Object invoke(Object message, AgentGroupSession session); public abstract IteratorObject stream(Object message, AgentGroupSession session);invoke同步执行入口接收消息对象或 Map返回分组聚合输出stream流式执行入口返回IteratorObject逐块产出结果两者的session参数为AgentGroupSession可传null由子类决定如何使用。AgentGroupSessioncore/src/main/java/com/openjiuwen/core/session/AgentGroupSession.java是分组级会话门面与AgentSession同属产品层提供AgentGroupSession.create(sessionId, envs)创建分组会话并注入环境变量getState(key)/updateState(...)读写会话状态writeStream(...)向分组流写入数据写入时会自动附带source_team_id/source_agent_id元数据createAgentSession(card, agentId)为成员 Agent 创建共享同一流写端的子会话。八、实战自定义分组完整示例系统测试 core/src/test/java/com/openjiuwen/core/systemtest/MultiAgentSystemTest.java 提供了BaseGroup最直接的子类实现范例展示同步聚合与流式扇出两种模式private static final class AggregatingGroup extends BaseGroup { private AggregatingGroup(GroupCard card, GroupConfig config) { super(card, config); } Override public Object invoke(Object message, AgentGroupSession session) { MapString, Object inputs normalizeInputs(message); String topic String.valueOf(session.getState(topic)); MapString, Object results new LinkedHashMap(); results.put(group_id, getGroupId()); results.put(topic, topic); for (Map.EntryString, BaseAgent entry : getAgents().entrySet()) { AgentSession agentSession new AgentSession(); results.put(entry.getKey(), entry.getValue().invoke(inputs, agentSession)); } return results; } Override public IteratorObject stream(Object message, AgentGroupSession session) { MapString, Object inputs normalizeInputs(message); ListObject items new ArrayList(); for (Map.EntryString, BaseAgent entry : getAgents().entrySet()) { AgentSession agentSession new AgentSession(); items.add(Map.of( agent_id, entry.getKey(), payload, entry.getValue().invoke(inputs, agentSession) )); } return items.iterator(); } }对应的组装与执行同文件 MultiAgentSystemTest.javaAggregatingGroup group new AggregatingGroup( GroupCard.builder() .id(uniqueId(group)) .name(uniqueId(group-name)) .description(multiagent system test group) .build(), new GroupConfig() .configureMaxAgents(2) .configureConcurrency(2) .configureTimeout(10.0) ); group.addAgent(new TemplateAgent(uniqueId(alpha), alpha), alpha); group.addAgent(new TemplateAgent(uniqueId(beta), beta), beta); AgentGroupSession session AgentGroupSession.create( trackSessionId(group-session), Map.of(topic, incident-response) ); MapString, Object result (MapString, Object) group.invoke( Map.of(query, hello group), session );测试断言同时验证了分组核心行为group.getAgentCount()返回 2group.getCard().getAgentCards().size()为 2印证注册即同步卡片group.listAgents()同时包含alpha、beta印证注册顺序稳定聚合结果中包含分组 ID、会话 topic 以及每个成员的输出alpha:hello group、beta:hello group印证invoke的聚合语义stream版本按成员逐个产出 chunk每个 chunk 携带agent_id与payload。九、新旧分组基类对比仓库中并存两套分组基类理解差异可避免误用维度新版BaseGrouplegacyBaseGroup源码位置core/src/main/java/com/openjiuwen/core/multiagent/BaseGroup.javacore/src/main/java/com/openjiuwen/core/multiagent/legacy/BaseGroup.java配置载体GroupCardGroupConfigAgentGroupConfig构造传入执行模型子类自行实现invoke/stream依托BaseGroupController消息队列路由MessageQueueInMemory 发布订阅控制器需实现handleEvent定位当前文档推荐模式Deprecated用于ControllerGroup向后兼容从源码看旧版控制器BaseGroupControllercore/src/main/java/com/openjiuwen/core/multiagent/legacy/BaseGroupController.java基于内存消息队列与GroupEvent路由实现异步编排新接入的分组建议优先采用本文所述的新版BaseGroup。十、最佳实践小结卡片先行GroupCard的id与name必填name会被固化为groupId命名时需保证全局可辨识配置前置maxAgents在addAgent阶段即生效规划分组容量时应先通过GroupConfig设定上限避免运行时注册失败链式搭建new MyGroup(card, config).addAgent(a).addAgent(b)的链式风格与框架设计一致聚合语义自定invoke/stream是抽象方法扇出、串行、并发、超时等编排策略完全由子类决定maxConcurrentMessages、messageTimeout仅为约定参数会话贯通分组级使用AgentGroupSession成员级使用createAgentSession生成的子会话可共享流端并自动附带团队/成员元数据。赞分享人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习【免费下载链接】agent-core-javaopenJiuwen agent core Java是 openJiuwen Core的 Java版本提供AI Agent开发、运行、调优与演进相关的全套SDK能力。项目地址https://gitcode.com/openJiuwen/agent-core-java点击查看免费下载相关推荐agent-core-java 多 Agent 分组编程指南BaseGroup 与 GroupConfig 的 Card Config 运行模型agent core java 多 Agent 分组编程指南BaseGroup 与 GroupConfig 的 Card Config 运行模型 本文围绕人工智能AI AgentAgent 框架工具调用Agent 工作流RAGMCP Clients强化学习DLSS版本随便换DLSS Swapper 从上手到 DLL 替换的进阶指南DLSS版本随便换DLSS Swapper 从上手到 DLL 替换的进阶指南 装好 DLSS Swapper 之后游戏里的 DLSS、FSR、XeSS DL桌面应用openJiuwen agent-core 组件级执行指南execute_single_component 详解与实战openJiuwen agent core 组件级执行指南execute_single_component 详解与实战 导读 execute_single_c人工智能AI AgentAgent 框架大模型工具调用RAG提示工程强化学习上一篇React-maskedinput性能优化指南提升大型表单渲染效率的5个方法下一篇Palettable完全解析为什么它是Python数据科学家的必备色彩库创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考