.. Copyright (c) 2025 Huawei Technologies Co., Ltd. All Rights Reserved.

介绍
===================

EvoFabric 的多智能体（Multi-Agent）模块提供用于构建“智能体协作图”的能力。该模块采用可扩展架构，当前包含 Swarm 组件（Swarm-style 的多智能体），后续将补充更多编排策略与组件。

什么是多智能体？
-------------------

多智能体系统通过一组各司其职的 Agent 协作完成复杂任务。每个 Agent 往往绑定特定能力（检索、规划、工具调用、代码执行、写作审校等），并在约定的拓扑与路由机制下进行“接力式”求解，以提升可控性、可观测性和鲁棒性。

为什么选择多智能体
---------------------------

- 将复杂任务拆解为多个专职 Agent（规划、检索、计算、工具调用、写作等），提升可靠性与可维护性
- 基于“handoff（移交）”范式，让 Agent 在任务中动态协作与接力
- 利用图结构控制执行流、避免无谓循环，并在需要时约束拓扑
- 分而治之与可维护性：把复杂任务拆解为稳定的子角色，单个 Agent 的提示与工具更聚焦、更易测试与演进。  
- 复用与扩展：不同团队可沉淀领域 Agent 并在更大工作流内复用，或按需增加/替换角色而不破坏主体流程。  

典型使用场景
----------------

- 检索增强与写作协作：检索 Agent、整合/评审 Agent、撰写 Agent 协作完成资料搜集与成稿。  
- 面向工具的任务编排：由“调度/规划”Agent 触发检索、数据库、搜索、代码执行等工具并路由子任务。  
- 客服/运营自动化：按照“分诊/路由 → 专家处理 → 质检/汇总”流程组织角色；在实时语音或多模态场景中可采用“顺序 handoff”接力。
- 研究与数据工作台：多 Agent 组聊协作完成信息搜集、对比、总结与可视化。
- 长流程与人审：在关键节点通过中断机制等待人审决定，再继续流程（批准/修改/拒绝）。



Swarm的优势
---------------------------

- 快速落地与低心智负担：API 简洁、约定优于配置，适合以“规划 + 专家 Agent”的模式在较少回合内完成任务。  
- 明确的接力语义：内置 handoff 工具使“把任务交给谁、携带什么信息”具备可见、可测与可控的接口。  
- 拓扑可约束：通过 ``edges`` 指定允许的移交边，既能 Star（集中调度）也能 All‑to‑All（探索验证）或 Pipeline（流水线）。  
- 易于集成：与 EvoFabric 的 AgentNode、ToolManager、ComponentFactory、Pydantic State 无缝衔接。  


Swarm 的关键构件与术语
-------------------------

以下术语既覆盖业界多智能体通用构件，也标注 Swarm 的特有点，便于迁移理解：

- Agent（智能体）  
  绑定聊天模型、系统提示与工具集合的节点。Swarm 中使用 ``AgentNode`` 表示。

- Tool/Function（工具调用）  
  Agent 通过工具与外部世界交互，如检索、天气查询、时间查询、数据库操作等。  

- Handoff（移交，Swarm 特有重点）  
  由当前 Agent 主动“把任务接力给目标 Agent”，并携带上下文或需求说明。Swarm 会为每个 Agent 注入定制化的 ``handoff`` 工具，其可选目标由 ``edges`` 或“全连接（默认）”自动生成。

- Router/Planner（路由/规划）  
  用于决定下一步交给谁。常见模式包括：集中式 Planner（Star）、条件路由（基于消息/工具调用）、以及有限状态机/层级调度。

- Graph/Edges（图与边）  
  以“节点+有向边”控制可达路径与条件分支。Swarm 通过 ``edges`` 生成允许的 handoff 目标集合，并在运行时打印路由日志以便调试。

- State/Memory（状态/记忆）  
  Swarm 运行图需要 Pydantic 状态模型，至少包含 ``messages: List[StateMessage]``

- Termination（终止条件）  
  Swarm 默认在检测到回复中包含 ``"FINISHED"`` 时终止；也可通过 ``termination_pattern`` 自定义为 ``"END"`` 等。