Tool

Tool 执行签名已更新为使用独立的输入参数和上下文参数，同时重新组织了上下文属性。

已变更

createTool 的 execute 签名改为 (inputData, context) 格式

所有 createTool execute 函数现在都使用包含独立 inputData 和 context 参数的签名，不再使用单个解构对象。Tool 输入和执行上下文现在分别传递。

此签名变更仅适用于 createTool。Workflow 的 createStep 调用仍保留 async (inputData, context) 签名。

迁移时，请更新 createTool 签名，将 inputData 作为第一个参数（类型由 inputSchema 推断），将 context 作为第二个参数。

  createTool({
    id: 'weather-tool',
-   execute: async ({ context, requestContext, mastra }) => {
-     const location = context.location;
-     const userTier = requestContext.get('userTier');
-     return getWeather(location, userTier);
-   },
+   execute: async (inputData, context) => {
+     const location = inputData.location;
+     const userTier = context?.requestContext?.get('userTier');
+     return getWeather(location, userTier);
+   },
  });

createTool 上下文属性的组织方式

createTool 中的上下文属性现在按命名空间组织。Agent 特有属性位于 context.agent 下，Workflow 特有属性位于 context.workflow 下，MCP 特有属性位于 context.mcp 下。此变更让组织方式更合理，API 界面也更清晰。

对于在 Agent 内执行的 Tool，请通过 context.agent 访问 Agent 特有属性。

  createTool({
    id: 'suspendable-tool',
    suspendSchema: z.object({ message: z.string() }),
    resumeSchema: z.object({ approval: z.boolean() }),
-   execute: async ({ context, suspend, resumeData }) => {
-     if (!resumeData) {
-       return await suspend({ message: 'Waiting for approval' });
-     }
-     if (resumeData.approval) {
-       return { success: true };
-     }
-   },
+   execute: async (inputData, context) => {
+     if (!context?.agent?.resumeData) {
+       return await context?.agent?.suspend({
+         message: 'Waiting for approval',
+       });
+     }
+     if (context.agent.resumeData.approval) {
+       return { success: true };
+     }
+   },
  });

对于在 Workflow 内执行的 Tool，请通过 context.workflow 访问 Workflow 特有属性。

  createTool({
    id: 'workflow-tool',
-   execute: async ({ workflowId, runId, state, setState }) => {
-     const currentState = state;
-     setState({ step: 'completed' });
-     return { result: 'done' };
-   },
+   execute: async (inputData, context) => {
+     const currentState = context?.workflow?.state;
+     context?.workflow?.setState({ step: 'completed' });
+     return { result: 'done' };
+   },
  });

Tool 执行时，会根据 suspendSchema 验证 suspendPayload。如果 suspendPayload 与 suspendSchema 不匹配，系统会记录警告并将错误作为 Tool 输出返回，但仍会继续暂停。 此外，Tool 恢复时，会根据 resumeSchema 验证 resumeData。如果 resumeData 与 resumeSchema 不匹配，Tool 将返回 ValidationError，阻止恢复。

如需跳过 suspendSchema 或 resumeSchema 验证，请不要在创建 Tool 时定义 suspendSchema 或 resumeSchema。

备注

有关 MCP 特有的 Tool 上下文变更，请参阅 MCP 迁移指南。

RuntimeContext 改为 RequestContext

Tool 执行上下文中的 RuntimeContext 类已全面重命名为 RequestContext。新名称表明该类包含请求特有的数据。

迁移时，请在 Tool 执行函数中将 runtimeContext 引用更新为 requestContext。

  createTool({
    id: 'my-tool',
    execute: async (inputData, context) => {
-     const userTier = context?.runtimeContext?.get('userTier');
+     const userTier = context?.requestContext?.get('userTier');
      return { result: userTier };
    },
  });

Codemod

你可以使用 Mastra 的 codemod CLI 自动更新导入：

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

此变更适用于所有 Tool 执行，无论是直接调用，还是通过 Agent 和 Workflow 调用。类型收窄可确保你正确处理验证错误，并避免访问输出属性时出现运行时错误。

使用 outputSchema 验证 Tool 输出

提供 outputSchema 的 Tool 现在会在运行时验证返回值。此前，outputSchema 仅用于类型推断，并不会实际验证输出。

如果 Tool 返回的数据与其 outputSchema 不匹配，现在会返回 ValidationError，而不是无效数据。

如需修复验证错误，请确保 Tool 输出与 Schema 定义匹配：

  const getUserTool = createTool({
    id: "get-user",
    outputSchema: z.object({
      id: z.string(),
      name: z.string(),
      email: z.string().email(),
    }),
    execute: async (inputData) => {
-     return { id: "123", name: "John" }; // Missing email
+     return { id: "123", name: "John", email: "john@example.com" };
    },
  });

验证失败时，Tool 会返回 ValidationError：

+ // Before v1 - invalid output would silently pass through
  await getUserTool.execute({});
- // { id: "123", name: "John" } - missing email
+ // {
+ //   error: true,
+ //   message: "Tool output validation failed for get-user. The tool returned invalid output:\n- email: Required\n\nReturned output: {...}",
+ //   validationErrors: { ... }
+ // }

tool.execute 返回类型包含 ValidationError

tool.execute 的返回类型现在包含 ValidationError，用于处理验证失败。访问输出 Schema 属性前，必须先收窄结果类型，以满足 TypeScript 的类型检查要求。

调用 tool.execute 时，请先检查结果是否包含错误，再访问输出属性：

const result = await getUserTool.execute({})

// Type-safe check for validation errors
if ('error' in result && result.error) {
  console.error('Validation failed:', result.message)
  console.error('Details:', result.validationErrors)
  return
}

// TypeScript knows result is valid here
console.log(result.id, result.name, result.email)

你也可以更新 outputSchema 以匹配实际输出；如果不需要验证，则可以完全移除 outputSchema。

直接执行 Tool

为了支持单独处理执行逻辑的客户端 Tool 定义，tool.execute 属性在类型系统中是可选的。直接在 Tool 实例上调用 execute 时（而不是通过 Agent 或 Workflow），请使用可选链或非空断言：

// Optional chaining (recommended)
const result = await weatherTool.execute?.({ location: 'New York' }, {})

// Non-null assertion (when you know execute exists)
const result = await weatherTool.execute!({ location: 'New York' }, {})