跳轉到主要內容
文件建構工作流程步驟類型

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