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

# Tool

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

## 已变更

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

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

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

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

```diff
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 特有属性。

```diff
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 特有属性。

```diff
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 迁移指南](https://mastra.zisheng.pro/guides/migrations/upgrade-to-v1/mcp)。

### `RuntimeContext` 改为 `RequestContext`

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

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

```diff
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 自动更新导入：
>
> ```bash
> npx @mastra/codemod@latest v1/runtime-context .
> ```

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

### 使用 `outputSchema` 验证 Tool 输出

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

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

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

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

```diff
+ // 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` 时，请先检查结果是否包含错误，再访问输出属性：

```typescript
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），请使用可选链或非空断言：

```typescript
// 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' }, {})
```