Skip to main content
Workflows orchestrate multi-step pipelines with shared state. Define steps (agents, functions, conditions, parallel execution), pass state between them, and handle retries and errors—all in a declarative, state-machine style.

Read usage and cost

Set cost: true in the constructor and read result.costs after run(). Child Agents use the same accounting context. The parent snapshot includes its descendants once. Use cost: { budget: { maxCostPerRun: 0.50 } } for a simple USD threshold, or pass a shared costTracker for durable history and shared budgets. Set either cost or costTracker. Close the component after its work has finished to drain its owned tracker. Supplied trackers and stores remain caller-owned. See cost accounting.

Stateful Step-Based Execution

Shared State

Each step reads from and writes to a typed TState object passed through the workflow.

Step Types

Agent, function, condition, parallel, graph and bounded repeat steps.

Retry & Error Handling

Configurable retry policy and step result status (done, error, skipped).

Event-Driven

Optional EventBus for workflow lifecycle events.

WorkflowConfig

string
required
Display name for the workflow.
TState
required
Initial state object. Steps read from and merge updates into this state.
StepDef<TState>[]
required
Ordered array of steps. See Workflow Steps.
StorageDriver
Storage integration. Persisting data does not make arbitrary step effects replay-safe; see recovery contracts.
object
{ maxRetries, backoffMs } for failed steps. See Retry & Error Handling.
EventBus
Custom bus. Emits workflow.step with { runId, stepName, status: "start" \| "done" \| "error" }.
boolean
default:"true"
Put this workflow in the global registry. false for tests.
WorkflowCheckpointStore<TState>
Save state after complete top-level boundaries. Configure definition version and state validation together for validated continuation.

workflow.run(opts?)

Returns WorkflowResult<TState>: { state, stepResults, costs? }. The cost snapshot is present when accounting is enabled. It includes descendant work once; see usage and cost accounting for completeness states.

StepResult

Step shapes

See dependency graphs for control/data edges, clone isolation, strict conflicts and scoped grants. Function steps return owned patches; failed/stopped Agent output remains diagnostic rather than overwriting a successful state field. failurePolicy: "continue" collects ordinary errors and runs later steps; "stop" marks later serial work skipped. Any error makes aggregate status failed. Cancellation escapes collection/retries, drains started siblings and prevents late patches/checkpoints.

State Machine Concept

Workflows behave like state machines:
  1. Initial state — initialState is the starting point.
  2. Steps — Each step receives the current state and can return a partial update.
  3. State merge — Updates are merged into the state before the next step.
  4. Result — WorkflowResult contains final state and stepResults.

Basic Example


WorkflowResult

TState
Final state after all steps (including any updates from steps).
StepResult[]
Per-step results: stepName, status (done | error | skipped), error?, durationMs.

Next Steps

Workflow Steps

AgentStep, FunctionStep, ConditionStep, ParallelStep.

Retry & Error Handling

retryPolicy, StepResult status, WorkflowResult.