Write a Jinba Flow Workflow Manifest in YAML

Define workflow steps, tool inputs, dependencies, conditions, and loops in a Jinba Flow manifest.

A flow manifest is a YAML document with a flow name and an ordered list of steps. Each tool step has an ID, a tool ID, and an input list. Use the tool’s documentation to confirm its accepted inputs and configuration.

The code panel. Edit the entire flow directly as a YAML manifest

A runnable example

This flow accepts text and returns it in a greeting:

name: First workflow
steps:
  - id: name
    tool: INPUT_TEXT
    input:
      - name: value
        value: Jinba

  - id: greeting
    tool: OUTPUT_TEXT
    needs:
      - name
    input:
      - name: value
        value: "Hello, {{ steps.name.result }}!"

Flow and step fields

Field	Where	Purpose
name	Flow	Required flow name
description	Flow	Optional description of what the flow does
steps	Flow	Required list of steps
id	Step	Required unique identifier; use letters, numbers, underscores, or hyphens. __proto__, constructor and prototype are reserved
name	Step	Optional display name shown in the editor
description	Step	Optional note explaining what the step does
tool	Tool step	Tool ID from the Jinba Flow tool catalog
input	Tool step	List of name and value pairs accepted by that tool
config	Tool step	Optional list of tool-specific configuration values
needs	Step	IDs of steps that must finish before this step runs
when	Step	Optional CEL expression; a falsy result skips the step
forEach	Step	Optional expression that supplies an array to process item by item

A tool step must include input, even when it has no values to pass. For example, use input: [] for a tool that takes no inputs. Include only fields supported by the selected tool.

Configure a tool

config uses the same name and value list as input. Configuration values can reference secrets but not step results:

config:
  - name: <config_name>
    value: "{{ secrets.<SECRET_NAME> }}"

Set the execution order

Steps run in the order set by needs, not by their position in the file. Steps with no needs start together.

• A step waits for every step listed in needs. Referencing steps.<id> in an input does not make the step wait; list that ID in needs.
• Branches can split and rejoin. A step can need two steps that both need the same earlier step.
• Circular dependencies are rejected with Flow contains circular dependencies.
• If a step in needs fails or is cancelled, the dependent step is cancelled. If every step in needs was skipped, the dependent step is skipped too.

Pass a previous step’s result

Use the step ID and its result to reference an earlier output. The result’s shape depends on the tool; check that tool’s documentation before selecting a nested field.

  - id: greeting
    tool: OUTPUT_TEXT
    needs: [name]
    input:
      - name: value
        value: "Hello, {{ steps.name.result }}!"

The needs list makes the dependency explicit. Step IDs also identify flow inputs: when calling a published flow, use the input step’s ID as the argument name.

Values available in templates:

Reference	Value
{{ steps.<step_id>.result }}	The whole result of an earlier step
{{ steps.<step_id>.result.<field> }}	One field of that result; array elements use [0]
{{ secrets.<SECRET_NAME> }}	A workspace secret
{{ item }}, {{ itemIndex }}, {{ itemCount }}	The current element, its zero-based position, and the array length in a forEach step

A {{ steps.<step_id>.result... }} placeholder that resolves to an object or array is inserted as JSON text. Strings are inserted as-is, and a missing value becomes an empty string. See Variables & Templates for more patterns.

Conditions and loops

Use CEL directly for a condition. For example, this expression runs a step when an earlier result has a truthy isValid field:

when: "steps.check.result.isValid"

A condition can also use {{ }} placeholders. They are filled in first, and the resulting text is evaluated as CEL, so quote text values:

when: "'{{ steps.check_genre.result.content }}' == 'General'"
when: "{{ steps.count_items.result }} > 5"

If the condition cannot be evaluated, for example because it refers to a missing field, the step fails with Failed to evaluate when condition on step '<step_id>'.

Use forEach to run a step for each item in an array. The current item is available as item in supported expressions:

forEach: "{{ steps.get_items.result }}"

Later steps read steps.<step_id>.result as an array of the successful items’ results. See Step Module Options for more needs, when, and forEach examples.

Templates

Input values are rendered as Nunjucks templates before the step runs. Besides {{ }} placeholders, you can use loops, conditions, and filters:

- name: prompt
  value: |
    Review these items:
    {%- for entry in steps.get_items.result.items %}
    - {{ entry.name }}
    {%- endfor %}
    {%- if steps.check.result.status == 'urgent' %}
    Flag anything that needs a reply today.
    {%- endif %}

• {%- and -%} remove the whitespace before or after a tag.
• Inside a loop, loop.index is the 1-based position.
• Built-in filters include default('<fallback>'), upper, lower, trim, replace('<old>', '<new>'), length, and join(', ').
• json outputs strict JSON. A placeholder with a filter is not converted to JSON automatically, so add | json when the value is an object.
• For a forEach result, successful, failed, results, and pluck('<field>') filter or extract per-item outputs.

Python’s zip() and inline loop filters such as for x in items if ... are not supported; use an {% if %} block inside the loop instead.

Multi-line values

Use | in YAML for a value that spans several lines, such as code or a prompt. The value continues until the indentation ends. |- does the same but drops the final line break.

Example: split and combine

This flow reads a list of numbers, sums the even and odd numbers in parallel, and combines the results:

name: Sum numbers
steps:
  - id: input_data
    tool: INPUT_JSON
    input:
      - name: value
        value: '{"numbers": [1, 2, 3, 4, 5]}'

  - id: sum_even
    tool: PYTHON_SANDBOX_RUN
    needs: [input_data]
    input:
      - name: code
        value: |
          data = {{ steps.input_data.result }}
          sum(x for x in data["numbers"] if x % 2 == 0)
      - name: data_type
        value: NUMBER

  - id: sum_odd
    tool: PYTHON_SANDBOX_RUN
    needs: [input_data]
    input:
      - name: code
        value: |
          data = {{ steps.input_data.result }}
          sum(x for x in data["numbers"] if x % 2 != 0)
      - name: data_type
        value: NUMBER

  - id: combine
    tool: PYTHON_SANDBOX_RUN
    needs: [sum_even, sum_odd]
    input:
      - name: code
        value: "{{ steps.sum_even.result.data }} * 2 + {{ steps.sum_odd.result.data }}"
      - name: data_type
        value: NUMBER

• input_data returns the parsed JSON object.
• sum_even and sum_odd both need only input_data, so they run at the same time. The last line of the code is the result, available as result.data (6 and 9).
• combine waits for both branches and returns 21.

Validate a manifest

If a flow does not validate or run:

• Check that each step ID is unique and contains only letters, numbers, underscores, or hyphens.
• Check that each tool ID and input name exists in that tool’s documentation.
• Check that every referenced step ID exists and is listed under needs.
• Check that result references use the output shape documented for that tool.
• Check that YAML indentation is consistent.

See the tool catalog for tool IDs and inputs, and Debug for validation error messages.