Blocks

Sub-workflow

The sub-workflow trigger turns a workflow into a function other workflows and AI agents can call. Pass the caller's payload through or start clean.

The sub-workflow trigger turns a workflow into a function: other workflows call it (via the call workflow action step or an agent tool), it runs with the caller's data, and its final output returns to the caller.

When it runs

When any workflow in the workspace invokes it. The callee must be active. There is no URL and no schedule: a sub-workflow is internal only, which also means nothing outside your workspace can reach it. A call workflow step whose target lives in another workspace simply doesn't resolve.

Each call is its own run, with its own entry in runs, its own step history and its own approvals. The child run records the parent run that started it and how deep in the chain it sits.

Config

The sub-workflow trigger's Inspector config One switch: pass the caller's payload through, or start clean.

  • Pass payload through: on, the caller's payload becomes this workflow's starting payload. Off (the default): the caller's inputs are received but not forwarded, and the next step starts with {}.

Leave it off when the sub-workflow is self-contained (a nightly cleanup several schedules share); turn it on whenever the callee is a function of the caller's data, which is most of the time.

Output

The caller's payload (with pass-through on), in whatever shape the calling step sent. If the caller was a step reading an order, the first step after this trigger sees

{ "order_id": "ord_9f2", "total_cents": 12900, "email": "a@example.com" }

and references it as {{ payload.order_id }}. With pass-through off the first step sees {}.

The sub-workflow's return value is whatever its last step emits. In the caller, that map becomes the call workflow step's output. Document your own contract: sub-workflows are easiest to reuse when they expect a small, named set of fields and return a small, named set of fields.

How the caller waits

The call workflow step has two modes. In wait (the default) the parent run pauses at that step; its worker exits, the child runs on its own job, and the parent resumes with the child's output when the child finishes. A failed child fails the parent step. In detach the parent continues immediately with the child's run id and never hears back, which is how one event fans out to several sub-workflows in parallel.

One exception: a call in wait mode inside a loop body runs the child to completion inside that iteration instead of pausing, because a loop can't pause mid-iteration. The result is the same from the body's point of view.

Patterns

  • Shared delivery: one "notify team" workflow every other workflow calls, so changing the channel is one edit.
  • Agent tools: an AI agent step can call a sub-workflow as a tool, turning any workflow into a capability the model can use.
  • Decomposition: a big pipeline split into testable parts.
  • Router: a listener workflow that receives every event and detaches one sub-workflow per event type, each with its own approvals and its own run history.

Gotchas

  • Call depth is bounded, so a sub-workflow calling itself (or a cycle of callers) stops at the limit instead of recursing forever. A top-level run is depth 0; a run at depth 3 refuses to start another call. A step that targets the workflow it lives in is refused outright.
  • The caller waits synchronously, so keep sub-workflows quick or the parent run inherits the wait.
  • The callee runs its active snapshot. Editing the callee's canvas changes nothing for callers until you activate again.
  • With pass-through off, every {{ payload.* }} reference in the callee renders empty. The build-time linter flags these.

Related

‹ Watch File upload ›