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

# Workflow\.tool()

`.tool()` 方法将 tool 添加为声明式步骤。该 tool 自身的输入和输出 schema 会生效，因此前一个步骤的输出必须满足 tool 的输入 schema。如果数据不匹配，请使用 `.map()` 转换数据。

与使用 `createStep()` 包装 tool 不同，`.tool()` 会在 workflow 图中记录一个声明式条目。这使 workflow 可移植：同一个图可以序列化并持久化为[动态 workflow](https://mastra.zisheng.pro/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 步骤的步骤级别重试次数、scorers 和 metadata。

**stepOptions** (`{ id?: string }`): 步骤在 workflow 中调用位置的 ID。默认使用 tool 的 ID。同一个 tool 在一个 workflow 中出现多次时，请设置此项。

## 返回值

**workflow** (`Workflow`): 用于方法链式调用的 workflow 实例

## 通过 ID 引用 tool

传入字符串可引用已注册的 tool，而无需导入它。workflow 运行时，该 tool 必须已在 Mastra 实例上注册：

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

## 持久化 tool 步骤

使用 `.tool()` 构建的 workflow 会序列化为[动态 workflow](https://mastra.zisheng.pro/docs/workflows/dynamic-workflows)使用的同一种声明式条目。只有 `retries` 和 `metadata` 可以通过存储往返保留。值为函数的 `scorers` 选项会在存储 workflow 时抛出错误。

## 相关内容

- [Agents 和 Tools](https://mastra.zisheng.pro/docs/workflows/agents-and-tools)
- [动态 workflow](https://mastra.zisheng.pro/docs/workflows/dynamic-workflows)
- [Workflow.agent()](https://mastra.zisheng.pro/reference/workflows/workflow-methods/agent)