変数と式

Braidrun のすべての動的値は「変数参照」を使用します。構文には 2 つの中括弧という形式が 1 つだけあります。

{{var:name}}                     # workflow 级变量
{{steps.fetch.data.user.name}}   # 上游步骤的 JSON 输出
{{classifier.category}}          # 分类器路由结果
{{credentials.openai_api_key}}   # 凭据库里的密钥

4 つの変数ソース

1. var: — ワークフローパラメータ

ワークフローの上部にある変数/パラメーター セクション、またはスケジュール/Webhook プリセットの入力。

variables:
  target_date:
    type: string
    default: "yesterday"
  top_n:
    type: number
    default: 10

steps:
  - id: fetch
    type: code
    code: |
      return { date: "{{var:target_date}}", top: {{var:top_n}} };

2. steps.id.* — 上流ステップからの出力

各ステップの実行後には構造化された出力が得られます。最も一般的に使用されるサブフィールド:

• steps.id.output — プレーンテキストまたは生の戻り値。
• steps.id.data — 抽出後の構造化された JSON。
• steps.id.artifacts[0].url — 製品ファイルのリンク。
• steps.id.tokens / cost / duration_ms — 実行統計。

steps:
  - id: fetch
    type: code
    extract:
      articles: $.items
      total: $.meta.total

  - id: summarize
    type: single
    agent: writer
    task: |
      我有 {{steps.fetch.data.total}} 条新闻，这是第一条：
      {{steps.fetch.data.articles[0].title}}

3. classifier.* — 分類子のルーティング結果

前の分類ステップの結果は、条件/分岐の第 1 レベルの参照として使用されます。

steps:
  - id: triage
    type: classifier
    agent: planner
    task: "{{var:user_message}}"
    categories: [billing, technical, other]

  - id: respond
    type: single
    condition: "{{classifier.category}} == 'billing'"
    agent: writer
    task: "客户关于账单的问题是：{{var:user_message}}"

steps.<classifier_step_id>.category と同等 - より短く、よりセマンティックなだけです。

4. credentials.* — 資格情報の参照

解決リンク: ユーザー名前空間 → チーム名前空間 → システム名前空間。詳細を見る 認証情報。

JSONパス式

単純なパス構文は中括弧内に記述できます。基本的には JSONPath のサブセットと互換性があります。

• {{steps.fetch.data.articles[0].title}} — 配列インデックス
• {{steps.fetch.data.articles[*].title}} — 配列のすべての要素 (配列を返します)
• {{steps.fetch.data.articles[?(@.score>5)]}} — 条件付きフィルタリング
• {{steps.fetch.data | length}} — filter：length / upper / lower / default / trim

抽出: ステップ出力を構造化する

LLM またはコードによって返されたデータは、多くの場合、下流で使用するために「いくつかのフィールドを選択する」必要があります。抽出を使用します。

- id: fetch_user
  type: code
  code: |
    const res = await fetch('https://api.example.com/me');
    return await res.json();
  extract:
    name: $.profile.fullName
    company: $.profile.org.name
    is_admin: $.permissions[?(@=='admin')] | length > 0

その後、steps.fetch_user.data.name / .company が直接利用できるようになります。

条件: 条件付き実行

どのステップにも条件を設定できます。式が false の場合、このステップはスキップされます (実行ステータスは SKIPPED とマークされます)。

- id: summarize
  type: single
  agent: writer
  condition: "{{classifier.category}} == 'ai' && length({{steps.fetch.data.articles}}) > 0"
  task: "..."

サポートされている演算子:

• 比較してください:== != < > <= >=
• ロジック:&& || !
• 文字列:contains(x, y) startsWith(x, y) endsWith(x, y) matches(x, /re/)
• 配列:length(x) any(list, cond) all(list, cond)
• 短い判断:isEmpty(x) isNotEmpty(x)

再試行: 再試行戦略

- id: fetch
  type: code
  code: "..."
  retry:
    max_attempts: 3
    backoff: exponential     # fixed | linear | exponential
    initial_delay_ms: 1000
    max_delay_ms: 30000
    retry_on: [network, rate_limit, http_5xx]

一時的な (ネットワーク/速度制限/5xx) エラーの場合にのみ再試行してください。ビジネス例外 (条件の失敗、LLM の拒否) は再試行されません。

集計: 複数の入力をマージします

ステップが複数の上流ソースからデータを収集する場合は、集約を使用します。たとえば、group_chat の後のコメントを要約します。

- id: combine
  type: code
  aggregate:
    comments: concat_lines({{steps.group_chat_1.messages}})
    total_tokens: sum({{steps.*.tokens}})
  code: "return { comments, total_tokens };"

利用可能な集計関数: concat/concat_lines/json_array/join(sep)/first/last/max/min/avg。

DTO 命名マッピング

YAML にはスネークケース (グループチャット、エージェントベース) を使用し、JSON API/DTO にはキャメルケース (グループチャット、エージェントベース) を使用します。プラットフォームは自動的に両方向に変換するため、心配する必要はありません。

よくある落とし穴

• 実行されていないステップへの参照 — 条件が上流のステップをスキップすると、それに対する下流の参照は null/未定義になります。使用 |デフォルト(...) を調べてください。
• 大きなフィールドはタスクに直接接続されます — task: "{{steps.x.output}}" アップストリーム出力が 100KB の場合、LLM はトークンをバーストします。送信する前に、まず抽出して圧縮します。
• YAML 内側の引用符 — コロンまたは特殊文字を含む式は二重引用符で囲む必要があります。 condition: "{{x}} == 1"