P6 · 如何管理和调度 Agent 工作流？ - Workflow Management
所属知识库：Agent 全栈技术地图
所属领域：04 · Agent Platform
所属章节：02 · Agent Platform 是如何构建和运行的？ - Technical Architecture
文档类型：专题研究 / 技术架构 / 参考设计
版本：v1.3
更新日期：2026 年 11 月 1 日
核心问题：Agent Platform 如何将 Workflow 作为可定义、校验、版本化、触发、执行、暂停、恢复、审计与治理的平台资产，并协调 Agent、工具、人工审批与外部系统完成跨步骤任务？
专题导读
本篇属 Technical Architecture。P6 研究的是平台级 Workflow Management，而非再次介绍 Agent 内部如何推理，也不等于把多 Agent 的消息通信简单绘制成流程图。这里的 Workflow 是具有明确身份、定义、版本、执行记录和管理权限的可管理资产；Workflow Engine 是执行或协调该资产的技术组件。两者既可以由同一软件实现，也可以分离。
本篇围绕五个问题展开：定义什么、何时触发、由谁调度、如何恢复、如何治理。贯穿案例为“技术研究报告 Studio”：选题 → 审核 → 深度调研 → 分析 → 人工确认 → 写作与交付。示例中的状态机、数据表、API、事件与代码是可讨论的参考设计，未声称已经部署或通过测试。
研究结论
- Workflow Definition、Workflow Version 与 Workflow Run 必须分离。 定义承载稳定身份，版本固定图与配置，运行记录一次实际执行；长任务不应在运行中无意切换定义版本。
- 平台工作流管理不等于 Agent System 内部编排。 平台负责资产、触发、授权、版本、运行生命周期、配额与审计；Agent System 负责具体节点内部的推理、工具调用和协作策略。两者可以通过适配器和运行契约连接。
- 调度的基本单位应是具备持久身份的工作项。 Workflow Run 下可存在 Step Run、Task、Attempt；要显式记录依赖、重试、超时、取消、结果引用和人工等待状态。
- 工作流可靠性依赖持久化状态与明确的副作用语义。 “至少一次投递”下，节点可能重复运行；无法用简单重试保证外部写操作恰好一次完成。
- 人工审批应是可持久化的等待点。 审批记录、授权主体、输入快照、超时和恢复动作必须独立管理，不能依赖浏览器连接或内存回调。
- 工作流版本与依赖必须可追溯。 Agent Version、工具版本、提示词、模型策略、资源授权与策略快照都可能影响结果；应区分强固定与运行时解析的依赖。
- MVP 宜先实现有限的工作流语义。 顺序、条件、并行汇聚、重试、人工等待与结果交付通常比一开始构建通用可视化编排语言更重要。
一、概念、对象与研究边界
1.1 什么是平台级 Workflow Management？
平台级 Workflow Management 是 Agent Platform 对工作流资产及其执行过程提供的一组管理能力，包括定义、编辑、校验、版本、发布、触发、调度、状态追踪、暂停恢复、权限、配额、审计和结果交付。它既面向开发者，也面向平台管理员和业务使用者。
Workflow 描述一组有依赖关系的工作步骤及其数据流、控制流和异常处理规则；Workflow Engine 解释并推进这些规则；Orchestrator 可泛指协调执行的控制逻辑，不必与独立引擎一一对应。Agent Workflow 的节点可包含 Agent 调用、普通代码、工具调用、人工审批、等待事件、外部服务和子工作流。
一个“聊天界面中先问 A 再问 B”的固定交互未必是平台级工作流。若其没有独立的定义身份、版本、运行记录或管理接口，可能只是应用内部的流程逻辑。
1.2 与相邻专题的边界
| 专题 | 主要研究对象 | 与 P6 的交界 |
|---|---|---|
| 02 · Agent / A9 Planning & Reasoning | 单个 Agent 的规划与推理 | P6 将 Agent 视为可调度的节点，不替代其内部规划 |
| 03 · Agent System / L5 Orchestration & Collaboration | 系统内任务编排与 Agent 协作机制 | P6 管理可复用工作流资产、版本、触发与平台级运行 |
| P1 Control Plane | 执行准入、控制命令、全局策略 | P6 接收准入结果，推进工作流状态与步骤调度 |
| P2 Execution Plane | Worker、Sandbox 与实际执行 | P6 派发节点工作项，P2 执行并返回结果 |
| P3 Agent Registry | Agent 定义与不可变版本 | P6 通过固定引用使用 Agent Version；工作流可有独立 Registry |
| P4 Agent Development Services | 编辑、校验、调试、测试构建 | P6 定义工作流运行语义与管理契约 |
| P5 Deployment & Runtime Management | 部署、运行实例与容量 | P6 使用可用执行能力，不重复 Worker 生命周期 |
| P10 Platform Data & Assets | 平台数据与资产存储治理 | P6 定义执行状态与产物引用，依赖 P10 保存资产 |
| P11 / P12 | 多租户隔离、权限与治理 | P6 在定义、触发、执行和审批各环节落实策略 |
| F5 / F7 | 工作空间、项目与 Agent 协作产品体验 | P6 研究后端工作流能力，不预设特定 UI |
边界检验： 若研究问题是“怎样在图上连接两个节点”，偏向 Builder 与产品设计；若是“两个节点之间的数据、失败、重试和状态如何保证一致”，属于 P6；若是“节点内部多个 Agent 怎样协商”，属于 L5。
1.3 核心对象及其层次
| 对象 | 身份与职责 | 生命周期要点 |
|---|---|---|
| Workflow Definition | 工作流稳定身份、所有者与元数据 | 创建、编辑、归档 |
| Workflow Draft | 可编辑的工作流草稿 | 草稿修订、并发控制、校验 |
| Workflow Version | 不可变的图结构与执行配置快照 | 校验、发布、撤销、弃用 |
| Workflow Deployment / Binding | 版本与环境、入口或渠道的绑定 | 激活、切换、停用 |
| Trigger | 定时、事件、Webhook 或手动入口 | 注册、启用、禁用 |
| Workflow Run | 一次工作流执行实例 | 待运行、运行、等待、完成等 |
| Step Run | 某节点在某次工作流中的执行记录 | 待依赖、可调度、运行、终态 |
| Attempt | 一次实际执行尝试 | 领取、执行、成功、失败、超时 |
| Approval Request | 持久化的人类决策请求 | 待审、批准、拒绝、过期 |
| Artifact Reference | 节点输入输出与最终产物的引用 | 创建、授权访问、保留、归档 |
Workflow Run 与 P1/P2 的通用 Run 可能是同一基础对象的特化，也可能通过 parent_run_id 关联。不应在一个平台内无意设计两套含义冲突的 Run ID。
二、工作流的定义模型与执行语义
2.1 控制流、数据流、事件流应分开建模
控制流描述节点执行顺序、分支与汇聚；数据流描述节点读取与输出什么；事件流描述系统如何观察执行及处理外部信号。三者不能完全由一条“连线”表达。尤其是条件分支：未被选择的节点是 SKIPPED，不是 FAILED；汇聚节点必须说明等待哪些前驱。
flowchart LR
T[Trigger] --> S[选题 Agent]
S --> R{审核}
R -->|退回| S2[修订选题]
S2 --> R
R -->|通过| D[深度调研]
D --> A[深度分析]
A --> H{人工确认}
H -->|批准| W[报告写作]
H -->|拒绝| X[终止或返工]
W --> O[产物交付]这张图是业务逻辑示意，不是可直接运行的工作流定义。实际引擎还需声明循环上限、超时、输出 Schema、审批权限、失败处理、重试策略和版本引用。
2.2 参考节点类型
| 节点 | 输入输出 | 关键语义 |
|---|---|---|
| Agent Task | 输入参数 → 结构化结果/产物 | 固定 Agent 版本、模型与工具权限 |
| Tool / Service | 参数 → 外部响应 | 幂等键、超时、速率限制与副作用 |
| Transform | 数据 → 数据 | 确定性变换、Schema 校验 |
| Condition | 布尔/枚举 → 分支 | 决策依据与未选中分支处理 |
| Parallel / Join | 多输入 → 汇聚 | all / any / quorum、部分失败 |
| Human Approval | 审批请求 → 决策 | 权限、等待、超时、恢复 |
| Timer / Wait Event | 时间/事件 → 继续 | 持久订阅、去重、过期策略 |
| Subworkflow | 参数 → 子流程结果 | 版本固定、深度限制、父子追踪 |
| Emit / Deliver | 产物 → 交付状态 | 对账、重复投递、访问控制 |
quorum、动态循环、补偿事务等属于可选高级能力。MVP 不必同时支持全部节点类型。
2.3 工作流图的合法性
平台应在发布前校验：节点 ID 唯一、入口可达、边引用有效、端口类型兼容、条件分支完备、循环受限、无未声明副作用、依赖版本可解析、工具权限满足策略、敏感数据流向符合约束。
对于 DAG，拓扑排序能检测非法环；但并非所有 Agent 工作流都必须是 DAG。带审核返工的流程天然可能循环。支持循环时，应使用显式 Loop/Retry 节点、迭代计数、退出条件和最大执行预算，避免任意图环导致不可控运行。
2.4 数据契约与引用传递
节点输入建议使用 Schema 声明，避免完全依赖自然语言约定。大文件、报告、图像或长文本不宜在所有事件中重复嵌入，应保存为带权限控制的 Artifact Reference，并在步骤间传递引用。
例如，调研节点输出 research_artifact_id 和 citations_manifest_id，分析节点通过授权读取，避免重复复制全文并失去来源关联。敏感内容不应直接进入可广泛访问的事件总线。
2.5 示例：参考 Workflow Manifest
apiVersion: platform.example/v1
kind: Workflow
metadata:
workflowId: research-studio
tenantId: tenant-demo
spec:
inputSchema: research-topic-v1
maxDurationSeconds: 86400
maxTotalAttempts: 20
nodes:
- id: topic
type: agent
agentVersion: topic-agent@1.2.0
outputSchema: topic-proposals-v1
retry:
maxAttempts: 2
backoff: exponential
- id: review
type: agent
agentVersion: review-agent@1.0.0
dependsOn: [topic]
outputSchema: review-decision-v1
- id: approval
type: human_approval
dependsOn: [review]
timeoutSeconds: 172800
requiredRole: project_owner
- id: research
type: agent
agentVersion: research-agent@2.1.0
dependsOn: [approval]
when: "approval.decision == 'approved'"
- id: deliver
type: deliver
dependsOn: [research]该 YAML 是自定义教学契约，不是 Temporal、LangGraph、Argo、Dify 等产品的真实配置格式。它省略了输出映射、审批拒绝路径与复杂循环，仅用于说明字段职责。
三、Workflow Registry、版本与发布
3.1 Workflow 与 Agent 的版本关系
Workflow Version 固化的是流程图及其执行策略，而 Agent Version 固化的是节点使用的 Agent 定义。二者独立演进：修改流程拓扑需要新 Workflow Version；只修改某 Agent 的指令也应发布新 Agent Version，并由新的 Workflow Version 或显式绑定策略决定是否采用。
推荐记录：workflow_version_id、definition_digest、node_agent_version_ids、tool_bindings、input_output_schema_versions、policy_snapshot_id、published_by、published_at。运行时解析到的模型、工具与凭据引用应另存 resolved_execution_manifest，以便追踪动态路由和轮换。
3.2 发布管线
Draft 编辑 → 结构/语义校验 → 权限与依赖检查 → 模拟/测试
→ 审批（按策略） → 冻结 Workflow Version
→ 绑定环境或发布渠道 → 启用 Trigger发布工作流版本与启用触发器应是两个不同动作。发布成功不代表立即允许外部 Webhook 触发生产任务。对于生产入口，建议由 Deployment/Binding 指向一个确定的 Workflow Version，避免执行时读取可变草稿。
3.3 已运行实例与版本升级
长时间运行的 Workflow Run 原则上继续使用启动时固定的 Workflow Version。若确需迁移，必须明确旧节点到新节点的映射、状态兼容性、待审批请求、输出 Schema 和副作用；迁移应作为显式受控操作，不能因更新 production 指针而自动发生。
3.4 复用、子工作流与模板
模板是可复制或参数化的设计资产；子工作流是执行时被调用的工作流版本。两者不同：复制模板后通常形成新的定义身份；调用子工作流则产生父子 Run 关联。共享工作流应执行跨租户访问控制，禁止通过模板间接泄露密钥或私有数据。
四、触发机制与执行准入
4.1 触发类型
| 类型 | 典型场景 | 必须解决的问题 |
|---|---|---|
| 手动/API | 用户点击“开始研究” | 身份、授权、幂等、输入校验 |
| 定时 | 每日定时报告 | 时区、夏令时、错过调度、并发重叠 |
| Webhook | 外部系统通知 | 签名、重放防护、速率限制 |
| 事件驱动 | 新资料上传后分析 | 事件去重、顺序、订阅生命周期 |
| 上游工作流 | 前一项目完成后继续 | 父子关联、级联失败、循环触发 |
触发器接收到事件后，先进行身份校验、租户归属确认、Schema 校验、配额与预算检查，再创建 Workflow Run。不能把“Webhook 收到 HTTP 200”当成工作流成功执行。
4.2 触发幂等与去重
推荐幂等键作用域为 (tenant_id, trigger_id, external_event_id)，并在数据库上建立唯一约束。手动/API 调用可接受客户端提供的 Idempotency-Key；重复请求应返回已有 Run 的引用，而非创建新任务。
对于定时任务，需要明确定义 scheduled_for 与 actually_started_at。调度器故障恢复后，是否补跑错过的时间窗属于产品策略，不能默认全部补跑，否则可能引发成本峰值。
4.3 准入决策
准入可综合用户角色、Workflow Version 状态、Agent/Tool 权限、租户配额、并发限制、成本预算、敏感数据策略与运行环境健康度。准入通过仅授权启动；节点执行时仍需对实际工具操作做权限检查。
五、调度器与工作流执行引擎
5.1 典型运行链路
sequenceDiagram
participant U as User / Trigger
participant CP as Control Plane
participant WE as Workflow Engine
participant DB as State Store
participant Q as Task Queue
participant EX as Execution Plane
participant A as Agent System
U->>CP: Start Workflow(version, input, idempotencyKey)
CP->>CP: Auth / Policy / Quota
CP->>DB: Create Workflow Run (pinned version)
CP->>WE: Start(runId)
WE->>DB: Persist ready Step Runs
WE->>Q: Dispatch step task
Q->>EX: Deliver task
EX->>A: Execute pinned Agent Version
A-->>EX: Result / Artifact refs
EX->>DB: Commit Attempt outcome
EX-->>WE: Step completion event
WE->>DB: Advance graph state
WE-->>CP: Run status / completion
CP-->>U: Status / artifact references在真实分布式系统中，事件和状态更新可能重复、延迟或乱序。图示仅表达逻辑职责，不保证每条箭头都是独立网络调用。
5.2 调度器的基本职责
引擎读取已固定的工作流定义与当前状态，判断哪些节点依赖已满足，生成待执行 Step Run，派发给执行面，并处理完成、失败、等待和取消事件。调度器应能够在重启后从持久化状态重新计算可执行节点，而不依赖内存中的“当前步骤”。
节点可执行性不应只根据“所有前驱成功”判断。条件分支中的 SKIPPED、并行汇聚中的部分成功、审批拒绝等都需要明确语义。可采用三值依赖结果：satisfied、blocked、impossible，由不同节点类型解释。
5.3 并发、队列与公平性
至少考虑四级限制：平台总并发、租户并发、Workflow Version 并发、特定 Agent/工具并发。高优先级任务可使用独立队列或权重调度，但应避免低优先级租户长期饥饿。外部模型 API 的速率限制与平台 Worker 数量是不同约束，必须同时计量。
5.4 工作流与任务执行的关系
一个 Workflow Run 包含多个 Step Run；一个 Step Run 可能因失败产生多个 Attempt；一次 Attempt 由某个 Worker 执行。平台可把 Step Run 映射到 P2 的通用 Task，也可把子 Agent 调用映射到独立 Run，但需要统一 workflow_run_id、step_run_id、attempt_id 的追踪关系。
5.5 执行一致性与状态推进
推荐将“步骤结果落库”和“后继任务产生意图”放入同一事务，采用 Transactional Outbox 或等效机制确保事件最终可投递。消费者使用幂等键和唯一约束去重。不要声称跨数据库、队列与外部 API 具备普遍的 exactly-once 语义。
六、状态机、暂停恢复与人工审批
6.1 Workflow Run 状态机（参考）
stateDiagram-v2
[*] --> PENDING
PENDING --> RUNNING
RUNNING --> WAITING
WAITING --> RUNNING: approved / event / timer
RUNNING --> SUCCEEDED
RUNNING --> FAILED
RUNNING --> CANCELING
WAITING --> CANCELING
CANCELING --> CANCELED
WAITING --> TIMED_OUT
RUNNING --> TIMED_OUT这只是最小状态集合。PAUSED 与 WAITING 可以分开：前者是用户/管理员主动冻结，后者是等待外部条件；两者恢复权限与超时语义不同。若平台采用补偿执行，还需引入 COMPENSATING、COMPENSATED 等状态。
6.2 Step Run 与 Attempt 状态
建议 Step Run 至少区分 BLOCKED、READY、DISPATCHED、RUNNING、WAITING、SUCCEEDED、FAILED、SKIPPED、CANCELED。Attempt 则区分 CREATED、LEASED、RUNNING、SUCCEEDED、FAILED、TIMED_OUT。一次 Step Run 的最终失败不必意味着整个 Workflow Run 立即失败，取决于 on_failure 策略。
6.3 人工审批是持久化节点
审批请求至少保存：approval_id、workflow_run_id、step_run_id、tenant_id、required_role、requested_by、decision、decided_by、created_at、expires_at、input_snapshot_ref、decision_reason。批准动作需验证操作者当前身份与授权；拒绝、过期、撤回必须有明确后继路径。
避免使用“审批页面打开期间阻塞一个 Worker”的实现。正确方式是将工作流持久化为等待状态，释放执行资源，收到合法审批事件后恢复调度。
6.4 取消与暂停的边界
取消是协作式请求：已发出的外部邮件、付款或数据库写入不一定可撤销。引擎应阻止新的节点派发，并向可取消的执行任务发送取消信号；对已发生的副作用记录实际结果并执行必要补偿。暂停也不能保证正在运行的模型调用瞬间停止，需规定安全暂停点。
6.5 超时、重试与死信
区分工作流总超时、步骤超时、执行尝试超时、人工审批超时和外部事件等待超时。重试策略应定义最大次数、退避、抖动、可重试错误类别和总预算。永久失败进入明确终态或人工处理队列，而不是无限循环。
七、失败语义、补偿与可靠性
7.1 常见故障及处理
| 故障 | 风险 | 参考策略 |
|---|---|---|
| 事件重复投递 | 同一步骤被重复推进 | 唯一键、版本号、幂等消费 |
| Worker 执行中崩溃 | 不知外部副作用是否发生 | 先对账，后重试；记录 Attempt |
| 引擎重启 | 内存调度状态丢失 | 从数据库重建可执行节点 |
| 审批超时 | 工作流永久挂起 | 到期任务、明确拒绝/升级路径 |
| 并行分支部分失败 | 汇聚结果不确定 | 明确 all/any/quorum 语义 |
| 发布版本更新 | 在途任务行为漂移 | Run 固定版本；迁移显式审批 |
| 依赖服务限流 | 任务积压、成本飙升 | 限流、退避、熔断、预算门禁 |
| 用户取消 | 已执行副作用无法撤回 | 停止后续派发、补偿与审计 |
7.2 幂等不是“重复执行永远无害”
对于读取资料、纯数据变换，重试相对安全；对于发送邮件、创建工单、写入 CRM、付款等操作，必须提供外部幂等键或业务对账。平台能保证的通常是“尽可能避免重复”和“可检测、可恢复”，而非对任意外部系统的全局恰好一次副作用。
7.3 Saga 与补偿
跨服务工作流通常无法使用一个数据库事务覆盖全部外部操作。可采用 Saga：每个成功步骤声明可能的补偿操作；后续失败时按策略执行补偿。但补偿不等于精确回滚，可能失败、需要人工介入，也可能产生新的审计事件。对不可逆动作应在执行前设置更严格的人工审批。
7.4 可恢复性的最低要求
恢复时至少能回答：当前 Workflow Version 是什么、哪些节点完成、哪些仍在运行、外部副作用证据在哪里、下一步可安全执行什么、是否需要人类介入。只保存“当前节点名称”无法满足可靠恢复。
八、存储架构与数据模型
8.1 参考关系模型
erDiagram
WORKFLOW_DEFINITION ||--o{ WORKFLOW_VERSION : has
WORKFLOW_VERSION ||--o{ WORKFLOW_RUN : executes
WORKFLOW_RUN ||--o{ STEP_RUN : contains
STEP_RUN ||--o{ STEP_ATTEMPT : retries
STEP_RUN ||--o{ APPROVAL_REQUEST : waits_for
WORKFLOW_RUN ||--o{ WORKFLOW_EVENT : records
STEP_RUN ||--o{ ARTIFACT_REFERENCE : produces8.2 最小表设计（概念级）
| 表 | 核心字段 | 约束建议 |
|---|---|---|
workflow_definitions | id, tenant_id, owner_id, name | 租户范围唯一约束 |
workflow_versions | id, definition_id, digest, spec_ref, status | 已发布内容不可变 |
workflow_runs | id, version_id, trigger_id, state, input_ref, idempotency_key | 租户范围幂等唯一键 |
step_runs | id, run_id, node_id, state, output_ref, revision | (run_id,node_id,iteration) 唯一 |
step_attempts | id, step_run_id, attempt_no, worker_id, lease_until, state | 尝试编号唯一 |
approval_requests | id, step_run_id, required_role, expires_at, decision | 决策仅允许一次终态提交 |
workflow_events | id, run_id, sequence, type, payload_ref, created_at | 顺序与去重约束 |
outbox | id, aggregate_id, event_type, payload, delivered_at | 事务外发与重试 |
动态循环或子工作流需要增加 iteration_key、parent_run_id、subworkflow_version_id 等字段。以上仅是概念模型，生产实现需补齐外键、索引、分区、保留期限、加密与访问控制。
8.3 事件溯源与快照
事件溯源（Event Sourcing）可以提升可审计性与重放能力，但不是所有平台必选。较简单的方案是当前状态表 + 追加式事件日志 + 周期性快照。如果选择完整事件溯源，必须管理事件 Schema 演进、重放副作用隔离、历史兼容与存储成本。
8.4 数据保留与删除
工作流定义、执行日志、节点输入输出、审批记录、模型调用轨迹和最终产物的保留周期可能不同。删除 Workflow Definition 不应自动删除仍受保留政策约束的历史 Run；跨租户共享资产也不应绕过原始数据授权。此处由 P10/P12 提供平台级策略。
九、平台接口与事件契约
9.1 参考 API
POST /v1/workflows
PATCH /v1/workflows/{workflow_id}/draft
POST /v1/workflows/{workflow_id}/validate
POST /v1/workflows/{workflow_id}/versions
POST /v1/workflow-runs
GET /v1/workflow-runs/{run_id}
GET /v1/workflow-runs/{run_id}/steps
POST /v1/workflow-runs/{run_id}:cancel
POST /v1/workflow-runs/{run_id}:pause
POST /v1/workflow-runs/{run_id}:resume
POST /v1/approvals/{approval_id}:decide这些路径为参考设计。真实接口需补充认证、授权、租户作用域、分页、并发版本条件、错误码、速率限制、幂等及审计要求。pause 与 resume 的可用性取决于运行引擎是否支持安全暂停点。
9.2 运行请求示例
{
"workflow_version_id": "wfv_20261031_001",
"project_id": "project_research_01",
"input": {"topic": "Agent Platform 架构研究"},
"idempotency_key": "project_research_01_run_001",
"budget": {"max_cost_usd": 8.0}
}平台创建 Run 时，应返回稳定 run_id 和初始状态，长任务结果通过状态查询、事件订阅或 Webhook 获得，不要求请求连接持续存在。
9.3 事件契约示例
{
"event_id": "evt_001",
"event_type": "workflow.step.completed",
"schema_version": "1",
"tenant_id": "tenant_demo",
"workflow_run_id": "wfr_001",
"step_run_id": "step_003",
"attempt_id": "attempt_002",
"sequence": 19,
"occurred_at": "2026-10-31T10:00:00Z",
"result_ref": "artifact://tenant_demo/research/result-003"
}消费者必须能处理重复与乱序事件；事件中的 artifact:// 是说明性引用格式，不代表可直接公开访问的 URL。
十、安全、权限与资源治理
10.1 权限贯穿整个执行链
至少分别检查：谁可以编辑/发布工作流、谁可以启用触发器、谁可以启动 Run、节点可以调用哪些 Agent/工具、谁可以查看中间数据与产物、谁可以审批/取消/重试。拥有 Workflow 编辑权限不等于拥有全部工具执行权限。
10.2 多租户隔离
Workflow Definition、Version、Run、Step Run、事件、产物、审批记录都应绑定租户或可验证的归属链。调度器、队列、Worker、缓存与日志中的租户上下文必须一致。对于不可信代码或高风险工具调用，需要额外的执行隔离，不能仅依赖数据库查询条件。
10.3 预算与配额
建议同时设置单 Run 总预算、单节点最大尝试、最大迭代、最大并行数、租户总并发、工具调用次数和模型费用上限。预算耗尽应产生可观察的终止或等待决策，不能让工作流无限重试。
10.4 机密与提示词注入
工作流中的外部网页、文档和工具响应可能包含不可信指令。节点间传递内容时应保持数据与控制指令的边界；高风险工具应采用独立权限检查和人工审批。密钥通过运行时安全引用注入，不写入 Workflow Manifest 或事件日志。
十一、可观测性、评估与运营指标
11.1 统一追踪链
建议使用 trace_id → workflow_run_id → step_run_id → attempt_id → agent_run_id/tool_call_id 关联平台与 Agent System 的观测数据。关键事件包括 run.created、step.ready、step.started、step.completed、approval.requested、run.failed、run.completed。
11.2 核心指标
| 维度 | 指标 | 解释 |
|---|---|---|
| 可用性 | 工作流启动成功率 | 触发后成功创建合法 Run 的比例 |
| 完成度 | 工作流完成率 | 需区分成功、失败、取消与等待 |
| 时延 | 端到端完成时间 | 包含排队、执行与人工等待 |
| 调度 | Ready→Running 等待时长 | 识别队列拥塞与容量不足 |
| 可靠性 | 重试率、重复执行检测数 | 评估执行稳定性与副作用风险 |
| 人工协作 | 审批等待时长、超时率 | 识别流程瓶颈 |
| 成本 | 每成功 Run 的模型/工具成本 | 结合业务价值评估 |
| 质量 | 节点输出 Schema 合格率 | 仅反映结构，不等于内容正确 |
对 AI 生成内容的真实性、引用准确性和任务质量，仍需借助 03 Agent System 的 H3 Evaluation 和 H10 Testing & Validation；工作流“成功完成”不代表业务结果必然正确。
11.3 运维操作
平台应支持查看阻塞节点、识别失败原因、按权限重试安全节点、手动恢复等待中的 Run、停用异常 Trigger、隔离高风险工作流版本，并记录每次人工干预的操作者与理由。
十二、技术实现路径与选型
12.1 三种实现路径
路径 A：应用后端 + 数据库 + 队列 + 自研有限状态机。 适合语义有限、流程规模较小的 MVP。优点是对象模型可控、依赖少；缺点是持久化等待、重试、定时器和并发一致性需要自行实现。
路径 B：采用持久化工作流引擎。 例如 Temporal 一类的 durable execution 系统可承担工作流历史、计时、重试和恢复等底层能力，但仍需自行构建平台资产、权限、发布、租户与产品接口。应理解引擎对代码确定性、版本演进和活动副作用的约束。
路径 C：采用 Agent 图编排框架并叠加平台管理层。 例如 LangGraph 一类框架适合表达 Agent 状态图与中断恢复，但框架图定义不自动等于多租户平台 Registry、发布治理或产品权限。复杂系统可组合 B 与 C，但要避免重复状态机与双重调度。
12.2 选型对照
| 决策维度 | 自研有限引擎 | 持久化工作流引擎 | Agent 图框架 |
|---|---|---|---|
| 主要优势 | 精简、可控、契合业务 | 长任务与恢复基础设施 | Agent 状态与分支表达 |
| --- | --- | --- | --- |
| 主要成本 | 重试/计时/恢复自行实现 | 学习、部署、版本兼容 | 平台治理需额外建设 |
| 适用重点 | MVP、固定业务流程 | 长任务、强恢复需求 | Agent 驱动的动态流程 |
表格表达能力侧重，不代表某个产品完全不具备其他能力；应以目标版本官方文档及原型验证为准。
12.3 Studio 的推荐渐进路线
阶段 1：固定流程 MVP。 先实现选题、审核、调研、人工确认、报告交付六类节点；支持手动触发、Run 持久化、有限重试、人工审批和产物引用。
阶段 2：可配置工作流。 增加 Workflow Draft/Version、Schema 校验、条件分支、并行汇聚、运行图与节点级观测；不急于引入任意循环与复杂可视化 DSL。
阶段 3：团队与多租户。 增加项目权限、版本审批、配额、租户隔离、触发器治理、共享模板、成本与质量仪表盘。
阶段 4：平台生态。 增加 Webhook/事件触发、子工作流、插件节点、跨工作空间共享、正式 SDK 与高级恢复策略。
12.4 技术选型的关键验证问题
在采用任何框架前，应实际验证：长任务进程中断后能否恢复、人工等待是否占用 Worker、已运行实例如何兼容代码升级、重复事件如何处理、外部副作用如何对账、历史运行能否追踪实际依赖版本，以及租户隔离是否可以端到端实施。
十三、贯穿案例：技术研究报告 Studio
13.1 业务目标
用户创建一个研究项目，选择研究范围与 Agent 团队，启动选题流程；审核 Agent 对选题提出修改意见；通过后进入调研与分析；用户在关键节点确认；最终形成可追溯的报告产物。
13.2 对象映射
| Studio 对象 | 平台对象 | 关键关系 |
|---|---|---|
| Studio / Project | Workspace / Project | 项目所有权、成员与权限 |
| 研究流程模板 | Workflow Definition | 可复用的业务流程 |
| 已发布研究流程 | Workflow Version | 固定拓扑与节点配置 |
| 一次研究任务 | Workflow Run | 项目内的一次完整执行 |
| 选题、审核、调研节点 | Step Run | 独立状态、输出与重试 |
| 选题 Agent / 审核 Agent | Agent Version | Registry 中的不可变定义 |
| 用户确认 | Approval Request | 持久等待与授权决策 |
| 研究资料 / 报告 | Artifact | 受控存储、引用与交付 |
13.3 一次执行的具体过程
- 用户在项目中选择
research-workflow@v1，平台检查权限、预算与输入 Schema，并创建Workflow Run。 - 引擎创建
topicStep Run，调度选题 Agent；执行面返回候选题目和来源引用。 reviewStep Run 评估候选，若不通过，进入受限返工分支，记录修订轮次；达到迭代上限后升级人工处理。- 选题通过后，触发深度调研和分析；若两者可并行，应声明汇聚规则，而不是依赖消息先后顺序。
- 用户确认节点创建 Approval Request，释放 Worker，等待用户批准或拒绝。
- 批准后恢复工作流，写作 Agent 生成报告；平台保存产物引用与版本快照。
- Workflow Run 进入终态，Studio 展示节点轨迹、成本、引用和最终交付文件。
13.4 容易忽略的边界场景
- 用户连续点击两次“启动”：通过幂等键返回同一个 Run。
- 审核节点在失败前已写入结果：重试前先检查已提交的 Artifact 与 Attempt 记录。
- 用户审批时工作流已取消：审批接口拒绝过期决策并返回当前状态。
- Agent v2 在运行中发布：当前 Run 继续使用 v1；新 Run 根据发布渠道使用 v2。
- 调研工具临时不可用：按错误类别退避重试，预算耗尽时进入等待或失败状态。
- 用户退出浏览器：后台任务继续执行，状态由持久化存储维护。
13.5 推荐 MVP 架构
flowchart TB
UI[Studio Web UI] --> API[Platform API / Auth]
API --> CP[Control Modules]
CP --> REG[Workflow & Agent Registry]
CP --> DB[(PostgreSQL: Run / Step / Approval)]
CP --> ENG[Workflow Scheduler]
ENG --> Q[(Durable Queue)]
Q --> WK[Agent Worker Pool]
WK --> AR[Agent System Runtime]
WK --> OBJ[(Artifact Storage)]
WK --> DB
ENG --> DB
API --> OBJ逻辑架构不要求所有模块都是独立微服务。初期可采用模块化单体后端、独立 Worker 与可靠队列；当长任务、定时器或恢复复杂度上升时，再评估专用持久化工作流引擎。
十四、工程验证计划与验收标准
下表是待实施的测试计划，并非已通过的测试结果。
| 编号 | 验证场景 | 预期结果 |
|---|---|---|
| T01 | 非法节点引用 | 发布前拒绝并定位错误 |
| T02 | 无退出条件的循环 | 校验拒绝或强制预算上限 |
| T03 | 输入 Schema 不匹配 | 不创建可执行 Run |
| T04 | 重复手动启动 | 幂等键返回同一 Run |
| T05 | Webhook 重放 | 去重且记录安全事件 |
| T06 | 工作流版本切换 | 在途 Run 版本不漂移 |
| T07 | Worker 执行中崩溃 | 恢复后状态可解释且可安全处理 |
| T08 | 节点结果事件重复 | 不重复推进后继节点 |
| T09 | 节点事件乱序 | 状态机拒绝非法倒退 |
| T10 | 条件分支未命中 | 节点标记 SKIPPED，汇聚语义正确 |
| T11 | 并行分支部分失败 | 按声明的 join/failure 策略处理 |
| T12 | 审批等待期间重启 | 审批请求仍存在且可恢复 |
| T13 | 非授权审批 | 拒绝并生成审计记录 |
| T14 | 审批超时 | 进入预定义超时路径 |
| T15 | 取消正在运行的任务 | 停止新派发，记录不可撤销副作用 |
| T16 | 外部写操作重试 | 幂等或对账，避免盲目重复 |
| T17 | 租户 A 读取租户 B Run | 拒绝访问且不泄露数据 |
| T18 | 超过预算/迭代上限 | 明确终止或进入受控等待 |
| T19 | 调度器重启 | 从持久状态恢复待调度步骤 |
| T20 | Outbox 发布中断 | 事件最终重投且消费幂等 |
| T21 | 产物引用失效 | 产生可诊断错误并保留上下文 |
| T22 | 历史 Run 审计 | 可追溯版本、审批、节点与结果 |
验收原则： 不仅验证“流程跑通”，还要验证重复、乱序、失败、重启、权限、预算和版本演进。具体 SLA、恢复时间目标、并发与费用阈值需根据真实业务负载另行制定，本文不虚构数值。
十五、常见设计误区与自检
15.1 常见误区
- 把流程图当成运行引擎。 图形表达不等于具备持久化调度、失败语义与权限控制。
- 把 Workflow 与 Agent System 的内部规划混为一谈。 平台工作流应能承载非 Agent 节点和人工等待。
- 所有节点都使用“成功/失败”两态。 缺少等待、跳过、取消、超时会导致错误推进。
- 发布版本后让在途任务自动切换。 容易破坏长任务一致性与可追溯性。
- 假设队列保证恰好一次执行。 外部副作用必须独立处理。
- 审批等待占用 Worker。 应持久化等待并释放执行资源。
- 将节点输入输出全部写进消息队列。 大数据和敏感内容应通过受控产物引用传递。
- 无限返工和重试。 必须限制轮次、成本和总执行时间。
- 先建复杂通用画布再定义语义。 应先验证有限节点类型、对象模型与状态机。
- 忽略租户、角色与工具权限的差别。 工作流启动授权不能替代节点执行授权。
15.2 架构自检问题
- 是否区分 Definition、Draft、Version、Deployment/Binding、Run、Step Run 和 Attempt？
- 是否定义每种节点的输入输出、超时、失败与重试语义？
- 是否明确 DAG、循环、并行汇聚和人工等待的行为边界？
- 是否固定执行版本与依赖，并能重建历史运行上下文？
- 是否支持重复事件、Worker 崩溃和调度器重启后的安全恢复？
- 是否具备取消、暂停、审批和预算耗尽的受控处理路径？
- 是否将平台级权限与 Agent 内部工具权限分开校验？
- 是否能够从单个 Workflow Run 追踪到每个 Agent/工具执行及产物？
- 是否通过真实故障测试验证了关键假设，而不只依赖设计文档？
十六、与后续专题的衔接
P6 建立工作流定义、版本、触发、调度与运行治理的参考模型。后续 P7 Resource & Integration 将研究工作流节点所依赖的模型、工具和外部资源如何统一接入；P8 Platform API & SDK 将研究对外暴露的接口契约；P9 Extensibility & Ecosystem 将研究可插拔节点与扩展点；P10 Platform Data & Assets 将研究定义、事件和产物的统一存储与共享；P11、P12 分别深化租户隔离与平台治理。
产品侧，F3 研究开发调试体验，F5 研究 Workspace/Project，F6 研究执行交互，F7 研究多 Agent 协作，F8 研究运行监控，F10 研究产物交付。P6 解释这些产品能力背后的技术机制，不替代产品设计。
跨章节契约修订说明（v1.3-r1，2026-11-01）
本节是第五轮审核后的规范对齐补充，不代表前文所有局部示例已经被自动改写为统一 schema，也不代表完成工程测试。统一契约详见
04-Agent-Platform-Canonical-Contracts-v1.3-r1.md；当本文的参考状态、字段或接口示例与统一契约不一致时，应以统一契约作为后续实现候选基线，并在真正部署前完成迁移与验证。
工作流持久化与平台业务状态边界： [官方资料已核验，范围见第四轮审核] LangGraph 等运行时的 checkpoint 可用于图状态恢复，但跨进程恢复依赖实际持久化 checkpointer；平台应另行持久化 Run、Approval、ArtifactVersion、审计与版本引用。checkpoint 不保证外部工具副作用恰好一次。
异步可靠性契约： [平台设计决策/待测试] Run 状态与 Outbox 在同一数据库事务提交；消息至少一次投递；消费者按事件 ID 和业务状态版本去重；Worker 租约/fencing 防止旧 Worker 提交平台状态，但外部写操作必须独立执行幂等、回执核对或补偿。审批等待应进入统一 waiting + status_reason=approval，恢复时重新调度为 queued。
触发器幂等： 手动/API 触发与外部事件触发分别定义作用域、规范化请求摘要、保留期限和冲突策略；重复键不能跨租户匹配。原文的幂等键组合是参考建议，不是 HTTP 标准强制规定。
附录 A：参考文献与原始资料
以下资料优先选取官方技术文档或标准，用于核对术语、实现模式与技术边界。各平台能力会随版本变化；本文未对当前最新版本执行在线逐项核验。
- Temporal Documentation - Workflows、Activities、Retries、Signals、Updates、Versioning、Durable Execution。官方文档：<docs.temporal.io>。
- LangGraph Documentation - Graph API、Persistence、Interrupts、Durable Execution、Human-in-the-loop。官方文档：<docs.langchain.com/oss/python/langgraph/overview>。
- Argo Workflows Documentation - Kubernetes 原生工作流、DAG、Steps、Retry Strategy、Artifacts。官方文档：<argo-workflows.readthedocs.io>。
- Apache Airflow Documentation - DAG、Scheduling、Task Instances、Retries。官方文档：<airflow.apache.org/docs>。
- AWS Step Functions Developer Guide - State Machines、Standard/Express、Error Handling、Human Approval patterns。官方文档：<docs.aws.amazon.com/step-functions>。
- CloudEvents Specification - 事件格式与互操作约定。规范：<github.com/cloudevents/spec>。
- OpenTelemetry Documentation - Traces、Metrics、Logs 与 Context Propagation。官方文档：<opentelemetry.io/docs>。
- Kubernetes Documentation - Controllers、Jobs、CronJobs、Workload Management。官方文档：<kubernetes.io/docs>。
- PostgreSQL Documentation - Transactions、Constraints、Locking、Isolation。官方文档：<www.postgresql.org/docs>。
- OWASP Top 10 for LLM Applications - Agent/LLM 应用中不可信输入与工具使用的安全风险。项目：<genai.owasp.org>。
上述资料支持相关技术模式的存在与基本概念；本文提出的对象分类、字段、API、状态机、Studio 架构和测试清单属于综合性参考设计，并非这些来源共同规定的统一标准。
附录 B：研究证据、验证声明与适用边界
B.1 证据类型
- 通用工程事实： 分布式任务可能重复投递、网络故障造成状态不确定、长任务需要持久化恢复等，属于成熟分布式系统工程问题。
- 官方技术能力参考： Temporal、LangGraph、Argo、Airflow、Step Functions 等用于比较不同工作流与 Agent 编排能力的侧重点；具体功能以各自目标版本文档为准。
- 本文设计建议： Workflow Version 不可变、Run 固定版本、审批持久化、Outbox、参考 API、状态机和 Studio MVP 路线，属于面向 Agent Platform 的推荐方案，非强制行业规范。
- 案例推演： 研究报告 Studio 的流程、组件映射和故障情境用于架构推理，未代表已上线系统。
B.2 验证状态
- 已进行：目录与专题边界对照、文档结构检查、示例对象关系和流程逻辑的静态审阅。
- 未进行：对引用产品最新版本的联网功能核验、真实工作流引擎部署、API 调用、并发压测、故障注入、安全渗透测试和业务质量评估。
- 因此：本文不能作为某个具体框架的生产兼容性证明，也不能将“测试计划”解释为“测试通过”。
B.3 适用范围
适用于需要管理多个 Agent 或 Agent System、需要可复用工作流资产、长任务、人工审批、版本追踪和统一治理的 Agent Platform。对于单次模型调用、简单同步脚本或不需要独立工作流资产的小型应用，完整引入上述机制可能造成不必要的复杂度。
B.4 后续验证建议
优先在 Studio 的最小真实原型中完成 T04、T06、T07、T08、T12、T13、T16、T17、T19、T22 十项验证；在形成可靠的状态模型和执行契约后，再扩展复杂循环、插件节点与多租户开放能力。