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

# Tools

File-based Agent 会从其 `tools/` 直属目录下的 `.ts` 和 `.js` 文件中发现 Tool。每个发现的文件都会在构建时导入，且必须默认导出一个 [`createTool()`](https://mastra.zisheng.pro/reference/tools/create-tool) 结果；不含扩展名的文件名将成为模型可调用的 Tool 键。

本页介绍基于文件的约定。有关 Tool schema、执行选项、输出调整和审批选项，请参阅 [`createTool()` 参考](https://mastra.zisheng.pro/reference/tools/create-tool)。

## 快速开始

在 `tools/` 下每个文件放置一个 Tool。此文件会以 `get_weather` 名称向 Agent 公开。

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export default createTool({
  id: 'get_weather',
  description: 'Get the current weather for a location.',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})
```

## 组织 Tool

每个文件放置一个 Tool。以模型应执行的操作命名文件：

- 使用 `get_weather.ts`、`search_docs.ts` 或 `create_ticket.ts`。
- 避免使用 `helper.ts`、`api.ts` 或 `utils.ts` 等含糊名称。
- 以 `*.test.ts` 或 `*.spec.ts` 的形式将测试放在 Tool 旁边。发现过程会忽略这些文件。
- 将共享的辅助代码放在 `tools/` 之外，或放在 `tools/` 下扩展名不符合发现规则的文件中。

嵌套目录不会被发现为 Tool，因此请使用清晰的文件名前缀（例如 `calendar_create_event.ts` 和 `calendar_list_events.ts`）来组织相关 Tool，而不是使用子文件夹。

## Tool 选项

基于文件的约定只控制 Tool 的存放位置及其注册方式。Tool API 仍由 `createTool()` 提供：

- 使用 `description` 告诉模型何时调用 Tool。
- 使用 `inputSchema` 和 `outputSchema` 定义结构化输入和输出。
- 当模型应看到与 `execute` 返回的原始值不同的结构时，使用 `toModelOutput`。
- 当 Tool 在执行前需要人工确认时，使用 `requireApproval`。

有关所有选项，请参阅 [`createTool()` 参考](https://mastra.zisheng.pro/reference/tools/create-tool)；有关审批流程，请参阅 [Tool 审批](https://mastra.zisheng.pro/docs/harness/agent-controller)。

## 运行时边界

Agent 调用 Tool 时，Tool 代码会在你的应用/server 运行时中执行。如果 Tool 需要文件系统或 shell 隔离，请显式调用 [workspace](https://mastra.zisheng.pro/reference/file-based-agents/workspace) 或 sandbox API。

## 与 config 的优先级

发现的 Tool 会与 [`config.ts`](https://mastra.zisheng.pro/reference/file-based-agents/config) 中的所有 `tools` 合并。如果键冲突，`config.tools` 优先，并会记录警告。

如果 `config.tools` 是函数，Mastra 会忽略发现的 Tool 并发出警告，因为值为函数的 Tool 无法进行静态合并。