Variables and Expressions

Variables pass execution input, upstream step output, and runtime results to subsequent steps. The editor checks for common citation errors and provides variable completion when available.

{{var:company_name}}              # 工作流变量
{{steps.fetch.output}}            # 上游步骤原始输出
{{steps.fetch.output.total}}      # JSON 输出的顶层字段
{{risk_level}}                    # classifier / extract 等写出的运行时变量

Three common references

1. var: — Workflow Variables

Declare default values in top-level variables; manual execution, cron tasks, or API calls can override these values at startup. variable_types is a type table parallel to variables. Do not nest type/default in variable values.

variables:
  target_date: "yesterday"
  top_n: "10"

variable_types:
  target_date: string
  top_n: number

workflow:
  - step: prepare
    code:
      language: python
      script: |
        import os
        date = os.environ["WF_VAR_TARGET_DATE"]
        top_n = int(os.environ["WF_VAR_TOP_N"])
        print(f"date={date}, top_n={top_n}")

2. steps.<step>.output — Upstream step output

When referencing the raw output of other steps, use the full step name and use depends_on to clarify data dependencies. If the output is a JSON object, top-level fields can also be referenced.

workflow:
  - step: fetch
    code:
      language: python
      script: |
        import json
        print(json.dumps({"total": 2, "items": ["A", "B"]}))

  - step: summarize
    agent: writer
    depends_on:
      - fetch
    input: |
      共找到 {{steps.fetch.output.total}} 条记录：
      {{steps.fetch.output}}

3. {{risk_level}} — Runtime Variables

extract, classifier, iterate_over, aggregate, and sub-workflow outputs will write the results to the specified variable name. Subsequent steps can directly reference the variable, or write it in the var: prefix form.

workflow:
  - step: classify_risk
    classifier:
      agent: risk_classifier
      input: "{{var:report_text}}"
      categories:
        - name: high
          description: "需要立即处理"
        - name: low
          description: "可进入常规队列"
      output_variable: risk_level
      default_category: low

  - step: urgent_review
    agent: reviewer
    depends_on:
      - classify_risk
    condition: "risk_level == 'high'"
    input: "请复核：{{var:report_text}}"

extract: Write the output into a variable

extract is a list; each item uses a regular expression or JSON Path to extract the value from the current step output and saves the name specified by variable.

workflow:
  - step: fetch_user
    code:
      language: python
      script: |
        print('NAME=Alex')
        print('ROLE=admin')
    extract:
      - pattern: 'NAME=(.*)'
        variable: user_name
      - pattern: 'ROLE=(.*)'
        variable: user_role

  - step: greet
    agent: writer
    depends_on:
      - fetch_user
    input: "请欢迎 {{user_name}}，其角色是 {{user_role}}。"

condition: control whether a step runs

A step can define a condition. When it evaluates to false, the step is marked SKIPPED. The expression can use variables that have already been produced.

workflow:
  - step: notify_owner
    agent: writer
    condition: "risk_level == 'high'"
    input: "生成一条高风险通知"

retry: Step retry

workflow:
  - step: fetch_remote_data
    code:
      language: python
      script: |
        # 调用可安全重试的只读接口
        print("ok")
    retry:
      max_attempts: 3
      backoff: exponential
      initial_delay: 1000
      max_delay: 30000
    idempotent: true

The maximum number of times, backoff method and delay can be configured. Whether retrying is suitable also depends on whether the step is idempotent; steps that will send messages, charge money, or modify external data should first design a deduplication mechanism.

aggregate: merge multiple sources

aggregate receives multiple template sources and writes the combined results into output_variable. Available strategies include concat, json_array, numbered_list, pick_longest, and pick_shortest.

workflow:
  - step: combine_reports
    depends_on:
      - research
      - review
    aggregate:
      sources:
        - "{{steps.research.output}}"
        - "{{steps.review.output}}"
      strategy: numbered_list
      output_variable: combined_report

A credential selector is not a plaintext variable

To use a key in a code step, declare credential:<provider> in variable_types. The variable stores only an optional credential ID. At runtime, the plaintext value is injected through the WF_CREDENTIAL_<PROVIDER> environment variable; there is no plaintext credentials.* expression.

variables:
  openrouter_credential_id: ""

variable_types:
  openrouter_credential_id: credential:openrouter

View full instructions for credential management

FAQ

• Variable not declared — Add default values in variables first; variables generated by nodes such as extract should also use unique and clear names.
• The step name is written incorrectly — The steps reference must be exactly the same as the step in the workflow.
• Missing dependencies — When referencing the upstream output, also add the upstream step to depends_on.
• Sensitive values are written into variables — variables will be saved with the workflow and are not suitable for storing keys; please use Credential Center.
• Large output is directly passed to the model — First use the extract or code step to organize necessary fields to avoid irrelevant content occupying the model context.