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

# Workflow\.tool()

`.tool()` 方法會將 Tool 新增為宣告式步驟。系統會套用 Tool 自己的輸入與輸出 schema，因此前一步驟的輸出必須符合 Tool 的輸入 schema。若兩者不相符，請使用 `.map()` 轉換資料。

與使用 `createStep()` 包裝 Tool 不同，`.tool()` 會在 Workflow 圖中記錄宣告式項目。這能讓 Workflow 具備可攜性：同一個圖可以序列化，並保存為[動態 Workflow](https://mastra.zisheng.pro/zh-TW/docs/workflows/dynamic-workflows)。

## 使用範例

```typescript
workflow.tool(testTool).commit();
```

## 參數

**toolOrId** (`Tool | string`): Tool 執行個體，或已在 Mastra 執行個體上註冊的 Tool ID。傳入 ID 時，系統會在執行階段從登錄檔解析 Tool。

**options** (`{ retries?: number, scorers?: DynamicArgument<MastraScorers>, metadata?: StepMetadata }`): Tool 步驟的步驟層級重試次數、scorer 與中繼資料。

**stepOptions** (`{ id?: string }`): 此步驟在 Workflow 中呼叫位置的 ID。預設為 Tool 的 ID。同一個 Tool 在同一個 Workflow 中出現多次時，請設定此值。

## 回傳值

**workflow** (`Workflow`): 可供方法連結使用的 Workflow 執行個體

## 透過 ID 參照 Tool

傳入字串，即可在不匯入 Tool 的情況下參照已註冊的 Tool。Workflow 執行時，該 Tool 必須已註冊於 Mastra 執行個體：

```typescript
workflow.tool("lookup-customer", { retries: 2 }).commit();
```

## 保存 Tool 步驟

使用 `.tool()` 建立的 Workflow，會序列化為與[動態 Workflow](https://mastra.zisheng.pro/zh-TW/docs/workflows/dynamic-workflows) 相同的宣告式項目。只有 `retries` 與 `metadata` 能完整寫入儲存空間後再還原。保存 Workflow 時，值為函式的 `scorers` 選項會擲回錯誤。

## 相關內容

- [Agent 與 Tool](https://mastra.zisheng.pro/zh-TW/docs/workflows/agents-and-tools)
- [動態 Workflow](https://mastra.zisheng.pro/zh-TW/docs/workflows/dynamic-workflows)
- [Workflow.agent()](https://mastra.zisheng.pro/zh-TW/reference/workflows/workflow-methods/agent)