跳转到主要内容
文档构建工作流步骤类型

8 种步骤类型

单 Agent、group_chat、agent_based、code、classifier、state_machine、sub_workflow、manual_approval 的用法与字段参考。

Braidrun 当前提供 8 种步骤类型。每个步骤必须且只能选择一种主模式；其他字段属于增强（retry、condition、manual_approval 等）。

1. single — 单 Agent

最常见的步骤：让一个 Agent 执行一段任务。

yaml
  - step: plan
    agent: planner
    input: "Plan a daily report pipeline"
    depends_on: [intro]
    retry:
      maxAttempts: 3
      backoff: exponential

允许的组合增强： parallel、repeat_until、iterate_over。

2. group_chat — 多代理讨论

多个 Agent 围绕同一个议题轮流发言。可以指定说话顺序，也可以让 orchestrator 决定。

yaml
  - step: peer_review
    group_chat:
      agents: [coder, reviewer]
      topic: "Review the change"
      max_rounds: 6
      repeat_until: "score >= 8"

repeat_until 的条件表达式会在每轮结束后求值；满足则结束 group_chat。

3. agent_based — 动态委派

orchestrator Agent 在运行时选择 worker 并分派子任务。相比静态 group_chat，更适合"我不知道谁合适，让 planner 决定"的场景。

yaml
  - step: delegate
    agent_based:
      orchestrator: planner
      workers: [coder, analyst, writer]
      input: "{{steps.plan.output}}"

4. code — 确定性脚本

支持 7 种语言：Python / JavaScript / TypeScript / Bash / Ruby / Lua / CLI。生产环境下默认跑在沙箱容器里。

yaml
code_preamble:
  python:
    inline: |
      import json, os

workflow:
  - step: transform
    code:
      language: python
      timeout: 30
      script: |
        data = json.loads(os.environ.get("STEP_INPUTS", "{}"))
        print(json.dumps({"rows": len(data)}))
共享代码前置

多个 code 步骤需要共享 import 或工具函数时，使用顶层的 code_preamble，按编程语言分组，运行时会自动拼到相同语言的 code 步骤脚本前面。

5. classifier — 路由变量

让 Agent 把"当前上下文属于哪类"作为输出，并写入一个路由变量，给后续步骤 condition 使用。

yaml
  - step: classify_request
    classifier:
      agent: router
      input: "Classify the user intent"
      categories:
        - name: coding
          description: Needs code changes
        - name: analysis
          description: Needs investigation only
      output_variable: route

  - step: coding_path
    agent: coder
    condition: route == coding
    depends_on: [classify_request]

推荐用 classifier + condition 代替复杂的 on_success.next 字符串数组。

6. state_machine — 嵌套状态机

作为 DAG 复合节点运行，内部可以有若干状态和转移。

yaml
  - step: triage
    state_machine:
      initial: ingest
      states:
        - name: ingest
          agent: planner
          transitions:
            - condition: route == analysis
              next: analyze
            - condition: route == coding
              next: code
        - name: analyze
          agent: analyst
          transitions:
            - next: DONE
        - name: code
          agent: coder
          transitions:
            - next: DONE

外层步骤不要再配置 parallel；进入 state_machine 的流量就是一条。

7. sub_workflow — 子工作流模块

调用另一个已发布的 Module。输入 / 输出遵守 module 声明的契约；运行时做环路检测。

yaml
  - step: fetch_report
    sub_workflow:
      workflow_id: 0d2c…ab12        # UUID of the published module
      version_strategy: pinned
      pinned_version: "2.0.1"
      inputs:
        app_id: "{{var:app_id}}"
        window: last_7d
      outputs:
        report_path: report_path    # parent variable <- module output

列出所有内置 module： 内置模块库。

8. workflow_output_read — 跨工作流读取

系统级步骤：从另一个工作流某次执行发布的输出（见下文 publish_outputs）里读取值，写入本工作流的变量。默认读取来源工作流最近一次成功执行。

yaml
  - step: read_spend_report
    workflow_output_read:
      workflow_id: 7f3a…9c21           # source workflow UUID
      selector:
        mode: latest_successful
      outputs:
        report_url: spend_report_url   # published name -> local variable
      missing_policy: use_default
      defaults:
        report_url: ""
  • selector.mode — 默认 latest_successful（最近一次成功执行）；也可用 execution_id 指定某次执行，或 input_variable 从变量里取 execution id
  • outputs — 必填：发布输出名到本工作流变量名的映射
  • missing_policy — 输出缺失时：fail（默认，步骤报错）、skip_step（跳过本步骤）、use_default（取 defaults 里的默认值）
  • require_workflow_status — 默认要求来源执行状态为 COMPLETED

步骤级增强

以下字段不是独立的步骤类型，而是加在步骤上的增强配置。

manual_approval — 人工审批

在任意步骤前加人工门控：执行暂停并通知审批人，批准后继续，拒绝或超时则停止。

yaml
  - step: deploy
    agent: deployer
    input: "Deploy to production"
    manual_approval:
      enabled: true
      approvers:
        - team-lead@company.com
      timeout: 3600
      approval_message: "Ready to ship?"

查看完整参数表和审批流程： 人工审批。

publish_outputs — 对外发布步骤输出

步骤成功后，把命名输出发布出去，供其他工作流用 workflow_output_read 读取。默认不发布任何内部产物。

yaml
  - step: build_report
    agent: analyst
    input: "Summarize yesterday's spend"
    publish_outputs:
      - name: report_url
        type: url
        source: "{{steps.build_report.output}}"
        description: Latest spend report link
        visibility:
          scope: team
  • source — 必填：模板表达式，发布时求值，例如引用本步骤的输出
  • type — 默认 text，还支持 markdown、json、number、boolean、url、file 等
  • visibility.scope — private（默认，仅本工作流所有者）、team、workflow_allowlist（配合 allowed_workflows 白名单）

structured_output — 结构化最终输出

仅单 Agent 步骤可用：Agent 照常调用工具，但最终回复会按已注册的 schema 解析成结构化结果；配置 write_to 时还会把结果序列化写入文件。

yaml
  - step: final_commentary
    agent: analyst
    input: "Write the commentary"
    structured_output:
      schema: ai_commentary_parts
      write_to: "{{var:output_dir}}/commentary.json"
      fail_on_empty: true
  • schema — 必填：已注册的结构化 schema 名称
  • write_to — 可选：写入的文件路径，支持模板变量；写入格式目前仅支持 json
  • fail_on_empty — 结构化结果为空时是否让步骤失败，默认 true

组合限制速览

  • parallel — 仅单 Agent 步骤可配置
  • repeat_until — 仅单 Agent 或 group_chat
  • iterate_over — 仅单 Agent 或 code
  • structured_output — 仅单 Agent 步骤
  • state_machine — 作为 DAG 复合节点运行，外层不要再配 parallel