# Sub-Workflows

The `automation` family lets one workflow invoke another. It is how a step shared by five automations becomes one automation the other five call, instead of five copies that drift apart.

Two operators: `call` invokes a target, `return` sends a result back.

## Calling a Sub-Workflow

`automation/call` invokes an automation that declares an [`automation-call` trigger](/en/docs/trigger-manual-chained).

```yaml
- name: enrich
  type: automation
  operator: call
  props:
    name: enrich-lead
    inputData: { email: '{{trigger.data.record.email}}' }
    mode: sync
    maxDepth: 10
```

| Prop        | Description                                                                   |
| ----------- | ----------------------------------------------------------------------------- |
| `name`      | **Required.** Target automation name, kebab-case.                             |
| `inputData` | Key-value input handed to the callee. It reads this at `{{trigger.input.*}}`. |
| `mode`      | `sync` (wait for the callee, the default) or `async` (fire and continue).     |
| `maxDepth`  | Recursion guard, 1–100. Defaults to **10**.                                   |

:::callout
**`waitForCompletion` and `timeout` are accepted but ignored.** Both validate against the schema and neither is read at runtime — a call written with `waitForCompletion: true` is not thereby synchronous. Use **`mode`**: `sync` waits, `async` does not.
:::

`maxDepth` stops a chain that calls itself, directly or through intermediaries. The callee can see how deep it currently is at `{{trigger.depth}}`, and which automation invoked it at `{{trigger.caller}}`.

## Returning a Result

`automation/return` hands output back to the caller. It is only meaningful in an automation whose trigger is `automation-call`.

```yaml
- name: done
  type: automation
  operator: return
  props:
    data:
      score: '{{computeScore.result}}'
      tier: '{{classify.result}}'
```

| Prop   | Description                                                        |
| ------ | ------------------------------------------------------------------ |
| `data` | **Required.** Key-value output returned to the calling automation. |

`data` is the only property, and it is required — a `return` action without it fails config decode. In the parent, the result arrives as `steps.{name}.result.*`, so the call above is read back as `{{enrich.result.score}}`.

:::callout
**The prop is `data`, not `output`.** `output` is a real prop name — on [`flow/stop`](/en/docs/automation-flow-control), which ends a run rather than returning from one. The two are easy to confuse and behave differently: `return` hands a value to a caller, `stop` terminates.
:::

## Composition vs. Failure Handling

`automation/call` invokes a target that _declares_ an `automation-call` trigger, and (in `sync` mode) waits for its result. To react to a workflow that **failed**, use the [`automation-failure` trigger](/en/docs/trigger-manual-chained) instead — it fires after the fact, on a run you did not start, and cannot influence it.

| You want                                      | Use                                                      |
| --------------------------------------------- | -------------------------------------------------------- |
| Reuse a step across several automations       | `automation/call` with `mode: sync`.                     |
| Kick off long work without blocking this run  | `automation/call` with `mode: async`.                    |
| Be notified when some other automation breaks | An `automation-failure` trigger.                         |
| Recover from a failing step inside _this_ run | Per-action [`retry`](/en/docs/automation-retry-failure). |

## Related Pages

- [Flow Control](/en/docs/automation-flow-control) — branching, iteration, and `flow/stop`.
- [Manual, Sub-Automation & Failure Triggers](/en/docs/trigger-manual-chained) — the `automation-call` trigger this targets.
- [Retry & Failure](/en/docs/automation-retry-failure) — in-run recovery before a run is declared failed.
- [Actions Overview](/en/docs/automation-actions-overview) — base props and the family map.
- [Automation Runs](/en/docs/automation-runs) — following a parent run and its children.