Agently 文档

中文

EN

中文

EN

Appearance

蓝图、配置导入导出与 Mermaid ​

可视化边界：Mermaid 可展示匿名链路帮助理解；JSON/YAML 导出不接受匿名 handler / condition。

v4.0.8.3 中有四种“复用/表达流程”的方式：

1. 四种表达方式的边界 ​

如何阅读这张图 ​

  • 这几种方式不是互相替代，而是针对不同复用边界。
  • BluePrint 偏运行时复用，Flow Config 偏可交换配置，Mermaid 偏可视化沟通，sub_flow 偏流程组合。

2. save_blue_print() / load_blue_print() ​

适合：

  • 同一 Python 进程内部复制流程定义

特点：

  • 不涉及 JSON/YAML
  • 不要求 handler 做显式注册

3. Flow Config ​

公开接口：

  • get_flow_config()
  • get_json_flow()
  • get_yaml_flow()
  • load_flow_config()
  • load_json_flow()
  • load_yaml_flow()

适合：

  • 跨进程/跨环境复用
  • 配置驱动
  • 审核与版本化

导出前提 ​

需要稳定的 handler / condition 引用。

推荐：

python
flow.register_chunk_handler(named_chunk)
flow.register_condition_handler(named_condition)

匿名 lambda 可以运行，但不能导出 JSON/YAML flow config。

4. sub_flow 也参与导出 ​

v4.0.8.3 起，to_sub_flow(child_flow) 不再只是运行时 closure，而是 flow config 可识别的一等 operator。

这意味着：

  • 子流程结构会进入父流程的导出配置
  • capture / write_back 声明也会保留在配置里
  • 重新 load_flow_config() 后仍能按同样的子流程边界运行

5. Mermaid ​

接口：

  • to_mermaid()
  • to_mermaid(mode="simplified")
  • to_mermaid(mode="detailed")

规则：

  • Mermaid 可以展示匿名 lambda
  • Mermaid 主要用于给人看结构
  • Mermaid 不是 execution state 持久化方案

v4.0.8.3 的 Mermaid 增强点：

  • if_condition / match / for_each 内部节点在 simplified 模式下会继续展开
  • 循环或条件块结束后的后续节点，不再错误落进上一层 group
  • sub_flow 会显示为虚线浅底色框，并内联 child flow 完整结构

6. declare_emits() ​

如果 chunk 内会主动 emit() 某些业务事件，建议声明：

python
chunk.declare_emits("Alert")

它会影响：

  • flow config 的 emit_signals
  • Mermaid 对外部信号的显示

7. replace=True ​

load_flow_config() / load_json_flow() / load_yaml_flow() 默认使用：

  • replace=True

即用导入配置替换当前 blue_print。

8. 推荐理解顺序 ​

  1. 先把 BluePrint 理解成“进程内定义复用”
  2. 再把 Flow Config 理解成“可交换定义格式”
  3. 把 Mermaid 理解成“给人看的结构图”
  4. 把 sub_flow 理解成“在父流程里组合一个隔离 child flow”