MASFactory

简体中文

English

简体中文

English

Appearance

核心概念 ​

本节介绍 MASFactory 的核心概念：节点、边、图、工作流、节点变量、消息流和控制流。

系统架构概览 ​

MASFactory 系统架构概览

节点 ​

节点（Node）是 MASFactory 中的基本计算单元，是构成工作流的核心要素。所有在 MASFactory 图中执行计算的组件都是节点的派生类。

节点的执行机制 ​

当一个节点被执行时，将运行以下步骤：

  1. 就绪检查：检查所有入边是否已有消息且闸门打开
  2. 消息聚合：将所有入边的消息聚合为统一输入
  3. 计算处理：调用 _forward 方法执行核心计算逻辑
  4. 消息分发：将计算结果通过所有出边发送给下游节点
  5. 状态更新：更新节点和边的状态，为下一轮执行做准备

节点的派生类

节点的派生类主要是对节点的计算处理逻辑也就是_forward函数进行了重载，少数组件（如Switch组件）也重载消息聚合函数和消息分发函数。

节点类型 ​

MASFactory 提供了多种节点类型：

  • Agent 节点：封装大语言模型的智能体节点，支持工具调用和记忆机制
  • Graph 节点：子图节点，可以嵌套其他节点形成复杂的工作流结构
  • Switch 节点：条件分支节点，根据逻辑或语义判断选择执行路径
  • CustomNode：自定义节点，允许用户通过回调函数定义特定的计算逻辑

边 ​

边（Edge）连接两个节点，负责流程控制和消息传递。

边的主要功能 ​

  • 流程控制：定义节点之间的执行顺序和依赖关系
  • 消息传递：处理上游节点的输出并传递给下游节点
  • 数据过滤：通过 keys 参数指定需要传递的特定字段
  • 格式转换：使用 MessageFormatter 对消息进行格式化处理

边的组成 ​

  • 发送节点（sender）：消息的来源节点
  • 接收节点（receiver）：消息的目标节点
  • 键映射（keys）：定义需要传递的字段及其自然语言描述
  • 消息格式化（formatter）：处理消息格式转换

图 与 工作流 ​

图（Graph）是节点和边的集合，是由节点和边组成的有向无环图（Loop中的Controller环路除外），提供了工作流的组织和管理能力。图本身也是节点的一种，支持嵌套和复用。

图的类型 ​

  • RootGraph：顶层可执行图，是工作流的入口点，可以被用户直接实例化和调用
  • Graph：子图节点，可以嵌套在其他图中，提供模块化的工作流组织
  • Loop：循环图，提供迭代控制和循环终止判断功能

图的主要功能 ​

  • 节点管理：通过 create_node 方法创建和管理图中的节点
  • 边管理：通过 create_edge 系列方法创建节点间的连接关系
  • 完整性检查：确保图结构的正确性，包括环路检测、孤立节点检查等
  • 执行控制：管理图内节点的执行顺序和消息传递

图的约束条件 ​

为确保图的正确执行，需要满足以下约束：

  1. 图中不能有孤立节点（入度或出度为 0 的节点）
  2. 不能出现环路结构（如需循环，应使用 Loop 组件）
  3. 图上的边所连接的两个节点必须都是这个图内部的节点
  4. 入口和出口连接必须使用专用的边创建接口

工作流 ​

工作流（Workflow）是使用RootGraph图实现的一整套多智能体编排工作流程。
子工作流是使用Graph或Loop等子图组件实现的局部多智能体编排工作流程。

生命周期 ​

MASFactory 工作流的生命周期包括编排、构建、执行三个主要阶段。

编排阶段（Orchestration Phase） ​

在这个阶段，运行用户编写的构图代码来创建工作流的结构：

  1. 图创建：实例化 Graph 或 RootGraph 对象
  2. 节点定义：使用 create_node 方法创建各类节点
  3. 边连接：使用 create_edge 系列方法建立节点间的连接关系
  4. 结构组织：定义图的层次结构和嵌套关系

构建阶段（Build Phase） ​

在这个阶段，系统调用 build() 函数完成整图的预设配置。

执行阶段（Execution Phase） ​

在调用 invoke() 后，智能体工作流开始执行，采用基于就绪状态的调度机制：

  1. 就绪检查：持续扫描所有节点的就绪状态
  2. 节点执行：按就绪顺序执行节点的计算逻辑
  3. 消息传递：将计算结果传递给下游节点
  4. 状态更新：更新节点和边的状态信息
  5. 终止判断：检查是否满足工作流终止条件

节点变量 ​

节点变量（Node Attributes）是 MASFactory 中的共享状态机制，允许节点间共享和传递状态信息。节点变量采用分层设计，支持从上层环境继承变量，并可以将计算结果回写到上层和本层的环境中。

节点变量的管理机制 ​

节点变量是统一的状态管理机制，每个节点都有自己的 _attributes_store 来存储变量：

  • 变量存储：每个节点维护独立的 _attributes_store 变量存储空间
  • 变量传递：母图（上层环境）的变量会传递给子节点，形成嵌套的变量作用域
  • 变量继承：子节点可以通过 pull_keys 从上层环境获取需要的变量
  • 变量回写：节点可以通过 push_keys 将计算结果更新到本地和上层变量存储空间

