Workflows

Les fonctionnalités de workflow héritées ont été supprimées.

Modifications

Remplacement de getWorkflows par listWorkflows

La méthode mastra.getWorkflows() a été renommée mastra.listWorkflows(). Ce changement respecte la convention de nommage utilisée dans l'ensemble de l'API, selon laquelle les méthodes d'accès au pluriel utilisent le préfixe list.

Pour effectuer la migration, remplacez tous les appels à mastra.getWorkflows() par mastra.listWorkflows().

- const workflows = mastra.getWorkflows();
+ const workflows = mastra.listWorkflows();

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour automatiquement vos imports :

npx @mastra/codemod@latest v1/mastra-plural-apis .

Remplacement de RuntimeContext par RequestContext dans le contexte d'une étape

Le paramètre runtimeContext a été renommé requestContext dans le contexte d'exécution des étapes d'un workflow. Ce changement s'inscrit dans le renommage global visant à améliorer la clarté.

Pour effectuer la migration, remplacez les références à runtimeContext par requestContext dans les fonctions d'exécution des étapes.

  createStep({
-   execute: async ({ runtimeContext } ) => {
-     const userTier = context.runtimeContext.get('userTier');
+   execute: async ({ requestContext } ) => {
+     const userTier = requestContext.get('userTier');
      return { result: userTier };
    },
  });

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour automatiquement vos imports :

npx @mastra/codemod@latest v1/runtime-context .

Remplacement de createRunAsync par createRun

La méthode createRunAsync() a été renommée createRun(). Ce changement simplifie l'API en supprimant le suffixe redondant « Async », puisque toute création d'exécution est asynchrone.

Pour effectuer la migration, remplacez les appels à la méthode createRunAsync par createRun.

- await workflow.createRunAsync({ input: { ... } });
+ await workflow.createRun({ input: { ... } });

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/workflow-create-run-async .

Remplacement de runCount par retryCount (obsolète)

Le paramètre runCount est désormais obsolète au profit de retryCount lors de l'exécution des étapes d'un workflow. Le nouveau nom indique que cette valeur correspond au nombre de nouvelles tentatives. L'ancien paramètre runCount fonctionne toujours, mais affiche des avertissements d'obsolescence.

Pour effectuer la migration, renommez runCount en retryCount dans les fonctions d'exécution des étapes.

  createStep({
    execute: async (inputData, context) => {
-     console.log(`Step run ${context.runCount} times`);
+     console.log(`Step retry count: ${context.retryCount}`);
    },
  });

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/workflow-run-count .

getInitData renvoie unknown

La fonction getInitData appelée dans la fonction d'exécution renvoie désormais unknown au lieu de any. Vous devez donc préciser son type vous-même. Pour effectuer la migration, remplacez getInitData() par getInitData<any>()

  createStep({
    execute: async ({ getInitData }) => {
-     const initData = getInitData();
-     if (initData.key === 'value') {}
+     const initData = getInitData<any>();
+     if (initData.key === 'value') {}
    },
  });

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/workflow-get-init-data .

Remplacement de getWorkflowRuns par listWorkflowRuns

La méthode getWorkflowRuns() a été renommée listWorkflowRuns(). Ce changement respecte la convention selon laquelle les méthodes list* renvoient des collections.

Pour effectuer la migration, remplacez les appels à la méthode getWorkflowRuns par listWorkflowRuns.

- const runs = await workflow.getWorkflowRuns({ fromDate, toDate });
+ const runs = await workflow.listWorkflowRuns({ fromDate, toDate });

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/workflow-list-runs .

Les entrées sont validées par défaut

Auparavant, les entrées n'étaient pas validées par défaut. L'option validateInputs détermine si les entrées du workflow doivent être validées. Ce booléen vaut désormais true. Si vous souhaitez conserver l'ancien comportement ou si les schémas de vos workflows n'ont pas besoin d'être validés, définissez validateInputs: false.

createWorkflow({
+  options: {
+    validateInputs: false
+  }
})

Validation du suspendPayload d'une étape

Le suspendPayload d'une étape est désormais validé lorsque celle-ci définit un suspendSchema. Cette validation utilise également l'option validateInputs pour déterminer si le suspendPayload doit être validé.

  createStep({
    id: "suspend-resume-step",
    // ... other step properties
    suspendSchema: z.object({
      reason: z.string(),
      otherReason: z.string()
    }),
    execute: async ({ suspend, resumeData}) => {
      if (!resumeData) {
-       return suspend({ reason: "Suspension reason" }); // Missing otherReason
+       return suspend({ reason: "Suspension reason", otherReason: "Other reason" });
      }
    },
  });

Les champs de résultat des branches sont désormais facultatifs

La méthode .branch() renvoie désormais un schéma dans lequel tous les champs de sortie des branches sont facultatifs. Cela reflète le comportement à l'exécution : chaque branche ne s'exécute que si sa condition est vraie, de sorte que les sorties de n'importe quelle branche peuvent être undefined.

Pour effectuer la migration, mettez à jour tout code qui consomme les sorties des branches afin de gérer les valeurs facultatives.

  const workflow = createWorkflow({...})
    .branch([
      [condition1, stepA],  // outputSchema: { result: z.string() }
      [condition2, stepB],  // outputSchema: { data: z.number() }
    ])
-   // Previously: stepA.result typed as string, stepB.data typed as number
+   // Now: stepA.result typed as string | undefined, stepB.data typed as number | undefined
    .then(nextStep);

Si votre code repose sur des types non facultatifs, ajoutez des vérifications à l'exécution ou fournissez des valeurs par défaut lorsque vous accédez aux sorties des branches.

Remplacement de writableStream par outputWriter dans Run.start() et Run.timeTravel()

Le paramètre writableStream de Run.start() et Run.timeTravel() a été remplacé par outputWriter. Au lieu de transmettre un WritableStream, vous fournissez désormais une fonction de rappel asynchrone qui reçoit directement chaque fragment d'événement du workflow.

Ce changement simplifie l'API : au lieu de créer une enveloppe WritableStream, vous traitez directement les fragments dans la fonction de rappel.

Exemple : Diffusion des événements d'un workflow vers une réponse HTTP (SSE) :

  const run = await workflow.createRun();

- const stream = new WritableStream({
-   write(chunk) {
-     response.write(`data: ${JSON.stringify(chunk)}\n\n`);
-   }
- });
- await run.start({ inputData, writableStream: stream });

+ await run.start({
+   inputData,
+   outputWriter: async (chunk) => {
+     response.write(`data: ${JSON.stringify(chunk)}\n\n`);
+   },
+ });

remarque

Le paramètre writer transmis aux fonctions execute des étapes n'est pas concerné par ce changement. Il reste un ToolStream qui étend WritableStream<unknown> et fournit les méthodes .write() et .custom() :

createStep({
  id: 'my-step',
  execute: async ({ writer }) => {
    // This API is unchanged
    await writer.write({ data: 'some output' })
    await writer.custom({ type: 'custom-event', payload: {} })
  },
})

setState() est désormais asynchrone et les données transmises sont validées

La fonction setState() est désormais asynchrone. Les données transmises sont maintenant validées par rapport au stateSchema défini dans l'étape. La validation des données d'état utilise également l'option validateInputs pour déterminer si ces données doivent être validées. De plus, lors d'un appel à setState(), vous pouvez désormais transmettre uniquement les données d'état à mettre à jour, sans ajouter la décomposition de l'état précédent (...state).

Pour effectuer la migration, mettez à jour les appels à la fonction setState() pour les rendre asynchrones.

- setState({ ...state, sharedCounter: state.sharedCounter + 1 });
+ await setState({ sharedCounter: state.sharedCounter + 1 });
+ // await setState({ ...state, sharedCounter: state.sharedCounter + 1 }); 
+ // this also works, as the previous state spread remains supported

Suppressions

Méthodes streamVNext, resumeStreamVNext et observeStreamVNext

Les méthodes expérimentales streamVNext(), resumeStreamVNext() et observeStreamVNext() ont été supprimées. Elles correspondent désormais à l'implémentation standard, avec des structures d'événements et des types de retour mis à jour.

Pour effectuer la migration, utilisez les méthodes standard stream(), resumeStream() et observeStream(). Mettez à jour les vérifications des types d'événements afin d'utiliser les noms préfixés par « workflow » et accédez directement aux propriétés du flux.

Pour plus de détails, consultez Run.stream(), Run.resumeStream() et Run.observeStream().

Codemod

Vous pouvez utiliser la CLI codemod de Mastra pour mettre à jour votre code automatiquement :

npx @mastra/codemod@latest v1/workflow-stream-vnext .

suspend() et setState() ne sont pas disponibles dans les paramètres des fonctions de condition d'étape

Les fonctions suspend() et setState() ne sont pas disponibles dans les paramètres des fonctions de condition d'étape.

Pour effectuer la migration, utilisez plutôt la fonction suspend() dans la fonction d'exécution de l'étape.

.dowhile(step, async ({ suspend, state, setState }) => {
- setState({...state, updatedState: "updated state"})
- await suspend({ reason: "Suspension reason" });
+ // Use the suspend/setState in the step execute function instead
});

Il en va de même pour les paramètres des fonctions de condition dountil et branch.

Export des workflows hérités

Le chemin d'export ./workflows/legacy a été supprimé de @mastra/core. Les workflows hérités ne sont plus pris en charge.

Pour effectuer la migration, utilisez la nouvelle API de workflow. Il n'existe aucun chemin de migration direct depuis les workflows hérités.

- import { LegacyWorkflow } from '@mastra/core/workflows/legacy';
+ // Legacy workflows are no longer supported
+ // Migrate to the new workflow API

Méthodes pipeThrough et pipeTo de WorkflowRunOutput

Les méthodes pipeThrough() et pipeTo() de WorkflowRunOutput sont obsolètes. Elles fonctionnent toujours, mais affichent des avertissements dans la console.

Pour effectuer la migration, utilisez la propriété fullStream au lieu d'appeler les méthodes directement sur la sortie de l'exécution.

  const run = await workflow.createRun({ input: { ... } });
- await run.pipeTo(writableStream);
- const transformed = run.pipeThrough(transformStream);
+ await run.fullStream.pipeTo(writableStream);
+ const transformed = run.fullStream.pipeThrough(transformStream);

API des événements watch

Les événements watch hérités ont été supprimés et regroupés dans l'API d'événements v2. La méthode watch() et les endpoints watch associés ne sont plus disponibles.

Pour effectuer la migration, utilisez l'API d'événements de workflow ou le streaming à la place des événements watch.

- const workflow = mastraClient.getWorkflow('my-workflow');
- const run = await workflow.createRun();
- await run.watch((event) => {
-   console.log('Step completed:', event);
- });

+ const workflow = mastraClient.getWorkflow('my-workflow');
+ const run = await workflow.createRun();
+ const stream = await run.stream({ inputData: { ... } });
+ for await (const chunk of stream) {
+   console.log('Step completed:', chunk);
+ }

API waitForEvent

L'API waitForEvent a été supprimée des workflows. Utilisez plutôt l'API de suspension et de reprise.

Pour effectuer la migration, utilisez l'API de suspension et de reprise afin d'attendre les jalons d'exécution d'un workflow.

- workflow.waitForEvent('step-complete', step1).commit();
+ workflow.then(step1).commit();
+ // Use suspend/resume API instead, in step1 execute function
createStep({
- execute: async (inputData, context) => {
-  // ... execution logic 
- }
+ execute: async (inputData, context) => {
+   if (!context.resumeData) {
+     return context.suspend({})
+   }
+ }
});
+
+ // after workflow is suspended, you can resume it
+ const result = await run.start({ inputData: { ... } });
+ if (result.status === 'suspended') {
+   const resumedResult = await run.resume({
+     resumeData: {
+       event: 'step-complete',
+     },
+     step: 'step1',
+   });
+ }

API sendEvent

L'API sendEvent a été supprimée des workflows. Utilisez plutôt l'API de suspension et de reprise.