Classe WorkflowKit

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

WorkflowKit sélectionne le moteur de workflow et expose un cycle de vie unifié. Le moteur par défaut est legacy (le moteur en mémoire) ; world s’exécute sur le Vercel Workflow SDK avec un backend Postgres/MongoDB durable (nécessite le package optionnel @ai_kit/workflow-world).

`WorkflowKitOptions`

Propriété	Type	Défaut	Description
`engine`	`"legacy" \| "world"`	`"legacy"`	Moteur utilisé par défaut pour `run`.
`world`	`WorldConfig`	`undefined`	Configuration du backend world. Requis quand `engine === "world"`.

`WorldConfig`

Propriété	Type	Défaut	Description
`type`	`"postgres" \| "mongodb"`	requis	Backend world. `mongodb` est expérimental.
`url`	`string`	requis	Chaîne de connexion (`postgres://` / `mongodb://`).
`jobPrefix`	`string`	`undefined`	Postgres : espace de noms des jobs sur une base partagée.
`workerConcurrency`	`number`	Défaut SDK	Postgres : workers concurrents (correspond à `queueConcurrency`).
`maxPoolSize`	`number`	Défaut SDK	Postgres : taille du pool de connexions.

Construction

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

Le constructeur valide la configuration :

engine: "world" sans config world lève une erreur.
Un world.type inconnu lève une erreur.
engine: "legacy" avec une config world est autorisé (permet de basculer entre les moteurs via une variable d’environnement sans réécrire la configuration).

Propriétés

Propriété	Type	Description
`engine`	`WorkflowEngine`	Le moteur par défaut configuré (lecture seule).
`world`	`WorldConfig \| undefined`	La configuration world, le cas échéant (lecture seule).

Méthodes

`start()`

start(): Promise<void>;

Démarre le worker world durable (charge @ai_kit/workflow-world à la demande et crée l’adaptateur). No-op quand engine === "legacy", donc le même code de cycle de vie fonctionne pour les deux moteurs. Lève une erreur claire si @ai_kit/workflow-world n’est pas installé.

`stop()`

stop(): Promise<void>;

Arrête proprement le worker world. No-op quand engine === "legacy" ou quand le world n’a jamais été démarré.

`run(workflow, input, dispatch?)`

Dispatche vers le moteur configuré (surchargeable par appel via dispatch.engine).

// Surcharge legacy — workflow est un Workflow AI Kit
run<Output>(
  workflow: Workflow<any, Output>,
  options: WorkflowRunOptions,
  dispatch?: { engine?: WorkflowEngine },
): Promise<WorkflowRunResult<Output>>;

// Surcharge world — workflow est une fonction "use workflow", input est le tableau d'args
run<TResult = unknown>(
  workflow: (...args: any[]) => TResult | Promise<TResult>,
  args: unknown[],
  dispatch?: { engine?: WorkflowEngine },
): Promise<WorldRunHandle<TResult>>;

legacy → délègue à Workflow.run(options) et retourne un WorkflowRunResult.
world → délègue au start(fn, args) du SDK et retourne un WorldRunHandle (durable ; la sortie n’est pas retournée directement — voir runAndWait / returnValue).

`runAndWait(workflow, input, dispatch?)`

Exécute un workflow et se résout avec sa sortie, de manière synchrone, quel que soit le moteur — l’équivalent le plus proche du legacy await workflow.run() puis .result.

// Surcharge legacy → se résout avec la sortie Output du workflow
runAndWait<Output>(
  workflow: Workflow<any, Output>,
  options: WorkflowRunOptions,
  dispatch?: { engine?: WorkflowEngine },
): Promise<Output>;

// Surcharge world → attend le run durable et se résout avec sa valeur de retour
runAndWait<TResult = unknown>(
  workflow: (...args: any[]) => TResult | Promise<TResult>,
  args: unknown[],
  dispatch?: { engine?: WorkflowEngine },
): Promise<TResult>;

Lève une erreur en cas d’échec (encapsulez là où le code legacy lisait result.status) :

legacy → lève une erreur quand le statut du résultat n’est pas "success" (avec l’erreur du run) ;
world → rejette via le SDK (WorkflowRunFailedError / WorkflowRunCancelledError).

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

`WorldRunHandle<TResult>`

Le handle retourné par un run world (pass-through du Run SDK). Utilisez-le quand vous voulez démarrer maintenant et consommer plus tard :

Membre	Type	Description
`runId`	`string`	Identifiant du run durable.
`returnValue`	`Promise<TResult>`	Se résout avec la sortie une fois terminé ; rejette si le run a échoué ou été annulé.
`status`	`Promise<WorldRunStatus>`	`"pending" \| "running" \| "completed" \| "failed" \| "cancelled"`.
`exists`	`Promise<boolean>`	Indique si le run existe dans le world.
`cancel()`	`Promise<void>`	Annule le run.

Reconstituez un handle plus tard à partir d’un identifiant stocké avec getRun(runId) depuis workflow/api.

Exemple

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

// Une seule config, basculable via env — legacy en local, world en 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 sur legacy
const handle = await kit.run(myWorkflow, ["arg"]);
await kit.stop();

Consultez le guide du moteur world pour l’installation, les règles d’écriture et la migration.

​WorkflowKitOptions

​WorldConfig

​Construction

​Propriétés

​Méthodes

​start()

​stop()

​run(workflow, input, dispatch?)

​runAndWait(workflow, input, dispatch?)

​WorldRunHandle<TResult>

​Exemple