YAML Syntax Reference

Braidrun's Web DTO performs YAML byte-level round-trip, but uses a different field naming style: camelCase vs snake_case. This page explains clearly the mapping, variables, conditions, and preset rules you need to know.

Naming: camelCase ↔ snake_case

Web JSON uses camelCase; execution YAML uses snake_case:

Agent Presets And Overrides

It is recommended to use preset to declare Agent, and use overrides to cover any fields when necessary:

agents:
  planner:
    preset: universal
  coder:
    preset: coder
    overrides:
      max_iterations: 2000

Variable Reference

• Workflow variables: {{var:name}}
• Step output: {{steps.step_name.output}}

variables:
  topic: workflow

workflow:
  - step: plan
    agent: planner
    input: "Plan for {{var:topic}}"

  - step: implement
    agent: coder
    input: "Implement based on {{steps.plan.output}}"
    depends_on: [plan]

Conditional Expression (Condition)

The basic form is "left operator right," and the operator must have spaces on both sides. Supported operators:

• == / != — Exact string comparison, case-sensitive
• > < >= <= — Numeric comparison; if either side isn't a number, the condition is treated as false
• contains / contains_cs — Contains check, case-sensitive
• contains_ci — Contains check, case-insensitive

Multiple comparisons can be combined at the top level with &&(and) and ||(or); && binds tighter and is grouped first. Example:

condition: route == coding
condition: score >= 8
condition: status == done && score >= 8
# && binds tighter — reads as (a == 1 && b != done) || retry == true
condition: a == 1 && b != done || retry == true

Don't write:

condition: "{{var:route}} == coding"      # don't — write the variable name directly
condition: (a == 1 || b == 2) && c == 3   # don't — parentheses are not supported

code_preamble — Shared Code Preamble

When multiple code steps need to share imports or helper functions, use the top-level code_preamble. It's grouped by programming language and, at run time, automatically prepended to the scripts of code steps in the same language:

code_preamble:
  python:
    ref: ./lib/shared_utils.py

Or use the inline form:

code_preamble:
  python:
    inline: |
      import json, os
      def log(msg):
          print(f"[workflow] {msg}")

Transition Action（on_success / on_failure）

Use action object form instead of string array:

on_success:
  - next: publish

on_failure:
  - notify: slack
    message: implementation failed
    stop: true

When exported as Web DTO, it corresponds to:

{
  "onSuccess": [{"next": "publish"}],
  "onFailure": [
    {
      "notify": "slack",
      "message": "implementation failed",
      "stop": true
    }
  ]
}

Top-level workflow fields

Beyond the required name / description / version / variables / agents / workflow, the top level accepts a set of optional settings:

Steps have no type field

This is the easiest thing to get wrong: a step's primary execution mode is not declared with type — it is decided by which key is present.

Stackable enhancer fields

These are not primary modes but modifiers you can attach to any step, and they combine freely:

Verify Clause List

• Variable reference usage {{var:name}}
• Exported YAML still passes /api/workflows/parse Read Back
• The condition has no template variables, and the && / || combination uses no parentheses
• manualApproval / onFailure / repeatUntil After the DTO field is exported, it has been converted into snake_case