Workflows

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.

Stateful Step-Based Execution

Shared State

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

Step Types

AgentStep, FunctionStep, ConditionStep, ParallelStep.

Retry & Error Handling

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

Event-Driven

Optional EventBus for workflow lifecycle events.

WorkflowConfig

interface WorkflowConfig<TState> {
  name: string;
  initialState: TState;
  steps: StepDef<TState>[];
  storage?: StorageDriver;
  retryPolicy?: { maxRetries: number; backoffMs: number };
  eventBus?: EventBus;
  register?: boolean; // default true
  checkpointStore?: WorkflowCheckpointStore<TState>; // time-travel
}

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 every step so you can replay or fork. See Time travel.

`workflow.run(opts?)`

Field	Type	Description
`sessionId`	`string?`	Correlate this run in events/storage.
`userId`	`string?`	Who triggered it.

Returns WorkflowResult<TState>: { state, stepResults }.

StepResult

Field	Type	Description
`stepName`	`string`	The `name` you set on the step.
`status`	`"done" \| "error" \| "skipped"`	Outcome. Condition steps skip children when false.
`error`	`string?`	Message when `status` is `"error"`.
`durationMs`	`number`	Wall-clock time for that step.

Step shapes

Kind	Fields	What it does
Agent	`{ name, agent, inputFrom?(state) }`	Runs `agent.run(inputFrom(state) ?? JSON.stringify(state))`. Writes `{ [name]_output: text }` into state by convention in examples; your `inputFrom` decides.
Function	`{ name, run(state, ctx) }`	Your code. Return a `Partial<TState>` to merge.
Condition	`{ name, condition(state), steps }`	If `condition` is true, run nested `steps`.
Parallel	`{ name, parallel: StepDef[] }`	Run nested steps at the same time, then merge.

State Machine Concept

Workflows behave like state machines:

Initial state — initialState is 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 — WorkflowResult contains final state and stepResults.

Basic Example

import { Workflow, Agent, openai } from "@agentium/core";

type ContentState = {
  topic: string;
  research_output?: string;
  write_output?: string;
}

const researcher = new Agent({
  name: "Researcher",
  model: openai(process.env.OPENAI_FAST_MODEL ?? "gpt-6-luna"),
  instructions: "Research topics and provide factual summaries.",
});

const writer = new Agent({
  name: "Writer",
  model: openai(process.env.OPENAI_FAST_MODEL ?? "gpt-6-luna"),
  instructions: "Write clear content from research notes.",
});

const workflow = new Workflow<ContentState>({
  name: "Content Pipeline",
  initialState: { topic: "Quantum computing basics" },
  steps: [
    {
      name: "research",
      agent: researcher,
      inputFrom: (state) => `Research: ${state.topic}`,
    },
    {
      name: "write",
      agent: writer,
      inputFrom: (state) => `Write a draft using: ${state.research_output}`,
    },
  ],
});

const result = await workflow.run();
console.log(result.state.write_output);

WorkflowResult

interface WorkflowResult<TState> {
  state: TState;
  stepResults: StepResult[];
}

TState

Final state after all steps (including any updates from steps).

StepResult[]

Per-step results: stepName, status (done | error | skipped), error?, durationMs.

Build

Agent applications

Harness runtime

Teams and workflows

Data and capabilities

Interfaces and jobs

Voice and telephony

Verify and manage

Stateful Step-Based Execution

Shared State

Step Types

Retry & Error Handling

Event-Driven

WorkflowConfig

`workflow.run(opts?)`

StepResult

Step shapes

State Machine Concept

Basic Example

WorkflowResult

Next Steps

Workflow Steps

Retry & Error Handling

​Stateful Step-Based Execution

Shared State

Step Types

Retry & Error Handling

Event-Driven

​WorkflowConfig

​workflow.run(opts?)

​StepResult

​Step shapes

​State Machine Concept

​Basic Example

​WorkflowResult

​Next Steps

Workflow Steps

Retry & Error Handling

Stateful Step-Based Execution

WorkflowConfig

`workflow.run(opts?)`

StepResult

Step shapes

State Machine Concept

Basic Example

WorkflowResult

Next Steps