Agently 文档

中文

EN

中文

EN

Appearance

运行态数据、共享状态与运行资源 ​

TriggerFlow 里最容易出错的，不是分支怎么写，而是“这个值到底该放哪一层”。

适合什么时候读 ​

  • 你已经开始写 TriggerFlow
  • 你不确定请求级数据、共享状态和运行依赖分别该放哪里
  • 你遇到了执行恢复后资源丢失、或者跨 execution 状态串味的问题

你会学到什么 ​

  • data.state、data.flow_state、runtime resources 的职责边界
  • flow 级资源和 execution 级资源覆盖怎么理解
  • 为什么恢复执行时经常缺的不是状态，而是运行资源

三层模型 ​

这张图在正文里强调的是: 数据和依赖不是一回事, 共享状态和单次执行状态也不是一回事。

快速判断规则 ​

  • 只属于这一次 execution 的值: 放 data.state
  • 之后同一个 flow 的其他 execution 也应该看到的共享值: 放 data.flow_state
  • logger、client、helper 这类不可序列化依赖: 放 runtime resources

如果一个值本质上是长期记忆或跨进程持久化数据，那通常应该放到外部存储，而不是只靠 TriggerFlow 运行时。

最小示例 ​

python
def prepare(data):
    data.state.set("request", {"topic": data.value})
    data.flow_state.set("shared_locale", "zh-CN")
    logger = data.require_resource("logger")
    logger.info("prepare")
    return data

flow.update_runtime_resources(logger=my_logger)

execution = flow.create_execution(
    input_value="Agently",
    runtime_resources={"search_tool": custom_search_tool},
)

资源覆盖怎么理解 ​

实用规则:

  • 整个 flow 都会用到的默认依赖: 用 flow.update_runtime_resources(...)
  • 只想对某一次 execution 覆盖: 用 create_execution(runtime_resources=...)
  • 当前 handler 临时生成的依赖: 用 data.set_resource(...)

恢复执行时真正会保留什么 ​

  • execution 级状态
  • flow 级状态快照
  • 中断、结果就绪状态等执行信息
  • 资源 key 名

不会自动保留:

  • live 资源对象
  • client 实例
  • 函数对象

所以恢复后失败，很多时候不是 state 丢了，而是资源环境没重新注入。

sub_flow 的边界 ​

子流程不会天然共享父流程的运行态容器本身。父子之间能交换什么，应该通过显式的 capture / write_back 来声明。

如果你没有显式 capture，就不要假设子流程天然看得见父流程里的一切。

常见误区 ​

  • 把请求级数据写进 data.flow_state，导致后续 execution 串味。
  • 把 logger、db client 这类对象塞进 data.state。
  • 以为 save() / load() 会把所有 runtime resources 一起持久化。

下一步去哪 ​

  • agently-triggerflow-state-and-resources
  • agently-triggerflow