Variablen und Ausdrücke

Alle dynamischen Werte in Braidrun verwenden „Variablenreferenzen“. Die Syntax hat nur eine Form: doppelte geschweifte Klammern.

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

Vier Variablenquellen

1. var: — Workflow-parameter

Der Abschnitt „Variablen/Parameter“ oben im Workflow oder die Eingabe der Zeitplan-/Webhook-Voreinstellung.

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.* — Ausgabe vom vorgelagerten Schritt

Nach der Ausführung jedes Schritts erfolgt eine strukturierte Ausgabe. Die am häufigsten verwendeten Unterfelder:

• steps.id.output — Nur-Text oder roher Rückgabewert.
• steps.id.data — Strukturiertes JSON nach dem Extrahieren.
• steps.id.artifacts[0].url — Link zur Produktdatei.
• steps.id.tokens / cost / duration_ms — Ausführungsstatistik.

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.* — Routing-ergebnisse des Klassifikators

Das Ergebnis des vorherigen Klassifikationsschritts wird als Referenz der ersten Ebene für die Bedingung/Verzweigung verwendet.

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}}"

Entspricht „steps.<classifier_step_id>.category“ – nur kürzer und semantischer.

4. credentials.* — Referenz zur Referenz

Lösungslink: Benutzer-Namespace → Team-Namespace → System-Namespace; siehe Details Zugangsdaten.

Jsonpath-ausdruck

Eine einfache Pfadsyntax kann in geschweiften Klammern geschrieben werden – grundsätzlich kompatibel mit einer Teilmenge von JSONPath:

• {{steps.fetch.data.articles[0].title}} — Array-Index
• {{steps.fetch.data.articles[*].title}} — Alle Elemente des Arrays (Rückgabearray)
• {{steps.fetch.data.articles[?(@.score>5)]}} — Bedingte Filterung
• {{steps.fetch.data | length}} — filter：length / upper / lower / default / trim

Extrahieren: Strukturieren Sie die Schrittausgabe

Für die von LLM oder Code zurückgegebenen Daten müssen häufig „einige Felder“ für die nachgelagerte Verwendung ausgewählt werden. Extrakt verwenden:

- 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

Danach ist „steps.fetch_user.data.name / .company“ direkt verfügbar.

Bedingung: bedingte Ausführung

Jeder Schritt kann eine Bedingung haben – wenn der Ausdruck falsch ist, wird dieser Schritt übersprungen (der Ausführungsstatus wird als SKIPPED markiert).

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

Unterstützte Betreiber:

• Vergleichen Sie:== != < > <= >=
• Logik:&& || !
• Zeichenfolge:contains(x, y) startsWith(x, y) endsWith(x, y) matches(x, /re/)
• Array:length(x) any(list, cond) all(list, cond)
• Kurzes Urteil:isEmpty(x) isNotEmpty(x)

Wiederholung: Wiederholungsstrategie

- 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]

Versuchen Sie es nur bei vorübergehenden Fehlern (Netzwerk/Geschwindigkeitsbegrenzung/5xx). Geschäftsausnahmen (Bedingungsfehler, LLM-Ablehnung) werden nicht wiederholt.

Aggregat: Mehrere Eingaben zusammenführen

Verwenden Sie Aggregat, wenn ein Schritt Daten aus mehreren Upstream-Quellen sammelt. Fassen Sie beispielsweise die Kommentare nach „group_chat“ zusammen:

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

Verfügbare Aggregatfunktionen: concat/concat_lines/json_array/join(sep)/first/last/max/min/avg.

Dto-namenszuordnung

Verwenden Sie Snake_case (group_chat, agent_based) für YAML und camelCase (groupChat, agentBased) für JSON API/DTO. Die Plattform konvertiert automatisch in beide Richtungen, Sie müssen sich keine Sorgen machen.

Häufige Fallstricke

• Verweis auf einen Schritt, der nicht ausgeführt wurde — Wenn die Bedingung den Upstream-Schritt überspringt, werden Downstream-Verweise darauf null/undefiniert. Verwenden Sie | default(...) um es herauszufinden.
• Große Felder werden direkt an Aufgaben angeschlossen — task: "{{steps.x.output}}" Wenn die Upstream-Ausgabe 100 KB beträgt, wird LLM das Token platzen lassen. Vor der Übertragung zunächst extrahieren und komprimieren.
• YAML Anführungszeichen im Inneren — Ausdrücke, die Doppelpunkte oder Sonderzeichen enthalten, sollten in doppelte Anführungszeichen gesetzt werden: condition: "{{x}} == 1"