> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# Workflow

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

## 変更

### `getWorkflows` から `listWorkflows` へ

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

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

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

> **Codemod:** Mastra の codemod CLI を使用すると、import を自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/mastra-plural-apis .
> ```

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

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

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

```diff
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 を自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/runtime-context .
> ```

### `createRunAsync` から `createRun` へ

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

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

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

> **Codemod:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-create-run-async .
> ```

### `runCount` から `retryCount` へ（非推奨）

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

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

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

> **Codemod:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-run-count .
> ```

### `getInitData` が unknown を返すように変更

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

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

> **Codemod:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-get-init-data .
> ```

### `getWorkflowRuns` から `listWorkflowRuns` へ

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

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

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

> **Codemod:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-list-runs .
> ```

### 入力をデフォルトで検証

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

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

### Step の `suspendPayload` 検証

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

```diff
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 の出力を使用するコードで任意の値を処理できるようにします。

```diff
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 する：

```diff
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` です。
>
> ```ts
> 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()` 関数を非同期で呼び出すよう更新します。

```diff
- 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()`](https://mastra.zisheng.pro/ja/reference/streaming/workflows/stream)、[`Run.resumeStream()`](https://mastra.zisheng.pro/ja/reference/streaming/workflows/resumeStream)、[`Run.observeStream()`](https://mastra.zisheng.pro/ja/reference/streaming/workflows/observeStream)を参照してください。

> **Codemod:** Mastra の codemod CLI を使用すると、コードを自動更新できます。
>
> ```bash
> npx @mastra/codemod@latest v1/workflow-stream-vnext .
> ```

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

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

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

```diff
.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 から直接移行する方法はありません。

```diff
- 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` プロパティを使用します。

```diff
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 を使用します。

```diff
- 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 を使用します。

```diff
- 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 を使用します。