Workflow patterns

Use a Workflow when your application defines the sequence. This example computes an order total and routes larger orders for review. It runs locally without a model, network connection, or order-service side effect.

Run an order-review pipeline

Use the supported Node runtime. In an empty directory, install the matching core package and a TypeScript runner:

npm init -y
npm pkg set type=module
npm install @agentium/core@4.0.0
npm install --save-dev typescript tsx @types/node

Save as review-order.ts:

review-order.ts

import { Workflow } from "@agentium/core";

type OrderState = {
  orderId: string;
  quantity: number;
  unitPriceCents: number;
  totalCents: number;
  route: "standard" | "review";
};

const workflow = new Workflow<OrderState>({
  name: "review-order", register: false,
  initialState: {
    orderId: "ORD-1042", quantity: 2, unitPriceCents: 2500,
    totalCents: 0, route: "standard",
  },
  steps: [
    {
      name: "calculate-total",
      run: async (state) => {
        if (!Number.isInteger(state.quantity) || state.quantity < 1) {
          throw new Error("Quantity must be a positive integer");
        }
        return { totalCents: state.quantity * state.unitPriceCents };
      },
    },
    {
      name: "route-large-order",
      condition: (state) => state.totalCents >= 10_000,
      steps: [{ name: "require-review", run: async () => ({ route: "review" }) }],
    },
  ],
});

const result = await workflow.run();
const failures = result.stepResults.filter((step) => step.status === "error");
if (failures.length) throw new Error(JSON.stringify(failures));
console.log(result.state);
console.table(result.stepResults.map(({ stepName, status }) => ({ stepName, status })));

npx tsx review-order.ts

Expect totalCents: 5000 and route: "standard". Change quantity to 4; the route becomes review. This is a routing decision, not a human approval or submitted order. Change it to 0 and verify the program exits with an error after inspecting step results. The function-only Workflow owns no model clients or stores to close. If you add Agents, stores, or service clients, the host must close those resources after the workflow settles.

Add a model only where judgment is needed

Host function: pass a configured model and trusted order summary. A named Agent step writes its text to <step-name>_output; declare that field in the state type. The function owns and closes the Agent.

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

type DraftState = { summary: string; draft_output?: string };

export async function draftOrderReply(model: ModelProvider, summary: string) {
  const writer = new Agent({
    name: "order-writer", model, register: false,
    instructions: "Write a concise customer update using only the supplied order facts.",
  });
  try {
    const result = await new Workflow<DraftState>({
      name: "draft-order-reply", register: false,
      initialState: { summary },
      steps: [{ name: "draft", agent: writer, inputFrom: (state) => state.summary }],
    }).run();
    if (result.stepResults.some((step) => step.status === "error")) {
      throw new Error("Order reply step failed");
    }
    return result.state.draft_output;
  } finally {
    await writer.close();
  }
}

Do not use a model for totals your application can compute exactly. Evaluate whether the drafted reply preserves the trusted facts with the quality-gate pattern.

Choose concurrency and failure behavior

Need	Use	Check before adapting
Ordered computation	Function steps returning partial state	Later steps receive the updated state
A conditional branch	`condition` with nested steps	Check both true and false paths
Concurrent independent work	Parallel steps	Branches start from snapshots; inspect merge behavior and avoid overlapping state writes
Retry transient failures	Retry policy	Retrying an effect can duplicate it; use provider idempotency and reconciliation
Operator approval	Harness approval workflow	Denial leaves effect count at zero
Conversation/model specialists	Teams	Coordination differs from a fixed sequence
Process restart recovery	Durable execution	A plain Workflow and conversation store do not supply a recovery contract

A resolved workflow.run() promise is not by itself proof that every step succeeded. Inspect stepResults; cancellation or other failures can also reject the call. Validate external input before merging it into trusted state.

More patterns

Step contracts and generated Workflow API.
Time travel for explicit checkpoints and forks; external effects remain external.
Queue workers for work that outlives an HTTP request.
Authenticated hosting for exposing registered application behavior.

Complete projects

Agents & memory

Models & Jev

Tools & knowledge

Teams & jobs

Deploy & devices

Quality & production

Workflow patterns

Run an order-review pipeline

Add a model only where judgment is needed

Choose concurrency and failure behavior

More patterns

​Run an order-review pipeline

​Add a model only where judgment is needed

​Choose concurrency and failure behavior

​More patterns

Run an order-review pipeline

Add a model only where judgment is needed

Choose concurrency and failure behavior

More patterns