agently-triggerflow

Agently TriggerFlow

当应用负责管理可见的多阶段执行语义时，使用 TriggerFlow。对于单个有界请求/运行，使用 ModelRequest/AgentExecution；如果一个 Agent 负责某项长任务的规划、证据收集、验证和修复，且应用未定义阶段拓扑，则使用 agent.create_task(...)。

按需阅读

• 图构建、状态、生命周期、Stage 桥接和主仓库示例： references/overview.md。
• 暂停/恢复快照、资源恢复、保留策略和重启相关说明： references/recovery.md。
• 可选运行时指导与必需的外部等待： references/runtime-intervention.md。
• 稳定的应用流投影：references/stream-bridge.md。
• DevTools 图/观察：references/devtools-graph.md。
• 完整的值/信号拓扑审查： ../agently-design/references/execution-topology-validation.md。
• 直接涉及 Stage 作用域、结算、桥接、通道或监听器的问题，请使用 agently-stage。

拓扑优先

实现之前，先梳理：

• 必需的串行值边；
• 独立分支和有界汇合点；
• 请求时的观察边界；
• 可安全取消或丢弃的临时工作；
• 副作用顺序、外部容量、等待、修复和终止状态。

使用 batch(...)、for_each(...)、when(...) 和托管 emit，让扇出与汇合在图中清晰可见。使用显式回边表示重复；不要将生命周期、重试或修订循环隐藏在 while True 分块处理器中。

ModelRequest 是调度时的快照。instant 输出可以更新 UI，或启动幂等/可取消的准备工作；但如果后续模型请求需要使用由此产生的观察结果，就必须在可见的汇合点和验证屏障之后启动。

图中的邻接关系只能证明激活关系，不能证明值传递。审查时，应沿着 ModelRequest、Action、子流程、TaskWorkspace/RecordStore、等待/恢复、修复和终止边界，追踪确切的值、信号、引用和使用方。

生命周期与状态

• 调用方拥有异步边界时，优先使用异步处理器和执行 API。同步 provider 门面内部可以使用 Agently-Stage；直接的桥接问题请转至 agently-stage。
• 仅当运行会自行结束，且调用方不需要执行句柄时，才使用 flow.start(...) / flow.async_start(...)。
• 对于外部 emit、暂停/恢复、保存/加载、干预、检查、取消或由宿主控制的关闭，使用 flow.create_execution(auto_close=False)。
• 使用位置参数传入初始值，并通过 await execution.async_close() 关闭。关闭会排空由执行管理的 nowait 工作，并报告未解决的所有权问题。
• 恢复后的行为应放在下游分块、显式恢复事件或 data.is_resume 分支中；挂起的 Python 帧不是恢复契约。
• 执行状态负责每次运行的分块交接。在异步分块中，等待异步状态、emit 和流式方法。setter 会替换完整值；仅在有意累积列表时才使用 append。
• flow_data 在多个执行之间共享。保存/加载会序列化并替换该共享值的副本；它不提供隔离、CAS、合并或并发安全性。
• TaskWorkspace 负责文件，RecordStore 负责持久记录和恢复，宿主存储负责业务持久化。执行状态中保留精简的引用/状态，并将完整内容置于冷存储中。

并发、等待与流

• create_execution(concurrency=N) 限制整个执行过程中的处理程序分发并发数； batch(..., concurrency=N) 和 for_each(..., concurrency=N) 限制本地 扇出的并发数。
• 宿主准入、提供商／模型速率限制和阻塞式工作池仍由不同组件分别负责管理压力。
• 使用 emit_nowait(...) / async_emit_nowait(...)，而不是不受跟踪的 asyncio.create_task(...)；执行关闭时会处理已注册的工作。
• 对于必需的外部输入，使用 pause_for(..., resume_to=...)。仅在声明的边界处， 才使用运行时干预来提供可选上下文。
• PolicyApproval 负责框架策略关卡；ExecutionExchange 负责适配宿主 UI／Webhook／队列传输；TriggerFlow 负责中断／恢复记录。
• 将模型解析器事件转换为稳定的应用事件。不要将原始解析器路径暴露为前端协议，并将临时项与最终验证后的输出进行协调。

恢复与动态图边界

保存／加载负责管理 TriggerFlow 的进度和声明的恢复元数据，不包括实时 客户端、回调、信号量、协程帧、机密信息或外部会话状态。通过宿主／插件解析器恢复实时的 ExecutionResources，并在就绪前验证外部引用、版本、租约和栅栏令牌。Local RecordStore 只能证明本地重启可行；没有真正的共享提供商和运行证据时，不要声称支持分布式恢复。

在可导入的 TriggerFlow 模块中直接定义开发者负责的稳定拓扑，并使用顶层处理程序。显式提交或由模型生成的 DAG 数据属于低频 TaskDAG 场景；请阅读 ../agently/references/task-dag.md。切勿将未经验证的运行时计划数据编译为临时的 TriggerFlow 定义。

API 形式

from agently import Agently, TriggerFlow

flow = TriggerFlow(name="workflow-name")
factory_flow = Agently.create_trigger_flow("factory-workflow")
execution = flow.create_execution(auto_close=False)

when、emit_nowait 和 pause_for 是 flow／runtime 方法，不是顶层 导入项。不要将 @flow.when(...) 用作装饰器，也不要将 flow 名称作为 TriggerFlow(...) 的第一个位置参数。

反模式

• 自定义事件总线、状态机、DAG 调度器或影子执行存储。
• 用休眠、轮询、本地完成集合或不受跟踪的任务，代替信号、连接等待和执行管理的工作。
• 使用闭包捕获的实时业务资源，而不是显式运行时资源和解析器。
• 将 flow_data 用作普通的单次执行状态。
• 将 DevTools 图表作为拓扑事实来源，而不是以定义和运行时元数据为准。