[Feature] 支持多agent

[DurantChan1]

MaxKB Version

v2.9.2 (build at 2026-05-19T18:09, commit: 566fd31)

Please describe your needs or suggestions for improvements

当前架构为单智能体模式，每个工作流（Workflow DAG）中只有一个 AI Chat 节点作为智能体运行。虽然工作流引擎支持 DAG 编排（条件分支、循环、并行执行），但没有智能体之间的协作、委托、并行能力。本计划在不修改核心工作流引擎的前提下，增量式添加 multi-agent 支持，使 MaxKB 能够支持 Supervisor/Orchestrator、Agent Team、Agent-as-Tool 三种多智能体模式。

Please describe the solution you suggest

见附件

Additional Information

Multi-Agent 支持实施方案

Context

MaxKB v2.0.0 当前架构为单智能体模式，每个工作流（Workflow DAG）中只有一个 AI Chat 节点作为智能体运行。虽然工作流引擎支持 DAG 编排（条件分支、循环、并行执行），但没有智能体之间的协作、委托、并行能力。本计划在不修改核心工作流引擎的前提下，增量式添加 multi-agent 支持，使 MaxKB 能够支持 Supervisor/Orchestrator、Agent Team、Agent-as-Tool 三种多智能体模式。

框架选择：LangGraph

经过主流 MAS 框架调研（CrewAI、AutoGen/MAF、OpenAI Agents SDK、PydanticAI、Agno、CAMEL、smolagents、Ray），选定 LangGraph 作为实现引擎，原因：

因素	结论
已有集成	MaxKB 已在 tools.py 中导入 langgraph.checkpoint.memory.MemorySaver，LangChain 1.2 广泛使用
架构匹配	LangGraph StateGraph 与 WorkflowManage DAG 天然互补 — StateGraph 在节点内部工作，不替换外层 DAG
Token 效率	基准测试最低成本 (~$12-18/1K 任务)，CrewAI 3x 开销不适合生产
错误恢复	90% 错误恢复率 vs CrewAI 0%
状态管理	Postgres Checkpointer 与 MaxKB 的 PostgreSQL 完美配合
模型支持	100+ 供应商，与现有 models_provider/ 兼容
许可证	MIT，兼容 GPL v3

关键原则：LangGraph 作为节点内部的实现引擎（内层），外层依然是 WorkflowManage DAG，不做架构重构。

---

架构概览

三种新模式映射为三个新节点类型，均构建在已有基础设施之上：

LangGraph 集成方式

LangGraph 作为节点内部引擎，而非替换 WorkflowManage：

WorkflowManage (外层 DAG，现有不变)
  ├── ai-chat-node        → ChatSerializers（不变）
  ├── agent-call-node     → ChatSerializers.chat()（直接调用 AgentProfile）
  ├── agent-supervisor-node → LangGraph StateGraph（内层多智能体编排）
  │     ├── supervisor     → LangGraph Supervisor Agent
  │     ├── sub-agent-1   → LangGraph Node (AgentProfile)
  │     └── sub-agent-2   → LangGraph Node (AgentProfile)
  └── agent-team-node     → LangGraph Send()（并行 fan-out）+ 汇总

全部复用的现有能力：

• LangGraph 已有集成 → MemorySaver 已导入，确认版本兼容即可
• ChatSerializers.chat() → 子智能体执行（与 application_node 相同模式）
• WorkflowManage ThreadPool → 整体 DAG 并行
• MCP Tool 协议 → supervisor 节点中 LangGraph Agent 通过 MCP 调用外部工具
• workflow 节点注册机制 → 新节点类型注册

---

新增数据模型

AgentProfile — 可复用智能体定义

新增文件：apps/application/models/agent_profile.py

核心字段：

• id, workspace_id, name, desc
• system_prompt — 智能体系统提示词
• model_id, model_params_setting, model_setting — 模型配置
• dialogue_number, dialogue_type — 对话上下文
• knowledge_setting — RAG 知识库配置
• tool_ids, mcp_tool_ids, mcp_servers — 工具配置
• application_ids — 可调用的子应用
• agent_ids — 可委托的子智能体（用于 supervisor 模式）
• collaboration_mode — 'supervisor' | 'team' | 'tool'
• delegation_prompt — 委托提示词

