ドキュメントワークフローの構築YAML 構文

YAML 構文リファレンス

変数参照、条件式、エージェントプリセット、code_preamble - Braidrun YAML の完全かつ信頼できるリファレンス。

Braidrun の Web DTO は YAML バイトレベルのラウンドトリップを実行しますが、異なるフィールド命名スタイルを使用します。 camelCase vs snake_case。このページでは、知っておく必要があるマッピング、変数、条件、事前設定ルールについてわかりやすく説明します。

権威のあるパーサー

検証と YAML ラウンドトリップは両方ともプラットフォーム解析インターフェイスを使用します /api/workflows/parse 、ブラウザ側で別のルールのセットを作成することを避けるため。

命名: キャメルケース ↔ スネークケース

Web JSON はキャメルケースを使用します。 YAML の実行では、snake_case を使用します。

ウェブ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`

エージェントのプリセットとオーバーライド

プリセットを使用してエージェントを宣言し、必要に応じてオーバーライドを使用してフィールドをカバーすることをお勧めします。

yaml

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

変数参照

ワークフロー変数: {{var:name}}
ステップ出力: {{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]

条件式（条件）

基本形式は「左辺演算子右辺」で、演算子の両側には必ずスペースを入れる必要があります。対応する演算子は以下のとおりです。

== / != — 文字列の完全一致比較、大文字と小文字を区別
> < >= <= — 数値比較。いずれかの側が数値でない場合、その条件は false として扱われます
contains / contains_cs — 包含判定、大文字と小文字を区別
contains_ci — 包含判定、大文字と小文字を区別しない

複数の比較はトップレベルで以下を使って組み合わせられます &&（かつ）と ||（または）で組み合わせます。 && の優先度が高く、先に結合されます。例:

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

書かないでください:

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

括弧によるグループ化には対応していません。より複雑なグループ化ロジックが必要な場合は、以下を使用します classifier ルーティング変数を生成するか、複数ステップに分割します。変数名は直接記述すればよく、condition 内でテンプレート変数構文を使用しないでください。解析できない条件は false として扱われ、そのステップはスキップされます。

code_preamble — 共有コードプリアンブル

複数の code ステップで import やユーティリティ関数を共有する必要がある場合は、トップレベルの code_preamble を使用します。プログラミング言語ごとにグループ化され、実行時に同じ言語の code ステップスクリプトの先頭に自動的に連結されます。

yaml

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

または、インラインフォームを使用します。

yaml

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

Transition Action（on_success / on_failure）

文字列配列の代わりにアクションオブジェクト形式を使用します。

yaml

on_success:
  - next: publish

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

Web DTO としてエクスポートされる場合、以下に対応します。

json

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

句リストの検証

変数参照の使用法 {{var:name}}
エクスポートされた YAML は引き続き合格します /api/workflows/parse 読み返す
condition にテンプレート変数を書いておらず、&& / || の組み合わせに括弧を使用していません
manualApproval / onFailure / repeatUntil DTO フィールドがエクスポートされると、snake_case に変換されます。