변수 및 표현식

Braidrun의 모든 동적 값은 "변수 참조"를 사용합니다. 구문에는 이중 중괄호라는 한 가지 형식만 있습니다.

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

변수의 네 가지 소스

1. var: — 작업흐름 매개변수

워크플로 상단의 변수/매개변수 섹션 또는 일정/웹훅 사전 설정의 입력입니다.

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.* — 분류기의 라우팅 결과

이전 분류기 단계의 결과는 조건/분기에 대한 첫 번째 수준 참조로 사용됩니다.

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.* — 자격 증명 참조

Resolution link: User namespace → Team namespace → System namespace; 세부정보 보기 자격 증명.

JSONPath 표현식

간단한 경로 구문은 중괄호로 작성할 수 있습니다. 기본적으로 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에는 snake_case(group_chat, Agent_based)를 사용하고 JSON API/DTO에는 camelCase(groupChat, AgentBased)를 사용합니다. 플랫폼은 자동으로 양방향으로 변환되므로 걱정할 필요가 없습니다.

일반적인 함정

• 실행되지 않은 단계에 대한 참조 — 조건이 업스트림 단계를 건너뛰면 이에 대한 다운스트림 참조가 null/정의되지 않음을 얻습니다. 사용 | default(...)를 알아보세요.
• 대규모 필드가 작업에 직접 연결됩니다. — task: "{{steps.x.output}}" 업스트림 출력이 100KB이면 LLM이 토큰을 버스트합니다. 전송하기 전에 먼저 압축을 풀고 압축하세요.
• YAML 안쪽에 따옴표 — 콜론이나 특수 문자가 포함된 표현식은 큰따옴표로 묶어야 합니다. condition: "{{x}} == 1"