Start child workflow `flow.child-workflow`

This node starts one child run with its own input, event history, signals, and terminal outcome. The parent first records the child request, then the scheduler creates or restores the child. When the child resolves, the parent is delivered again and receives the recorded outcome. Use this boundary for a process that needs independent observation, recovery, ownership, or version routing while remaining part of the parent operation.

Identity and definition

child_id must remain stable inside the parent run. Together with the graph node identity, it fixes the parent and child relationship during replay. spec selects the workflow name, version, runtime type, entry point, and any supported build route. The input expression produces the child start payload. Reusing the same child ID with a different spec, a different business object, or changed input is invalid because it would make history ambiguous.

Set cancellation_policy to request_cancellation when a cancelled parent should ask the child to stop and wait for its cleanup path. Select abandon only when the child has a separate owner, access path, retention policy, and reason to continue after the parent ends. Record that ownership decision in the workflow review so operators know which runs may outlive their parent.

Outcomes and failure handling

Resolved control leaves through completed. The outcome data port contains the actual success, failure, cancellation, or timeout result. Inspect that value before choosing the parent result. A child completion event does not imply business success. Tests should cover duplicate starts, child failure, parent cancellation, abandoned execution, scheduler restart, version routing, and result-size limits. Keep large child output in object storage and return a compact reference plus the fields required for the next decision. Monitoring should expose both run identities and make the selected cancellation policy visible during incident response.

Use it to start one child workflow with independent input, history, signals, and terminal outcome. The parent waits until the child resolves.

Runtime behavior

The node ID and child_id pin the parent-child relationship. The engine stores the request before starting or recovering the child, then exposes completed and outcome.

Node contract

Type: flow.child-workflow
Role: Durable runtime command
Runtime binding: start_child_workflow
Durable identity: Graph node ID

Configuration properties

Property	Type and control	Default	Rules
`child_id`Child ID	`str`StrInput	`child`	Replay-stable parent-local identity. The graph node ID is recommended.Required
`spec`Workflow spec	`dict`A3SFlowSpecInput	`{"name":"workflow.child","version":"0.1.0","runtime":{"kind":"native_ts","entrypoint":"workflows/child.ts","export_name":"main"}}`	Pinned workflow name, version, runtime, and optional build routing.Required
`input`Child input	`dict`A3SFlowExpressionInput	`{"apiVersion":"a3s.dev/flow-expression/v1","expression":{"op":"field","path":"input"}}`	Initial JSON input supplied to the child workflow.Required
`cancellation_policy`Cancellation policy	`str`DropdownInput	`request_cancellation`	Request child cancellation with the parent, or leave the child running.Required · Advanced · Allowed values request_cancellation, abandon

spec properties

Property	Type and control	Rules
`name`	`string`	Stable child workflow nameRequired
`version`	`string`	Child workflow definition versionRequired
`runtime.kind`	`native_ts \| rust_embedded`	Runtime familyRequired
`runtime.entrypoint`	`string`	Runtime entry file or registry keyRequired
`runtime.export_name`	`string`	Exported entry functionRequired
`runtime_build_id`	`string`	Pins the run to a compatible buildOptional

Ports

Direction	Port ID	Kind	Value types
Input	`in`In	control	`FlowControl`
Output	`completed`Completed	control	`FlowControl`
Output	`outcome`Outcome	data	`WorkflowTerminalOutcome`

Node JSON example

The CLI creates the same structure from manifest defaults. Canvas position, title, and selection are presentation data.

workflow.json

{
  "position": {
    "x": 320,
    "y": 160
  },
  "id": "example-flow-child-workflow",
  "data": {
    "child_id": "child",
    "spec": {
      "name": "workflow.child",
      "version": "0.1.0",
      "runtime": {
        "kind": "native_ts",
        "entrypoint": "workflows/child.ts",
        "export_name": "main"
      }
    },
    "input": {
      "apiVersion": "a3s.dev/flow-expression/v1",
      "expression": {
        "op": "field",
        "path": "input"
      }
    },
    "cancellation_policy": "request_cancellation",
    "type": "flow.child-workflow"
  }
}

CLI usage

Inspect the installed manifest first, then create the node and validate the complete workflow. Every command emits JSON.

Terminal

a3s-flow node flow.child-workflow --pretty
a3s-flow new flow.child-workflow --id example-flow-child-workflow --pretty
a3s-flow validate workflow.json --pretty
a3s-flow compile workflow.json --pretty
a3s-flow digest workflow.json --pretty

Skill usage

The package includes the a3s-flow Skill. It queries the CLI catalog before creating, validating, compiling, and digesting a workflow.

Prompt

Use $a3s-flow to add the "flow.child-workflow" node to workflow.json, connect valid ports, and validate the result.

CLI usage · Skill usage

Operational notes

Keep spec and input unchanged behind one child_id.
request_cancellation makes the parent wait for child cleanup.
abandon lets the child continue after parent ownership ends.

#Start child workflow flow.child-workflow

#Identity and definition

#Outcomes and failure handling