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;
}

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 for workflow persistence (e.g., resuming, audit).

object

{ maxRetries, backoffMs } for failed steps. See Retry & Error Handling.

EventBus

Custom event bus for workflow events.

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";

interface ContentState {
  topic: string;
  research_output?: string;
  write_output?: string;
}

const researcher = new Agent({
  name: "Researcher",
  model: openai("gpt-4o-mini"),
  instructions: "Research topics and provide factual summaries.",
});

const writer = new Agent({
  name: "Writer",
  model: openai("gpt-4o-mini"),
  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.

​Workflows

​Stateful Step-Based Execution

Shared State

Step Types

Retry & Error Handling

Event-Driven

​WorkflowConfig

​State Machine Concept

​Basic Example

​WorkflowResult

​Next Steps

Workflow Steps

Retry & Error Handling

Workflows

Stateful Step-Based Execution

WorkflowConfig

State Machine Concept

Basic Example

WorkflowResult

Next Steps