Read usage and cost
Setcost: 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
Ordered array of steps. See Workflow Steps.
Storage integration. Persisting data does not make arbitrary step effects replay-safe; see recovery contracts.
{ maxRetries, backoffMs } for failed steps. See Retry & Error Handling.Custom bus. Emits
workflow.step with { runId, stepName, status: "start" \| "done" \| "error" }.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:- Initial state —
initialStateis the starting point. - Steps — Each step receives the current state and can return a partial update.
- State merge — Updates are merged into the state before the next step.
- Result —
WorkflowResultcontains final state andstepResults.
Basic Example
WorkflowResult
Next Steps
Workflow Steps
AgentStep, FunctionStep, ConditionStep, ParallelStep.
Retry & Error Handling
retryPolicy, StepResult status, WorkflowResult.