Workflow

舊版 Workflow 功能已移除。

已變更

getWorkflows 改為 listWorkflows

mastra.getWorkflows() 方法已重新命名為 mastra.listWorkflows()。這項變更與整個 API 使用的命名慣例一致：回傳多筆資料的 getter 方法會使用 list 前綴。

遷移時，請將所有 mastra.getWorkflows() 呼叫替換成 mastra.listWorkflows()。

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

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新匯入：

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

步驟內容中的 RuntimeContext 改為 RequestContext

Workflow 步驟執行內容中的參數名稱已從 runtimeContext 變更為 requestContext。這項變更與為提升清晰度而進行的全域重新命名一致。

遷移時，請在步驟執行函式中將 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 自動更新匯入：

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 步驟執行中的 runCount 參數已棄用，請改用 retryCount。新名稱表示此值為重試次數。舊的 runCount 仍可運作，但會顯示棄用警告。

遷移時，請在步驟執行函式中將 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 函式現在傳回 unknown，而非 any。你必須自行指定型別。 遷移時，請將 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 輸入，此布林值現已改為 true。如果想保留舊有行為，或有不需驗證結構描述的 Workflow，請設定 validateInputs: false。

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

步驟 suspendPayload 驗證

對於已定義 suspendSchema 的步驟，現在會驗證步驟的 suspendPayload。此驗證也會使用 validateInputs 旗標，決定是否驗證 suspendPayload。

  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() 方法現在傳回所有分支輸出欄位皆為選填的結構描述。這反映執行階段行為：每個分支只會在條件為 truthy 時執行，因此任何分支的輸出都可能是 undefined。

遷移時，請更新所有使用分支輸出的程式碼，以處理選填值。

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

如果程式碼依賴非選填型別，請新增執行階段檢查，或在存取分支輸出時提供預設值。

Run.start() 與 Run.timeTravel() 中的 writableStream 改為 outputWriter

Run.start() 與 Run.timeTravel() 中的 writableStream 參數已由 outputWriter 取代。現在不再傳入 WritableStream，而是傳入直接接收每個 Workflow 事件區塊的非同步回呼函式。

這項變更簡化了 API：不需建立 WritableStream 包裝函式，直接在回呼中處理區塊即可。

**範例：**將 Workflow 事件串流至 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`);
+   },
+ });

備註

這項變更不影響傳給步驟 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() 函式現在是非同步。傳入的資料現在會根據步驟中定義的 stateSchema 驗證。狀態資料驗證也會使用 validateInputs 旗標，決定是否驗證狀態資料。此外，呼叫 setState() 時，現在只需傳入要更新的狀態資料，不需再展開先前的狀態 (...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 前綴名稱，並直接存取串流屬性。

詳情請參閱 Run.stream()、Run.resumeStream() 與 Run.observeStream()。

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新程式碼：

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

步驟條件函式參數中不提供 suspend() 與 setState()

步驟條件函式參數中不提供 suspend() 與 setState() 函式。

遷移時，請改在步驟 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 匯出項目

@mastra/core 已移除 ./workflows/legacy 匯出路徑。不再支援舊版 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() 方法已棄用。這些方法仍可運作，但會顯示主控台警告。

遷移時，請使用 fullStream 屬性，而非直接在 run 輸出上呼叫方法。

  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 事件 API

舊版 watch 事件已移除，並整合至 v2 事件 API。不再提供 watch() 方法與相關 watch 端點。

遷移時，請使用 Workflow 事件 API 或串流，而非 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);
+ }

waitForEvent API

Workflow 已移除 waitForEvent API。請改用暫停／恢復 API。

遷移時，請使用暫停／恢復 API，等待 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',
+   });
+ }

sendEvent API

Workflow 已移除 sendEvent API。請改用暫停／恢復 API。