Lifecycle
What happens when a workflow runs. The static plan the engine compiles first, the events it emits as each step runs, and the per-run metrics and two-currency cost accounting that make the whole run auditable.
A run moves through the same stages every time. The engine plans the workflow into a static tree, executes that plan step by step while emitting an event for each one, records metrics as it goes, and totals the cost at the end. Following that arc, plan to run to events to metrics to cost, is the best way to understand what the engine actually does with a definition.
The split between planning and executing is the important part. A workflow is fully laid out before any of it runs, so you can inspect exactly what will happen before a single byte of I/O or a single model call.
The plan
Planning walks the config and produces an ExecutionPlan. The plan resolves no templates, evaluates no conditions, and calls no component. It only assigns each step an id and mirrors the tree, so you can see exactly what will run before anything happens.
Every step gets a hierarchical id that encodes its place in the tree.
| Id | Step |
|---|---|
1 | The first top-level action. |
1.1 | The first child of step 1. |
1.2.1 | The first child of the second child of step 1. |
1.else | The else branch of step 1. |
An iterating step does not multiply the ids. A step carrying an each: field is one planned step that runs many times, and the children of a component: each block are planned once and re-run per element, so the plan stays the size of the document rather than the size of the data.
Because the plan is pure data, it can be serialized and rendered as a diagram, diffed between versions, or written to disk. A step whose component is another workflow carries that workflow's own sub-plan inline, so a plan for a composed automation expands to the full tree across every workflow it touches. Step variables are held unresolved in the plan. They are rendered only at execution time, against the outputs that exist by then.
Tip
Planning is where a workflow is validated structurally. Unknown components, malformed nesting, and unresolvable sub-workflow references surface here, before anything runs and before any model is called. A simulation goes further and reports named diagnostics, among them nil_decision for a decision modifier fed a value nothing supplies, which is the failure worth catching before a run rather than during one.
The run and its events
Executing the plan runs each top-level step in order, threading every earlier step's output forward so it is in scope for the next. Around each step the engine emits lifecycle events on a bus.
run.started
step.started → step.completed | step.failed | step.skipped | step.cached | step.retrying
...
run.finishedThere are eight event kinds and no others. Two are run-level, run.started and run.finished, and the run.finished payload carries a status of ok or failed. The other six are per-step. A skipped step reports its reason, disabled or condition, which is the detail the step's own skipped output flag deliberately leaves out. A cached step reports the hit, and a retrying step reports the attempt. A step.completed event carries that step's full metrics.
An iterated step is one step to the bus. It starts once and completes once however many elements it ran, and the elements' costs and retries are summed into that single completion.
Sinks subscribe to the bus to log a run, persist it, or accumulate metrics, and a per-run sink can be attached to collect everything a single execution produced. This is what makes a long automation observable from the outside while it runs, not only after it finishes.
Reading the verdict from inside the run
A top-level step carrying always: true is held back and run once the sequence has stopped, whether it finished or a step failed. It reads the outcome as two ordinary names in scope, run.failed and run.error, spelled the way a step's own outputs are spelled. These are values, not events. There is no run.failed event, and the per-step failure event is step.failed.
The plan still fails with the error that stopped it, so an always step reports the outcome rather than replacing it, and an always step that fails on top of a failure is logged rather than becoming the new reason the run stopped.
Per-step metrics
Each completed step produces a StepMetrics record. It times the step, counts retries, and splits cost into two buckets.
| Field | Meaning |
|---|---|
TookMS | Wall-clock duration of the step. |
Retries | How many times the step was retried. |
CostGeneral | Resource cost for non-model steps. |
CostInference | Model cost for inference steps. |
Logs | Log lines the step emitted. |
The general bucket counts real resource use, bytes and files read, written, and deleted, and network bytes moved. The inference bucket carries the model, the token count, and a per-phase breakdown across the estimate, input, output, and reasoning tokens. Summing the metrics of every step gives the totals for the run.
A model call made once per element costs the same whether the loop is in the document or in the caller, so an iterated step adds its elements' figures up rather than reporting the last one. An iterated step that looked free would be the more expensive mistake.
Two-currency cost
Cost is always tracked in two currencies. The provider cost is the real price in USD, and the client cost is that price converted into the currency the call requested. Both travel together through every phase of an inference and through the run total, so a report can show what a workflow cost the platform and what it costs the customer at the same time.
SkillInferenceCost
provider, model, tokens
cost_provider (USD) cost_client (converted)
estimate_input_* input_* output_* thinking_*Money is summed field by field without converting again at sum time. Each inference does its own conversion when it runs, and totals simply add same-currency amounts. The result is that a completed run reports a precise, auditable cost even though a model sat in the middle of it, which is the whole point of pairing a static plan with priced steps.
The cookbook puts every guide together, dissecting complete workflows from the first step to the final output.