> ## Documentation Index
> Fetch the complete documentation index at: https://ai.aidalinfo.fr/llms.txt
> Use this file to discover all available pages before exploring further.

# Classe WorkflowKit

> Façade unifiée pour exécuter des workflows AI Kit sur le moteur en mémoire legacy ou le moteur world durable.

```ts theme={null}
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`](/fr/workflows/world-engine)).

## `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

```ts theme={null}
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()`

```ts theme={null}
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()`

```ts theme={null}
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`).

```ts theme={null}
// 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`](/fr/api-reference/workflow).
* **`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`.

```ts theme={null}
// 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`).

```ts theme={null}
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

```ts theme={null}
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](/fr/workflows/world-engine) pour l'installation, les règles d'écriture et la migration.