Variables y expresiones

Todos los valores dinámicos en Braidrun utilizan "referencias variables". La sintaxis tiene una sola forma: llaves dobles.

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

Cuatro fuentes de variables

1. var: — Parámetros de flujo de trabajo

La sección de variables/parámetros en la parte superior del flujo de trabajo, o la entrada del preajuste de programación/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.* — Salida del paso aguas arriba

Hay una salida estructurada después de ejecutar cada paso. Los subcampos más utilizados:

• steps.id.output — Texto sin formato o valor de retorno sin formato.
• steps.id.data — JSON estructurado después del extracto.
• steps.id.artifacts[0].url — Enlace al archivo del producto.
• steps.id.tokens / cost / duration_ms — Estadísticas de ejecución.

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.* — Resultados de enrutamiento del clasificador

El resultado del paso del clasificador anterior se utiliza como referencia de primer nivel para la condición/ramificación.

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

Equivalente a pasos.<classifier_step_id>.category - sólo que más corto y más semántico.

4. credentials.* — Referencia de credencial

Enlace de resolución: Espacio de nombres de usuario → Espacio de nombres de equipo → Espacio de nombres del sistema; ver detalles Credenciales.

Expresión jsonpath

La sintaxis de ruta simple se puede escribir entre llaves, básicamente compatible con un subconjunto de JSONPath:

• {{steps.fetch.data.articles[0].title}} — índice de matriz
• {{steps.fetch.data.articles[*].title}} — Todos los elementos de la matriz (matriz de retorno)
• {{steps.fetch.data.articles[?(@.score>5)]}} — Filtrado condicional
• {{steps.fetch.data | length}} — filter：length / upper / lower / default / trim

Extraer: estructurar la salida del paso

Los datos devueltos por LLM o el código a menudo necesitan "seleccionar algunos campos" para su uso posterior. Usar extracto:

- 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

Después de eso,steps.fetch_user.data.name/.company estará disponible directamente.

Condición: ejecución condicional

Cualquier paso puede tener una condición: cuando la expresión es falsa, este paso se omite (el estado de ejecución se marca SKIPPED).

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

Operadores soportados:

• Comparar:== != < > <= >=
• Lógica:&& || !
• Cadena:contains(x, y) startsWith(x, y) endsWith(x, y) matches(x, /re/)
• Matriz:length(x) any(list, cond) all(list, cond)
• Juicio breve:isEmpty(x) isNotEmpty(x)

Reintentar: estrategia de reintento

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

Vuelva a intentarlo solo en caso de errores transitorios (red/límite de velocidad/5xx). No se volverán a intentar las excepciones comerciales (fallo de condición, rechazo de LLM).

Agregado: fusionar múltiples entradas

Utilice agregado cuando un paso recopila datos de múltiples fuentes ascendentes. Por ejemplo, resuma los comentarios después de 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 };"

Funciones agregadas disponibles: concat/concat_lines/json_array/join(sep)/first/last/max/min/avg.

Mapeo de nombres DTO

Utilice Snake_case (group_chat, agent_based) para YAML y camelCase (groupChat, agentBased) para JSON API/DTO. La plataforma convierte automáticamente en ambas direcciones, no tienes que preocuparte.

Errores comunes

• Referencia a un paso que no se ha ejecutado — Si la condición omite el paso ascendente, las referencias descendentes serán nulas/indefinidas. Uso | default(...) para averiguarlo.
• Los campos grandes se conectan directamente a las tareas — task: "{{steps.x.output}}" Si la salida ascendente es de 100 KB, LLM explotará el token. Primero extraiga y comprima antes de transmitir.
• YAML comillas dentro — Las expresiones que contienen dos puntos o caracteres especiales deben ir entre comillas dobles: condition: "{{x}} == 1"