变量控制机制 ​

节点变量通过三个核心参数进行精确控制：

pull_keys（变量提取控制） ​

控制从上层环境（outer_env）提取哪些变量字段到本地环境：

  • None：完全继承上层环境的所有变量（self._attributes_store = outer_env.copy()）
  • 非空字典：按字典中指定的键从上层环境提取对应字段（键为变量名，值为描述）
  • 空字典：不继承任何上层变量（self._attributes_store = {}）

push_keys（变量回写控制） ​

控制节点执行完成后，将哪些输出字段回写到本地和上层环境：

  • None：回写策略取决于 pull_keys 的设置
    • 当 pull_keys 为 None 时：回写输出中与本地 attributes 共同存在的所有键
    • 当 pull_keys 为非空字典时：仅回写 pull_keys 中指定的键
    • 当 pull_keys 为空字典时：不回写任何变量
  • 非空字典：仅回写字典中指定的键（键为变量名，值为描述）
  • 空字典：不回写任何变量

attributes（初始本地变量） ​

节点的初始本地变量，不受 pull_keys 和 push_keys 影响，在节点初始化时直接设置到 _attributes_store 中。

节点类型差异 ​

重要提醒

不同类型节点的 pull_keys 与 push_keys 默认值不同：

  • Agent 节点：两者默认值均为空字典 {}，意味着默认不继承也不回写变量
  • 非 Agent 节点：两者默认值均为 None，意味着默认全量继承和回写变量

节点变量在节点执行时的作用阶段 ​

节点在执行过程中，变量处理遵循以下流程：

  1. 变量提取阶段（_pull_attributes）

    • 在节点执行开始时调用
    • 根据 pull_keys 规则从上层环境提取变量到本地

  2. 业务逻辑处理

    • 执行节点的 _forward 方法
    • 使用本地变量进行计算

  3. 变量回写阶段

    • 本地回写（_attributes_push_local）：将输出回写到本地 _attributes_store
    • 上层回写（_attributes_push_outer）：将本地变量回写到上层环境

Agent 节点的特殊处理 ​

对于 Agent 节点，pull_keys 和 push_keys 中的描述信息具有特殊意义：

  • pull_keys 的描述：会被添加到 Agent 的 prompt 中，告知 Agent 可以访问哪些变量及其含义
  • push_keys 的描述：会被添加到 Agent 的 prompt 中，指导 Agent 应该输出哪些字段及其用途

变量的使用场景 ​

  • 状态共享：在多个节点间共享计算状态和中间结果
  • 参数传递：将配置参数和初始数据传递给子组件
  • 结果汇总：收集和聚合各节点的计算结果到上层环境
  • 条件判断：为分支节点和控制节点提供判断依据
  • 上下文传递：在嵌套图结构中传递执行上下文
  • 记忆机制：在循环和迭代过程中保持状态连续性

消息流 ​

消息流（Message Flow）描述了数据在工作流中的传递过程和格式转换机制。 更细粒度的“水平传递（edge）+ 垂直传递（attributes）”可参考： 消息更新与传递（水平 / 垂直）。

两层消息模型（推荐心智模型） ​

  • 水平消息（Edge）：节点输出字段沿边传递，由 keys 决定下游可见字段。
  • 垂直消息（attributes）：节点通过 pull_keys/push_keys 读写图上下文状态。

推荐分工：

  • 业务 payload（正文、评分、结果）优先放水平消息
  • 流程状态（计数、重试、阶段标记）优先放垂直消息

相关示例：

  • 水平为主：/zh/examples/sequential_workflow、/zh/examples/parallel_branching
  • 垂直为主：/zh/examples/attributes
  • 混合模式：/zh/examples/looping

消息的基本概念 ​

  • 消息对象：封装数据内容和格式信息的载体
  • 消息格式化器：负责消息格式转换的组件
  • 消息聚合：将多个输入消息合并为统一格式
  • 消息分发：将输出消息发送给所有下游节点

消息处理流程 ​

  1. 消息生成：上游节点产生输出消息
  2. 格式化：通过 MessageFormatter 进行格式转换
  3. 传输：消息通过边传递给下游节点
  4. 聚合：下游节点聚合所有输入消息
  5. 解析：将消息内容解析为节点可处理的格式

消息格式类型 ​

  • JSON 格式：结构化数据的标准格式
  • 文本格式：简单字符串消息
  • 自定义格式：通过自定义 MessageFormatter 支持特殊格式

控制流 ​

控制流（Control Flow）定义了节点执行的顺序和条件，是工作流调度的核心机制。

基于状态的调度 ​

MASFactory 采用基于节点状态的动态调度：

  • 就绪条件：所有入边有消息且Gate状态为Open
  • 执行队列：维护当前可执行节点的队列
  • 并发执行：支持多个就绪节点的并发处理

控制结构 ​

  • 顺序控制：节点按依赖关系顺序执行
  • 分支控制：通过 Switch 节点实现条件分支
  • 循环控制：通过 Loop 图实现迭代逻辑
  • 并行控制：独立分支的并发执行