API 端点：/api/application/agent_profile/ (标准 CRUD ViewSet)

---

新增后端节点类型

1. agent-call-node (Agent-as-Tool)

用途：在工作流中内联调用一个 AgentProfile，类似 application_node 但使用 AgentProfile 配置而非已发布应用。

实现文件：

• apps/application/flow/step_node/agent_call_node/i_agent_call_node.py
• apps/application/flow/step_node/agent_call_node/impl/base_agent_call_node.py

执行逻辑：BaseAgentCallNode.execute() ≈ BaseApplicationNode.execute() — 解析 AgentProfile 配置 → 通过 ChatSerializers.chat() 执行 → 返回结果

2. agent-supervisor-node (Orchestrator/Supervisor)

用途：运行一个 Supervisor LLM，将子智能体注册为 MCP Tool，由 Supervisor 自主决定委托策略、汇总结果。

实现文件：

• apps/application/flow/step_node/agent_supervisor_node/i_supervisor_node.py
• apps/application/flow/step_node/agent_supervisor_node/impl/base_supervisor_node.py
• apps/application/flow/tools.py — 新增 get_agent_tools()

执行逻辑（内部使用 LangGraph StateGraph）：

1. 解析子智能体列表（AgentProfile 或内联配置）
2. 构建 LangGraph StateGraph：
   • 定义 AgentState (TypedDict：query, results, final_answer)
   • supervisor 节点 → LangGraph 内置 SupervisorAgent，收到系统提示词描述可用子智能体
   • 每个子智能体注册为一个 LangGraph Node（内部调用 ChatSerializers.chat()）
   • 边：supervisor → 条件路由到子智能体 → 返回 supervisor → 循环直到完成
3. 使用 Postgres Checkpointer 持久化中间状态
4. 支持流式输出各子智能体的中间结果

配置项：

• sub_agent_configs — 子智能体列表（{name, agent_profile_id, description}）
• aggregation_strategy — 'last' | 'summarize' | 'concatenate'
• max_turns — 最大委托轮次

实现文件：

• apps/application/flow/step_node/agent_supervisor_node/i_supervisor_node.py
• apps/application/flow/step_node/agent_supervisor_node/impl/base_supervisor_node.py
• apps/application/flow/tools.py — 新增 build_langgraph_supervisor() 工具函数

3. agent-team-node (Parallel Agent Team)

用途：并行执行多个智能体，然后汇总结果。

实现文件：

• apps/application/flow/step_node/agent_team_node/i_agent_team_node.py
• apps/application/flow/step_node/agent_team_node/impl/base_agent_team_node.py

执行逻辑（使用 LangGraph Send() + parallel API）：

1. 解析所有成员智能体配置
2. 构建 LangGraph StateGraph，使用 Send() 进行并行 fan-out：

   for member in members:
       edges.append(Send("run_agent", {"member": member, "input": input_text}))

3. 各成员并行执行（各自调用 ChatSerializers.chat()）
4. 汇总节点根据 aggregation_strategy 处理结果：
   • 'concatenate' — 直接拼接
   • 'vote' — 调用 LLM 选择最佳
   • 'summarize' — 调用 LLM 综合
5. 使用 Checkpointer 支持在并行分支失败时单独重试

配置项：

• members — 团队成员列表
• input_source — 输入来源
• aggregation_strategy — 汇总策略

---

前端变更

新节点注册

每个节点遵循现有模式：

1. ui/src/workflow/nodes/{node-type}/index.ts — 注册图形节点
2. ui/src/workflow/nodes/{node-type}/index.vue — 配置面板
3. ui/src/workflow/icons/{node-type}-icon.vue — 图标
4. ui/src/workflow/common/data.ts — 添加到 nodeDict 和菜单分组

Agent Profile 管理页面

• 新路由：ui/src/views/application/agent-profile/
• 列表/编辑页面，包含系统提示词、模型选择、工具/知识库选择、子智能体配置

Workflow 编辑器集成

• 新增节点类型添加到 menuNodes 的 "多智能体" 分组
• agent-call-node 的选择器改为加载 AgentProfile

---

分阶段实施

Phase 1: 基础 ✅ (已完成)

