WorkflowKit class

import {
  WorkflowKit,
  type WorkflowEngine,
  type WorkflowKitOptions,
  type WorldConfig,
  type WorldRunHandle,
} from "@ai_kit/core";

WorkflowKit selects the workflow engine and exposes a unified lifecycle. The default engine is legacy (the in-memory engine); world runs on the Vercel Workflow SDK with a durable Postgres/MongoDB backend (requires the optional @ai_kit/workflow-world package).

`WorkflowKitOptions`

Property	Type	Default	Description
`engine`	`"legacy" \| "world"`	`"legacy"`	Engine used by default for `run`.
`world`	`WorldConfig`	`undefined`	World backend config. Required when `engine === "world"`.

`WorldConfig`

Property	Type	Default	Description
`type`	`"postgres" \| "mongodb"`	required	World backend. `mongodb` is experimental.
`url`	`string`	required	Connection string (`postgres://` / `mongodb://`).
`jobPrefix`	`string`	`undefined`	Postgres: namespace jobs on a shared database.
`workerConcurrency`	`number`	SDK default	Postgres: concurrent workers (maps to `queueConcurrency`).
`maxPoolSize`	`number`	SDK default	Postgres: connection pool size.

Construction

const kit = new WorkflowKit({
  engine: "world",
  world: { type: "postgres", url: process.env.WORKFLOW_POSTGRES_URL! },
});

The constructor validates the config:

engine: "world" without a world config throws.
An unknown world.type throws.
engine: "legacy" with a world config is allowed (lets you toggle engines via an env var without rewriting config).

Properties

Property	Type	Description
`engine`	`WorkflowEngine`	The configured default engine (read-only).
`world`	`WorldConfig \| undefined`	The world config, if any (read-only).

Methods

`start()`

start(): Promise<void>;

Starts the durable world worker (lazily loading @ai_kit/workflow-world and creating the adapter). No-op when engine === "legacy", so the same lifecycle code works for both engines. Throws a clear error if @ai_kit/workflow-world is not installed.

`stop()`

stop(): Promise<void>;

Gracefully stops the world worker. No-op when engine === "legacy" or when the world was never started.

`run(workflow, input, dispatch?)`

Dispatches to the configured engine (overridable per call via dispatch.engine).

// Legacy overload — workflow is an AI Kit Workflow
run<Output>(
  workflow: Workflow<any, Output>,
  options: WorkflowRunOptions,
  dispatch?: { engine?: WorkflowEngine },
): Promise<WorkflowRunResult<Output>>;

// World overload — workflow is a "use workflow" function, input is the args array
run<TResult = unknown>(
  workflow: (...args: any[]) => TResult | Promise<TResult>,
  args: unknown[],
  dispatch?: { engine?: WorkflowEngine },
): Promise<WorldRunHandle<TResult>>;

legacy → delegates to Workflow.run(options) and returns a WorkflowRunResult.
world → delegates to the SDK’s start(fn, args) and returns a WorldRunHandle (durable; the output is not returned directly — see runAndWait / returnValue).

`runAndWait(workflow, input, dispatch?)`

Runs a workflow and resolves with its output, synchronous-style, regardless of engine — the closest match to the legacy await workflow.run() then .result.

// Legacy overload → resolves with the workflow Output
runAndWait<Output>(
  workflow: Workflow<any, Output>,
  options: WorkflowRunOptions,
  dispatch?: { engine?: WorkflowEngine },
): Promise<Output>;

// World overload → awaits the durable run and resolves with its return value
runAndWait<TResult = unknown>(
  workflow: (...args: any[]) => TResult | Promise<TResult>,
  args: unknown[],
  dispatch?: { engine?: WorkflowEngine },
): Promise<TResult>;

Throws on failure (so wrap it where legacy code read result.status):

legacy → throws when the result status is not "success" (with the run error);
world → rejects via the SDK (WorkflowRunFailedError / WorkflowRunCancelledError).

const report = await kit.runAndWait(reportWorkflow, [input]); // output directly

`WorldRunHandle<TResult>`

The handle returned by a world run (pass-through of the SDK Run). Use it when you want to start now and consume later:

Member	Type	Description
`runId`	`string`	Identifier of the durable run.
`returnValue`	`Promise<TResult>`	Resolves with the output once complete; rejects if the run failed/was cancelled.
`status`	`Promise<WorldRunStatus>`	`"pending" \| "running" \| "completed" \| "failed" \| "cancelled"`.
`exists`	`Promise<boolean>`	Whether the run exists in the world.
`cancel()`	`Promise<void>`	Cancels the run.

Reconstitute a handle later from a stored id with getRun(runId) from workflow/api.

Example

import { WorkflowKit } from "@ai_kit/core";

// One config, switchable via env — legacy locally, world in production
export const kit = new WorkflowKit({
  engine: (process.env.WORKFLOW_ENGINE as "legacy" | "world") ?? "legacy",
  world: { type: "postgres", url: process.env.WORKFLOW_POSTGRES_URL ?? "" },
});

await kit.start();                 // no-op on legacy
const handle = await kit.run(myWorkflow, ["arg"]);
await kit.stop();

See the World engine guide for installation, authoring rules, and migration.

​WorkflowKitOptions

​WorldConfig

​Construction

​Properties

​Methods

​start()

​stop()

​run(workflow, input, dispatch?)

​runAndWait(workflow, input, dispatch?)

​WorldRunHandle<TResult>

​Example