Workflow

レガシー Workflow 機能が削除されました。

変更

getWorkflows から listWorkflows へ

mastra.getWorkflows() メソッドは mastra.listWorkflows() に改名されました。この変更は、複数の値を取得する getter メソッドに list プレフィックスを使用する API 全体の命名規則に合わせたものです。

移行するには、mastra.getWorkflows() の呼び出しをすべて mastra.listWorkflows() に置き換えます。

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

Codemod

Mastra の codemod CLI を使用すると、import を自動更新できます。

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

Step コンテキストの RuntimeContext から RequestContext へ

Workflow Step の実行コンテキストで、パラメーター名 runtimeContext が requestContext に変更されました。この変更は、明確性を高めるための全体的な改名に合わせたものです。

移行するには、Step 実行関数内の参照を runtimeContext から requestContext に更新します。

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

Codemod

Mastra の codemod CLI を使用すると、import を自動更新できます。

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

createRunAsync から createRun へ

createRunAsync() メソッドは createRun() に改名されました。すべての Run 作成が非同期であるため、冗長な「Async」サフィックスを削除して API を簡素化しています。

移行するには、メソッド呼び出しを createRunAsync から createRun に改名します。

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

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

runCount から retryCount へ（非推奨）

Workflow Step の実行で、runCount パラメーターは retryCount を優先して非推奨になりました。新しい名前は、この値が再試行回数であることを明確にします。以前の runCount も動作しますが、非推奨の警告が表示されます。

移行するには、Step 実行関数の runCount を retryCount に改名します。

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

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

getInitData が unknown を返すように変更

execute 関数の getInitData は、any ではなく unknown を返すようになりました。型を自分で指定する必要があります。 移行するには、getInitData() を getInitData<any>() に変更します。

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

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

getWorkflowRuns から listWorkflowRuns へ

getWorkflowRuns() メソッドは listWorkflowRuns() に改名されました。この変更は、コレクションを返すメソッドに list* を使用する規則に合わせたものです。

移行するには、メソッド呼び出しを getWorkflowRuns から listWorkflowRuns に改名します。

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

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

入力をデフォルトで検証

以前は、入力はデフォルトで検証されませんでした。validateInputs フラグは、Workflow の入力を検証するかを指定します。この Boolean のデフォルトが true に変更されました。以前の動作を維持する場合や、スキーマの検証が不要な Workflow では、validateInputs: false を設定してください。

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

Step の suspendPayload 検証

suspendSchema が定義された Step では、Step の suspendPayload が検証されるようになりました。suspendPayload を検証するかどうかも、validateInputs フラグで指定します。

  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" });
      }
    },
  });

Branch の結果フィールドが任意に

.branch() メソッドが返すスキーマでは、すべての Branch 出力フィールドが任意になりました。各 Branch は条件が truthy の場合にのみ実行されるため、どの Branch の出力も undefined になる可能性があるという実行時の動作を型に反映しています。

移行するには、Branch の出力を使用するコードで任意の値を処理できるようにします。

  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);

任意ではない型に依存するコードでは、Branch の出力へアクセスするときに実行時チェックを追加するか、デフォルト値を指定してください。

Run.start() と Run.timeTravel() の writableStream から outputWriter へ

Run.start() と Run.timeTravel() の writableStream パラメーターが outputWriter に置き換えられました。WritableStream を渡す代わりに、各 Workflow Event Chunk を直接受け取る非同期 Callback 関数を渡します。

この変更により、WritableStream の Wrapper を作成せず、Callback 内で Chunk を直接処理できるため API が簡素化されます。

例： Workflow Event を HTTP レスポンス（SSE）へ Streaming する：

  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`);
+   },
+ });

注記

Step の execute 関数に渡される writer パラメーターは、この変更の影響を受けません。引き続き WritableStream<unknown> を拡張し、.write() メソッドと .custom() メソッドを提供する ToolStream です。

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() を非同期化し、渡すデータを検証

setState() 関数が非同期になりました。渡すデータは、Step に定義された stateSchema に対して検証されます。State データを検証するかどうかも、validateInputs フラグで指定します。また、setState() を呼び出す際に、以前の State を Spread（(...state)）せず、更新する State データのみを渡せるようになりました。

移行するには、setState() 関数を非同期で呼び出すよう更新します。

- 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

削除

streamVNext、resumeStreamVNext、observeStreamVNext メソッド

実験的な streamVNext()、resumeStreamVNext()、observeStreamVNext() メソッドが削除されました。これらのメソッドは、イベント構造と戻り値の型を更新した標準実装になりました。

移行するには、標準の stream()、resumeStream()、observeStream() メソッドを使用します。イベント型のチェックには Workflow プレフィックス付きの名前を使用し、Stream のプロパティへ直接アクセスするよう更新してください。

詳しくは、Run.stream()、Run.resumeStream()、Run.observeStream()を参照してください。

Codemod

Mastra の codemod CLI を使用すると、コードを自動更新できます。

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

Step 条件関数のパラメーターから suspend() と setState() を削除

Step 条件関数のパラメーターでは、suspend() 関数と setState() 関数を使用できなくなりました。

移行するには、Step の execute 関数内で suspend() 関数を使用します。

.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
});

dountil と branch の条件関数のパラメーターについても同様です。

レガシー Workflow の export

./workflows/legacy の export パスが @mastra/core から削除されました。レガシー Workflow はサポートされなくなりました。

移行するには、新しい Workflow API を使用します。レガシー Workflow から直接移行する方法はありません。

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

WorkflowRunOutput の pipeThrough メソッドと pipeTo メソッド

WorkflowRunOutput の pipeThrough() メソッドと pipeTo() メソッドは非推奨です。これらのメソッドは引き続き動作しますが、コンソールに警告が表示されます。

移行するには、Run の出力でメソッドを直接呼び出す代わりに、fullStream プロパティを使用します。

  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);

Watch Event API

レガシー Watch Event が削除され、v2 Event API に統合されました。watch() メソッドと関連する Watch エンドポイントは利用できなくなりました。

移行するには、Watch Event の代わりに Workflow Event API または Streaming を使用します。

- 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);
+ }

waitForEvent API

waitForEvent API が Workflow から削除されました。代わりに Suspend/Resume API を使用します。

移行するには、Workflow の実行中に特定の時点を待機する処理で Suspend/Resume API を使用します。

- 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',
+   });
+ }

sendEvent API

sendEvent API が Workflow から削除されました。代わりに Suspend/Resume API を使用します。