• AgentProfile 模型 + CRUD API
• agent-call-node 后端（接口 + 实现）
• agent-call-node 前端（节点 UI + API + i18n + data.ts 注册）
• 管理 UI 页面（独立 AgentProfile 管理页面）
• 价值：用户可以定义可复用的智能体配置并在工作流中调用

Phase 1 已创建/修改文件清单：

后端新建：

• apps/application/models/agent_profile.py — AgentProfile 数据模型
• apps/application/api/agent_profile_api.py — API 定义
• apps/application/serializers/agent_profile_serializer.py — 序列化/CRUD 逻辑
• apps/application/views/agent_profile_view.py — REST 视图
• apps/application/flow/step_node/agent_call_node/i_agent_call_node.py — 节点接口
• apps/application/flow/step_node/agent_call_node/impl/base_agent_call_node.py — 节点实现

后端修改：

• apps/application/models/__init__.py — 导出 AgentProfile
• apps/application/views/__init__.py — 导出视图
• apps/application/urls.py — 添加路由
• apps/application/flow/step_node/__init__.py — 注册新节点类型

前端新建：

• ui/src/api/agent-profile.ts — API 模块
• ui/src/workflow/nodes/agent-call-node/index.ts — 节点注册
• ui/src/workflow/nodes/agent-call-node/index.vue — 节点 UI 组件
• ui/src/workflow/icons/agent-call-node-icon.vue — 节点图标

前端修改：

• ui/src/enums/application.ts — 添加 AgentCall = 'agent-call-node'
• ui/src/workflow/common/data.ts — 添加节点定义 + nodeDict + 菜单
• ui/src/locales/lang/zh-CN/workflow.ts — 中文 i18n
• ui/src/locales/lang/en-US/workflow.ts — 英文 i18n
• ui/src/locales/lang/zh-Hant/workflow.ts — 繁体 i18n

Phase 2: Supervisor 模式

• agent-supervisor-node 后端 + 前端
• tools.py 新增 get_agent_tools()
• Resource mapping 扩展
• 价值：Orchestrator/Supervisor 多智能体工作流

Phase 3: Team 模式

• agent-team-node 后端 + 前端
• 聚合策略实现
• 价值：并行多智能体 + 结果汇总

Phase 4: 深度集成（可选）

• MULTI_AGENT 应用类型
• 专用编辑器视图
• 直接函数调用（绕过 MCP 开销）
• 高级模式：层级智能体、Handoff 机制

---

验证方案

1. 单元测试：每个新节点类型的序列化/反序列化、执行逻辑
2. 集成测试：端到端 multi-agent 工作流执行、MCP 通信、流式响应
3. 回归测试：已有工作流不受影响
4. 前端测试：节点 UI 配置/保存/重载
5. 边界情况：循环引用验证、超时处理、资源竞争

---

关键参考文件

优先级	文件	作用
P0	apps/application/flow/step_node/application_node/impl/base_application_node.py	子工作流调用模式 — agent-call-node 直接复用
P0	apps/application/flow/step_node/ai_chat_step_node/impl/base_chat_node.py	MCP Tool 构建 + LLM 执行 — supervisor node 扩展此模式
P0	apps/application/flow/tools.py	MCP 客户端、DeepAgent、工具注册 — 新增 get_agent_tools()
P0	apps/application/flow/step_node/__init__.py	节点工厂 — 注册新类型
P1	apps/application/flow/workflow_manage.py	核心工作流引擎 — 理解并行执行
P1	ui/src/workflow/common/data.ts	前端节点注册
P2	apps/application/models/application.py	ApplicationTypeChoices 枚举

---

多智能体数据流示例

Supervisor → Researcher → Writer 流程

用户: "写一份量子计算报告"
  → agent-supervisor-node
    → Supervisor LLM 收到提示词: 可用工具包括 researcher, writer
    → 调用 researcher("研究量子计算")  → MCP Tool → 执行 AgentProfile X (含搜索工具)
    → 收到研究结果
    → 调用 writer(研究结果)  → MCP Tool → 执行 AgentProfile Y (含写作提示词)
    → 收到报告
  → 返回最终报告

Agent Team 并行辩论

用户: "最佳 ML 云服务商是？"
  → agent-team-node
    → 并行: CloudExpert + CostAnalyst + MLArchitect
    → 各自独立回答
    → Aggregator LLM 综合三个回答
  → 返回综合答案