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 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() 方法现在返回一个 Schema，其中所有分支输出字段都是可选的。这与运行时行为一致：每个分支仅在条件为真时执行，因此任何分支的输出都可能为 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> 的 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 导出

@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。