JiuwenSwarm 基于 openJiuwen 框架实现了多 Agent 协作机制Leader 负责任务调度Teammate 负责并行执行技能可继承任务全程可监控。本文深入解析这套机制的设计思路与核心实现。一、为什么需要多 Agent用 AI Agent 处理简单任务体验通常不错。但当任务的复杂度上来之后单智能体架构的短板就会暴露得比较明显。一个典型场景是长链条任务。假设你需要 AI 整理本月所有发票提取关键信息汇总成 Excel再发一封邮件通知——这涉及数据提取、格式转换、文件操作、邮件发送等多个环节单 Agent 只能串行处理中间任何一步出错后续流程就可能中断。如果用户在执行过程中又追加了新需求线性执行模式也很难灵活应对。多领域复合任务同样棘手。一个 Agent 同时要操作浏览器、编写代码、管理文件时上下文膨胀和注意力分散几乎不可避免。说到底单个 Agent 的注意力、专业度、并发能力都有明确的天花板。JiuwenSwarm 的做法是让 Agent 组队。通过内置的 Swarm Agent 机制一个 Leader Agent 可以动态创建多个 Teammate Agent各司其职、协同完成复杂任务。这套机制与 JiuwenSwarm 已有的技能自演进、记忆系统、任务规划等能力是打通的不是孤立的模块。运行环境项目配置值操作系统Windows 10 / macOS / LinuxPython3.11 / 3.12 / 3.13模型服务华为云 MaaS / OpenAI 兼容接口 / ModelScope 等通信渠道Web / 飞书 / 钉钉 / 企业微信 / 小艺 / Telegram / Discord / WhatsApp / 个人微信Agent 框架openJiuwen内置JiuwenSwarm 与 Swarm AgentopenJiuwen 是一个开源的 Agent 开发框架JiuwenSwarm 是基于该框架构建的智能助手。框架本身提供了模块化技能系统、多智能体协作、技能自演进、记忆与上下文管理、多渠道接入等能力。Swarm Agent 在此基础上做了几个关键增强任务并行Leader 调度 多 Teammate 并行执行替代单 Agent 的串行模式技能继承按角色选择性继承或全量继承主 Agent 的技能不必重复配置动态扩容Leader 可按需创建 Teammate不需要预先定义所有成员全程可观测12 种事件类型覆盖成员创建、任务进度、成员间消息等关键节点追加交互用户可以随时注入新指令不打断正在执行的任务细粒度权限按成员、按 Channel 控制工具权限架构总览核心组件分工组件职责源码位置TeamManager团队生命周期管理创建/销毁/会话隔离agentserver/team/team_manager.pyConfigLoader从 config.yaml 加载团队配置并构建规格agentserver/team/config_loader.pyTeamAgentSpec团队规格定义角色/技能/生命周期openjiuwen agent_teams.schemaTeamAgent运行时团队实例Leader Teammateopenjiuwen agent_teams.agentTeamMonitorHandler实时事件监控成员/任务/消息agentserver/team/monitor_handler.pyagent_customizer成员初始化定制能力继承/技能复制/工具注册team_manager.py内嵌SignalDetector技能演进信号检测openjiuwen agent_evolvingTeamHelpers流式协作多请求并发/事件广播agentserver/deep_agent/team_helpers.py消息从用户到团队的数据流二、核心组件实现2.1 TeamManager团队生命周期管理TeamManager负责团队的创建、销毁、会话隔离和并发控制。它的核心数据结构很直观class TeamManager: def __init__(self): self._team_agents: dict[str, TeamAgent] {} # session_id → TeamAgent self._team_monitors: dict[str, TeamMonitorHandler] {} # session_id → monitor self._stream_tasks: dict[str, asyncio.Task] {} # session_id → asyncio.Task self._lock asyncio.Lock()三个字典分别管理团队实例、监控器和后台流式任务用session_id做键。_lock保证同一 Channel 下不会出现两个 Team 同时创建的竞态条件。对外暴露的核心方法是get_or_create_team()实现了懒加载复用已有 Team 就复用没有就新建。新建时会自动清理同 Channel 下其他会话的残留实例async def get_or_create_team(self, session_id, deep_agent, ...) - TeamAgent: async with self._lock: team_agent self._team_agents.get(session_id) if team_agent is not None: return team_agent await self._destroy_other_sessions(session_id) return await self.create_team(session_id, deep_agent, ...)值得一提的是TeamManager是按channel_id隔离的。每个 Channel飞书、Web、钉钉等拥有独立的TeamManager实例通过全局注册表get_team_manager(channel_id)获取_team_managers: dict[str, TeamManager] {} def get_team_manager(channel_id: str | None None) - TeamManager: resolved_channel_id str(channel_id or default).strip() or default manager _team_managers.get(resolved_channel_id) if manager is None: manager TeamManager() _team_managers[resolved_channel_id] manager return manager这是最近一次重构commit1380032中加入的解决了多 Channel 同时使用 Team 模式时的冲突问题。2.2 ConfigLoader团队配置加载创建 Team 之前系统需要知道团队的结构。config_loader.py从config.yaml的team段加载配置构建TeamAgentSpec兼容的字典几个关键的配置项配置项说明默认值team_name团队名称teamlifecycle生命周期模式persistentteammate_modeTeammate 构建模式build_mode按需创建spawn_mode进程模式inprocess进程内leader.member_nameLeader 名称team_leaderleader.personaLeader 人设天才项目管理专家擅长任务分解和团队协调agents.role.skills角色技能列表继承全部全局技能每个 Agent 成员默认继承主 Agent 的模型配置确保团队内使用一致的 LLM 后端def _build_default_model_dict(config_base): model_config config_base.get(models, {}).get(default, {}) model_client_config model_config.get(model_client_config, {}) model_request_config dict(model_config.get(model_config_obj, {})) return { model_client_config: model_client_config, model_request_config: model_request_config, }2.3 技能继承机制这是 Swarm Agent 设计中比较精巧的部分。新的 Teammate 创建时不是从零开始而是通过agent_customizer自动继承主 Agent 的技能和工具。继承流程分几步走技能继承支持两种模式。如果成员在配置中指定了skills列表只复制指定的技能否则继承全部def copy_member_skills(member_skills_dir, *, skills_configured, selected_skills): selected_skill_set set(selected_skills) for skill_dir in global_skills_dir.iterdir(): if not skill_dir.is_dir() or not (skill_dir / SKILL.md).is_file(): continue if skills_configured and skill_dir.name not in selected_skill_set: continue dest member_skills_dir / skill_dir.name if not dest.exists(): shutil.copytree(skill_dir, dest)能力卡的继承也是自动的。主 Agent 的工具能力卡中标记为可继承的会被添加到新成员inheritable_cards filter_inheritable_ability_cards(deep_agent) existing_ability_ids {card.id for card in agent.ability_manager.list() or []} for card in inheritable_cards: if card.id not in existing_ability_ids: agent.ability_manager.add(card)实际效果是给主 Agent 安装了Excel 处理网页搜索邮件发送三个技能后新创建的 Teammate 会自动拥有这些能力。2.4 动态团队构建模式Swarm Agent 支持两种团队构建模式可以组合使用。build_mode按需构建是默认模式。Teammate 不是预先创建的而是 Leader 分析任务后根据需要动态拉起。比如用户说帮我分析这份数据并写份报告Leader 可能先创建一个数据分析的 Teammate 处理数据再创建一个写作 Teammate 生成报告。适合任务类型不固定的场景。predefined_members预定义成员在配置中预先定义好团队成员团队创建时这些成员就已就位team: predefined_members: - member_name: data_analyst display_name: 数据分析师 persona: 擅长数据分析和报表生成 - member_name: code_writer display_name: 代码编写员 persona: 擅长编写和调试代码适合工作流程固定、角色分工明确的场景。配置加载时会校验member_name必填缺失的成员会被跳过。2.5 实时事件监控机制多智能体系统中了解谁在做什么、任务到了哪一步很重要。JiuwenSwarm 通过TeamMonitorHandler实现了实时事件监控。监控的运作方式event_types.py中定义了 12 种事件类型分三类成员事件team.member事件类型说明MEMBER_SPAWNED新成员被创建MEMBER_STATUS_CHANGED成员状态变更MEMBER_EXECUTION_CHANGED成员执行状态变更MEMBER_RESTARTED成员被重启MEMBER_SHUTDOWN成员被关闭任务事件team.task事件类型说明TASK_CREATED新任务被创建TASK_CLAIMED任务被某个成员认领TASK_COMPLETED任务完成TASK_CANCELLED任务被取消TASK_UNBLOCKED任务解除阻塞消息事件team.message事件类型说明MESSAGE_P2P成员间点对点消息MESSAGE_BROADCAST广播消息这些事件经过_convert_event_to_dict()转换后通过_broadcast_event()分发到所有等待的请求队列前端可以实时展示团队运行状态。2.6 流式协作与追加交互机制Swarm Agent 的交互采用流式模式团队的进展以事件流的形式实时推送给用户。更重要的是用户可以在团队执行过程中追加新指令。流程大致是这样的代码层面的判断很直接——检查该 session 是否已有流式任务在跑async def process_team_message_stream(request, inputs, deep_agent): if is_first_request: team_agent await team_manager.get_or_create_team(...) monitor_handler TeamMonitorHandler(team_agent, session_id) await monitor_handler.start() stream_task asyncio.create_task( _consume_stream_with_query(channel_id, session_id, team_agent, query) ) else: await team_manager.interact(session_id, query)2.7 与已有能力的融合Swarm Agent 不是孤立的模块它和 JiuwenSwarm 的核心能力是打通的技能自演进Teammate 执行技能出错时SignalDetector捕获信号改进建议写入演进记录下次调用自动加载记忆系统Team 成员可读取主 Agent 的MEMORY.md、USER.md等记忆文件保持对用户偏好的感知定时任务通过CronRuntimeBridgeTeam 成员也可以注册 Cron Tools在协作中执行定时操作文件发送Teammate 完成文件处理后通过SendFileToolkit将结果直接发送到用户所在的通信渠道工具权限控制通过owner_scopes按 Channel 用户维度控制工具权限allow/deny/ask未配置的操作自动拒绝上下文压缩长对话中的冗余信息自动压缩保持 Team 成员的上下文精简浏览器工具Teammate 可操控真实浏览器完成网页任务按session_id复用浏览器会话三、配置与部署3.1 团队配置在~/.jiuwenclaw/config/config.yaml中添加team配置段即可启用 Swarm Agent 模式。最小可用配置team: team_name: my_team lifecycle: persistent teammate_mode: build_mode spawn_mode: inprocess这样配置后Leader 和 Teammate 使用默认角色Teammate 按需动态创建继承全部技能。进阶配置示例team: team_name: project_team lifecycle: persistent teammate_mode: build_mode spawn_mode: inprocess leader: member_name: project_manager display_name: 项目经理 persona: 擅长任务分解和项目管理的专家 agents: leader: skills: [openJiuwen-DeepSearch, advanced-daily-report] # Leader 的技能 teammate: {} # Teammate 继承全部技能 predefined_members: - member_name: data_analyst display_name: 数据分析师 persona: 擅长数据清洗、统计分析和可视化 - member_name: doc_writer display_name: 文档编写员 persona: 擅长技术文档、报告和公文撰写数据存储配置可选不配置时默认使用~/.jiuwenclaw/agent/team.dbteam: storage: type: sqlite params: connection_string: team.db # 相对于 agent_teams_home3.2 模型配置Swarm Agent 的模型配置继承自主 Agent在config.yaml的models段配置models: default: model_client_config: model_name: qwen-plus client_provider: openai model_config_obj: model: qwen-plus temperature: 0.73.3 Channel 配置Swarm Agent 可以在任何已配置的 Channel 上使用无需额外配置。以飞书为例channels: feishu: app_id: cli_xxxxx app_secret: xxxxx enabled: true在数字分身模式下工具权限的配置示例permissions: owner_scopes: feishu: ou_xxxx: defaults: *: allow tools: bash: *: deny patterns: git status *: allow git log *: allow write: *: deny deny_guidance_message: 该工具未被授权在数字分身模式下使用。3.4 启动服务pip install jiuwenclaw jiuwenclaw-init # 首次初始化 jiuwenclaw-start # 启动服务服务启动后AgentServer 会自动注册TeamManager当检测到team配置时启用 Swarm Agent 模式。四、实操演示多方向并行调研用一个实际场景走一遍完整流程用户要求对 AI Agent 的多个方向同时展开深度调研。4.1 场景说明用户在 Web 前端发送帮我全面调研一下 AI Agent 的最新进展我需要了解三个方向1主流 Agent 框架的设计对比LangGraph vs CrewAI vs AutoGen2Agent 通信协议的现状MCP、A2A、ACP3Agent 在企业场景中的落地案例。每个方向生成一份独立的 Markdown 报告保存到工作目录。这个场景适合 Swarm Agent 的原因很简单三个方向互相独立信息源不同可以并行处理。单 Agent 串行处理大约需要 45 分钟每个方向约 15 分钟而且随着信息累积上下文膨胀会影响后面的调研质量。Swarm Agent 的做法是拆出 3 个 Teammate 各负责一个方向同时启动 DeepSearch理论上 15 分钟即可全部完成。用到的都是 JiuwenSwarm 内置能力openJiuwen-DeepSearch技能负责深度搜索内置文件工具负责保存报告TeamMonitorHandler负责实时监控。4.2 步骤一启动服务pip install jiuwenclaw jiuwenclaw-init # 首次初始化 jiuwenclaw-start # 启动服务all 模式包含 app 后端 Web 前端服务启动后浏览器打开http://localhost:5173进入 Web 前端界面。4.3 步骤二切换到集群模式在聊天输入框底部的工具栏中找到左侧的模式切换按钮组三个并排的按钮从左到右依次为按钮模式说明规划模式agent.plan主动记忆 任务规划⚙️智能执行agent.fast基础 Agent适合日常对话集群模式team多 Agent 团队协作点击最右侧的集群模式按钮图标为多人头像将模式切换为 Swarm Agent 模式。如果当前会话没有历史消息会立即切换。如果已有历史消息会弹出确认弹窗提示切换模式将创建新会话点击确认即可。切换成功后输入框底部的模式按钮高亮状态会移到集群模式上。4.4 步骤三发送调研任务在聊天输入框中输入调研任务帮我全面调研一下 AI Agent 的最新进展我需要了解三个方向 1主流 Agent 框架的设计对比LangGraph vs CrewAI vs AutoGen 2Agent 通信协议的现状MCP、A2A、ACP 3Agent 在企业场景中的落地案例 每个方向生成一份独立的 Markdown 报告保存到工作目录。按Enter或点击输入框右侧的发送按钮向上箭头图标发送消息。4.5 步骤四观察团队运行消息发送后系统进入 Swarm Agent 模式。在聊天区域右侧会显示团队面板包含两个区域团队成员面板TeamArea显示团队中所有成员的列表每个成员前有一个状态圆点颜色含义 绿色就绪ready 黄色忙碌busy 蓝色重启中restarting 橙色关闭请求中shutdown_requested⚪ 灰色已关闭shut_down 红色错误error如果成员正在执行任务会显示**执行中: xxx**的任务描述每个成员右侧显示状态更新时间初始状态可以看到 Leaderteam_leader被创建。随后 Leader 分析任务动态创建 3 个 Teammate如framework_researcher、protocol_researcher、enterprise_researcher成员列表会实时更新。任务事件面板TeamTaskEvents显示团队任务的实时事件日志每条事件包含任务 ID、事件类型如created、claimed、completed、时间戳随着调研推进可以看到任务被创建 → 被成员认领 → 执行中 → 完成的完整生命周期4.6 步骤五追加新方向调研进行到第 5 分钟左右可以在输入框中直接追加减指令再帮我加一个方向Agent 的安全与对齐问题也调研一下。在集群模式下直接在输入框输入并发送即可。消息会通过追加交互路径注入正在运行的 TeamAgentLeader 收到后动态创建新的 Teammate 处理不影响其他正在执行的成员。此时观察团队成员面板可以看到第 4 个成员被创建并开始执行。可以看到team-leader会实时监控成员的运行状态给出及时的提醒并且会实时给我们汇报进度4.7 步骤六查看结果调研完成后聊天区域Leader 会汇总所有调研结果展示最终输出团队成员面板所有成员状态变为 就绪随后变为 ⚪ 已关闭工作目录报告文件已保存工作目录中最终生成的文件workspace/session/sess_research/ ├── Agent框架对比分析.md # LangGraph vs CrewAI vs AutoGen ├── Agent通信协议技术对比.md # MCP / A2A / ACP ├── Agent企业落地案例.md # 企业应用实践 ├── Agent安全与对齐.md # 追加的安全方向 └── todo.md # 任务进度记录查看工作目录中的文件。4.8 效果对比与单 Agent 相比核心差异在于维度单 AgentSwarm Agent处理方式串行处理 4 个方向并行处理31 个 Teammate 同时工作耗时约 60 分钟约 20 分钟上下文质量信息累积导致膨胀后期质量下降每个 Teammate 上下文独立质量稳定追加需求需排队等待当前任务完成立即创建新 Teammate 处理五、写在最后Swarm Agent 当前还有一些值得探索的方向。部署层面现在spawn_mode: inprocess意味着 Teammate 和 Leader 跑在同一进程里。如果未来能扩展到独立进程或远程节点让 Teammate 在专用 GPU 服务器上执行算力上限会提高不少。互联互通层面JiuwenSwarm 已经实现了 A2A ingress channeljiuwenclaw/channel/a2a_channel.py可以通过 A2A 协议与其他 Agent 系统对接。使用体验层面一个可视化的团队编排界面——拖拽配置角色和技能——会进一步降低上手门槛。回顾这套设计JiuwenSwarm 的 Swarm Agent 没有从零发明一套复杂的多 Agent 框架而是在 openJiuwen 的基础上把技能、记忆、演进等已有能力自然地扩展到多 Agent 场景。几个设计决策值得一提渐进式能力继承让 Teammate 上岗成本很低不需要逐个配置动态 静态两种构建模式覆盖了不同场景12 种事件的全链路监控让系统变得可观测流式协作与追加交互打破了提交后只能等待的模式用户可以随时介入。总的来说这是一套实用导向的多智能体协作方案——重心放在如何让现有能力在多 Agent 场景下顺畅运转而不是追求架构上的花哨。参考资料https://atomgit.com/openJiuwen?utm_sourcecsdnhttps://www.openjiuwen.com?utm_sourcecsdn