Lifecycle

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.

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.

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.finished

A skipped step reports why (a false condition), a cached step reports the hit, and a retrying step reports the attempt. A step.completed event carries that step's full metrics. 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.

Per-step metrics

Each completed step produces a StepMetrics record. It times the step, counts retries, and splits cost into two buckets.

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.

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 three complete workflows from the first step to the final output.