DocsBuild WorkflowYAML Syntax

YAML Syntax Reference

Variable references, conditional expressions, agent preset, code_preamble - the complete and authoritative reference for Braidrun YAML.

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.

Authoritative Parser

Verification and YAML round-trip both use the platform parsing interface /api/workflows/parse , to avoid writing another set of rules on the browser side.

Naming: Camelcase ↔ snake_case

Web JSON uses camelCase; execution YAML uses snake_case:

Web DTO	YAML
`groupChat`	`group_chat`
`agentBased`	`agent_based`
`stateMachine`	`state_machine`
`repeatUntil`	`repeat_until`
`iterateOver`	`iterate_over`
`manualApproval`	`manual_approval`
`onSuccess` / `onFailure`	`on_success` / `on_failure`

Agent Presets And Overrides

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

yaml

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

Variable Reference

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

yaml

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:

yaml

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:

yaml

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

Parenthesized grouping isn't supported — when you need more complex grouping logic, use classifier to produce a routing variable or split it into multiple steps. Write variable names plainly; don't use template-variable syntax inside a condition. A condition that can't be parsed is treated as false, and the step is skipped.

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:

yaml

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

Or use the inline form:

yaml

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:

yaml

on_success:
  - next: publish

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

When exported as Web DTO, it corresponds to:

json

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

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