Documentation

Sub-workflows

A sub-workflow step runs another saved workflow as part of your current workflow. You build the child once, then call it from any parent workflow — like dropping a reusable mini-process into a larger automation.

The parent workflow waits until the child finishes, then continues with the next step.

When to use sub-workflows

Good reasons to split work across two workflows:

  • Repeat the same action in several places — for example, “look up workspace details” — without copying steps every time.
  • Keep parent workflows readable by hiding detail inside a child workflow.
  • Share one child across many parents, each passing different input values.

Two workflows you need

Every sub-workflow setup uses two workflows:

WorkflowRole
ChildThe reusable process. Defines its own workflow inputs and workflow outputs.
ParentCalls the child via a Subworkflow step. Passes values in; reads results out.
flowchart LR
  parentInputs[Parent workflow inputs] --> subStep[Sub-workflow step]
  subStep --> childInputs[Child workflow inputs]
  childInputs --> childSteps[Child steps run]
  childSteps --> childOutputs[Child workflow outputs]
  childOutputs --> subOutputs[Sub-workflow step outputs]
  subOutputs --> parentOutputs[Parent workflow outputs]

Step 1 — Build the child workflow

Create a normal workflow first. A manual trigger is fine.

  1. Go to Workflows → Create workflow and save the child with a clear name (for example sub-workflow-child).

  2. Under Workflow inputs, add the fields the parent will supply. Example: workspace_id (text, optional).

  3. Add steps that use those inputs. In any field that accepts a formula, reference the input:

    {{ workflow_inputs.workspace_id }}

  4. At the bottom of the editor, under Outputs, map the results you want callers to receive. Example: expose ws_info from a tool step’s data field.

The visual editor builds the YAML for you. A child workflow that looks up workspace info might look like this:

name: sub-workflow-child
description: Look up workspace details for use by other workflows
version: 1.0.0
scope: account
enabled: true
trigger:
  kind: manual
  contexts:
    - chat
workflow_inputs:
  - name: workspace_id
    type: string
    required: false
steps:
  - name: get_workspace_info
    kind: tool
    config:
      tool_name: workspace_tool
      action: info
      workspace_id: "{{ workflow_inputs.workspace_id }}"
    on_error: fail
    description: Show workspace details
error_handling:
  mode: fail_fast
workflow_outputs:
  - name: ws_info
    step_id: get_workspace_info
    field: data

Run the child on its own with sample inputs before wiring the parent. If the child works alone, the parent will have reliable data to pass through.

Step 2 — Add a sub-workflow step in the parent

  1. Open the parent workflow in the editor.
  2. Click Add Step.
  3. Set Step kind to Subworkflow.
  4. Under Target workflow, use the Subworkflow target picker to choose the child workflow you saved. The editor records both the workflow ID and name.
  5. The picker excludes the current workflow so you cannot accidentally call yourself.

Passing inputs into the child

This is the most important wiring rule:

Child workflow inputs and parent step inputs must use the same names. Set each step input’s Value source to From expression, then write a formula for the value to send.

Example: the child expects workspace_id. The parent collects a list called workspaces when someone triggers the run. On the sub-workflow step, add a step input:

Child expectsParent step input nameExpression
workspace_idworkspace_id{{ workflow_inputs.workspaces[0] }}

The first workspace in the list is passed into the child as workspace_id.

For formula syntax (workflow_inputs, earlier steps, list indexes), see Workflow authoring.

Getting outputs back

Outputs flow back in two levels. Both matter if you want a clean result on the parent execution record.

1. Sub-workflow step outputs

On the parent’s sub-workflow step, open Outputs and declare what you want to capture from the child — for example ws_info (object). Use names that match what the child exposes in its workflow outputs.

2. Parent workflow outputs

At the bottom of the parent editor, under Outputs, map from the sub-workflow step into named results for the whole run — for example ws1 ← step step_1, field ws_info.

Worked example: two workspaces, one child

Parent input: workspaces — an optional list (default empty). Two sub-workflow steps call the same child with different items from that list. Top-level outputs ws1 and ws2 collect each result.

name: parent-workflow
version: 1.0.0
scope: account
enabled: true
trigger:
  kind: manual
  contexts:
    - chat
workflow_inputs:
  - name: workspaces
    type: array
    required: false
    default: []
steps:
  - name: step_1
    kind: subworkflow
    config:
      workflow_id: "<your-child-workflow-id>"
      workflow_name: sub-workflow-child
    inputs:
      - name: workspace_id
        type: string
        required: false
        value_source: from_expression
        expression: "{{ workflow_inputs.workspaces[0] }}"
    outputs:
      - name: ws_info
        type: object
        format: json
    on_error: fail
  - name: step_2
    kind: subworkflow
    config:
      workflow_id: "<your-child-workflow-id>"
      workflow_name: sub-workflow-child
    inputs:
      - name: workspace_id
        type: string
        required: false
        value_source: from_expression
        expression: "{{ workflow_inputs.workspaces[1] }}"
    outputs:
      - name: ws_info
        type: object
        format: json
    on_error: fail
error_handling:
  mode: fail_fast
workflow_outputs:
  - name: ws1
    step_id: step_1
    field: ws_info
  - name: ws2
    step_id: step_2
    field: ws_info

Replace <your-child-workflow-id> with the ID from the picker (you do not need to type this when using the visual editor).

Running and checking results

  1. Trigger the parent workflow as usual.
  2. While the child runs, the sub-workflow step shows Awaiting subworkflow, then Completed when the child finishes.
  3. On the execution detail page, View child execution opens the child run. The child run shows a link back to the parent when it was started from a sub-workflow step.
  4. The parent’s workflow outputs section shows ws1, ws2, or whatever names you configured.

Tips

  • Name inputs and outputs clearly — they are the contract between parent and child.
  • Test the child first with realistic inputs before connecting the parent.
  • Reuse the same child in multiple steps; change only the expression on each step input (as in the two-workspace example).
  • Save and validate — if the child workflow is missing or disabled, the editor will warn you before you rely on it in production.

Related guides