> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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`，阻止 Tool 恢復。

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

> **備註:** 如需 MCP 專屬 Tool 內容的變更，請參閱 [MCP 遷移指南](https://mastra.zisheng.pro/zh-TW/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 輸出符合結構描述定義：

```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 的型別檢查，你必須先縮小結果型別，再存取輸出結構描述的屬性。

呼叫 `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 或非 null 斷言：

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