Skip to main content
action.invoke-workflow, Execute another workflow and return its output

​
Child runs

Use execution: child to create a separate run. Set wait: false to return execution metadata immediately; retrieve the child output from its run later. Nested file descriptors are copied into the child’s run-owned input artifacts before the child becomes available to workers. A child target can be dynamic, for example workflow: "policy-{{ input.queue }}". Online validation warns that target existence, input/output contracts and cycles cannot be fully checked statically. The worker resolves the target in the same tenant and validates its inputs at runtime. Dynamic inline targets are rejected because inline definitions must be snapshotted before execution. With wait: true, a parent waiting for its child is checkpointed in the database and releases its worker slot and concurrency allocation. Child completion, failure, or cancellation requeues the parent, which continues from the same invocation and reads the child result. This is a child wait, not a human review: it does not create a review task. Nested and concurrent invocations use the same checkpoint mechanism. Execution tags correlate runs; they do not prevent duplicate dispatches. The worker reuses an existing child for the same parent run and step scope when that parent resumes. This does not deduplicate separate parent runs or independent API requests.

​
Inspecting failures

Use eigenpal runs get <run-id> --expand input,execution,debug --json. execution.childExecutions shows child runs and their steps; debug includes phase timing, the failure and the trace ID. Follow a child’s run ID to inspect its own failure. Queued phase spans show queue wait time. Input preparation failures include a specific failure code and public message. In debug.observability.failure, diagnostic.inputPath identifies the input location when known and diagnostic.correlationId identifies the run for log lookup. Raw provider errors, storage URLs and document filenames remain internal.

​
Execution tags

Child runs can carry tags for finding their output later. Inline invocations cannot carry tags.
tags accepts one string or a string array, including a template resolving to either. Tags are exact and case-sensitive, deduplicated, and never inherited from the parent. Use GET /api/v1/runs?tag=<requestId>, eigenpal runs list --tag <requestId>, or the Runs tag filter to retrieve tagged runs. Retry and rerun executions retain their original tags. Maximum: 100 tags, 256 characters each. Blank tags are rejected.

​
Configuration

Configuration goes inside the step’s with: block.
​
string | array<string>
Child mode only. One tag or a list. Supports templates resolving to a string or string array. Tags are not inherited.
​
string
Workflow to invoke, definition name or wf_ id (tenant-scoped)
​
string
Legacy alias for workflow when the value is a wf_ id
​
"inline" | "child"
inline: run target steps in this execution (default). child: spawn a separate run with lineage.
​
record<string, unknown>
Input record keyed by the invoked workflow’s declared inputs
​
boolean
Child mode only. Wait for the invoked workflow to complete and return its output (default: true). Set false for fire-and-forget.
​
number
Child mode only. Max wait time in ms while the child is queued or running (default: 300000). The deadline is stored with the invocation and survives worker restarts; expiry makes the parent eligible to resume and report the timeout. Once the child pauses for human review, the parent pauses durably instead of using this timeout.
​
number
Child mode only. Accepted for compatibility. Durable child waits no longer poll or occupy a worker slot.

​
Output

Returns record<string, unknown>. When wait is true, the invoked workflow’s declared output fields are flattened to the top level alongside a files array, reference them as {{ steps.<invoke>.output.<field> }} (there is no .data or .result wrapper). When wait is false, execution metadata. CLI authors can run eigenpal workflow schema &lt;workflow-id> to inspect resolved fields; Studio builder agents can call get_workflow_output_schema. Finite numeric tag values resolved from templates are converted to strings in child invocations (for example, request ID 123 becomes tag "123"). Other invalid values still fail validation. Tags supplied directly to the API must be strings.