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

# Tool

Tool 的執行簽名已更新，改為使用獨立的輸入及 context 參數，而 context 屬性亦已重新整理。

## 變更

### 將 `createTool` 的 execute 簽名改為 `(inputData, context)` 格式

所有 `createTool` execute 函式現在都使用獨立的 `inputData` 及 `context` 參數，不再使用單一的解構物件。Tool 輸入及執行 context 現在會分開傳遞。

這項簽名變更只適用於 `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` context 屬性的組織方式

`createTool` 中的 context 屬性現在會按命名空間分類。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`，並阻止 Tool 恢復執行。

如要略過 `suspendSchema` 或 `resumeSchema` 驗證，請不要在建立 Tool 時定義 `suspendSchema` 或 `resumeSchema`。

> **備註:** 有關 MCP 專用 Tool context 的變更，請參閱 [MCP 遷移指南](https://mastra.zisheng.pro/zh-HK/guides/migrations/upgrade-to-v1/mcp)。

### `RuntimeContext` 改名為 `RequestContext`

在整個 Tool 執行 context 中，`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 自動更新 imports：
>
> ```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`，以便處理驗證失敗的情況。為符合 TypeScript 的類型檢查要求，你必須先收窄結果類型，才可存取輸出 schema 的屬性。

呼叫 `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.execute` 屬性屬於可選，以支援在用戶端另外處理執行邏輯的 Tool 定義。直接在 Tool 實例上呼叫 `execute` 時（而非透過 Agent 或 Workflow），請使用 optional chaining 或 non-null assertion：

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