Workflows

舊版 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 自動更新 import：

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 自動更新 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 步驟執行中的 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

執行函數中的 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 的 schema 不需要驗證，請設定 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 結果欄位現在為選填

.branch() 方法現在傳回的 schema 中，所有 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 事件區塊。

這項變更令 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> 的 ToolStream，並提供 .write() 及 .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() 現為非同步，並會驗證傳入的資料

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 export

@mastra/core 中的 ./workflows/legacy export 路徑已移除。不再支援舊版 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 已移除。請改用 suspend/resume API。

如要遷移，請使用 suspend/resume 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 已移除。請改用 suspend/resume API。