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

# Tavily Tools

`@mastra/tavily` 包将 [Tavily](https://app.tavily.com) API 封装为与 Mastra 兼容的 Tool。它提供搜索、提取、抓取和网站结构映射 factory function。每个函数都返回使用 [`createTool()`](https://mastra.zisheng.pro/reference/tools/create-tool) 创建的 Tool，并包含完整的 Zod 输入/输出 schema。

## 安装

**npm**:

```sh
npm install @mastra/tavily @tavily/core zod
```

**pnpm**:

```sh
pnpm add @mastra/tavily @tavily/core zod
```

**Yarn**:

```sh
yarn add @mastra/tavily @tavily/core zod
```

**Bun**:

```sh
bun add @mastra/tavily @tavily/core zod
```

## 快速开始

使用 `createTavilyTools()` 以共用设置取得全部四个 Tool：

```typescript
import { createTavilyTools } from '@mastra/tavily'

const tools = createTavilyTools()
// Or pass an explicit API key:
// const tools = createTavilyTools({ apiKey: 'tvly-...' })
```

你也可以分别创建每个 Tool：

```typescript
import { createTavilySearchTool, createTavilyExtractTool } from '@mastra/tavily'

const searchTool = createTavilySearchTool()
const extractTool = createTavilyExtractTool({ apiKey: 'tvly-...' })
```

根据缺省，所有 Tool 都会从环境中读取 `TAVILY_API_KEY`。你可以明确传入 `{ apiKey }` 来覆写此值。

## 设置

所有 factory function 都接受来自 `@tavily/core` 的 `TavilyClientOptions`：

**apiKey** (`string`): Tavily API key。未设置时会使用 TAVILY\_API\_KEY 环境变量。

**clientName** (`string`): 每次请求时通过 X-Client-Name header 发送的归属字符串。 (Default: `'mastra'`)

**apiBaseURL** (`string`): Tavily API 的 base URL。

**proxies** (`object`): 传给底层 HTTP client 的 proxy 设置。

**projectId** (`string`): 用于限定请求范围的 Tavily project ID。

## `createTavilyTools()`

返回一个对象，其中包含共用设置的全部四个 Tool。

```typescript
import { createTavilyTools } from '@mastra/tavily'

const tools = createTavilyTools({ apiKey: 'tvly-...' })
// tools.tavilySearch, tools.tavilyExtract, tools.tavilyCrawl, tools.tavilyMap
```

**返回值：** `{ tavilySearch, tavilyExtract, tavilyCrawl, tavilyMap }`

## `createTavilySearchTool()`

创建一个使用 Tavily 搜索网络的 Tool。它会返回相关结果，包括内容摘要、选填的 AI 产生答案与图片。

**Tool ID：** `tavily-search`

```typescript
import { createTavilySearchTool } from '@mastra/tavily'

const searchTool = createTavilySearchTool()
```

### 输入

**query** (`string`): 搜索查找。

**searchDepth** (`'basic' | 'advanced' | 'fast' | 'ultra-fast'`): 搜索深度。使用 'basic' 取得标准结果、'advanced' 取得更完整的结果，或使用 'fast'／'ultra-fast' 降低延迟。

**maxResults** (`number`): 返回结果的数量上限（1–20）。

**includeAnswer** (`boolean | 'basic' | 'advanced'`): 包含由 AI 产生的答案摘要。

**includeImages** (`boolean`): 在回应中包含与查找相关的图片。

**includeImageDescriptions** (`boolean`): 包含返回图片的说明。

**includeRawContent** (`false | 'markdown' | 'text'`): 包含每个结果经清理的 HTML 内容。传入 false 可停用，或传入 'markdown'／'text' 指定格式。

**includeDomains** (`string[]`): 将结果限制在这些网域。

**excludeDomains** (`string[]`): 排除来自这些网域的结果。

**timeRange** (`'day' | 'week' | 'month' | 'year'`): 依时间新近程度筛选结果。

### 输出

**query** (`string`): 原始搜索查找。

**answer** (`string`): 由 AI 产生的答案摘要。

**images** (`{ url: string; description?: string }[]`): 相关图片。

**results** (`SearchResult[]`): 搜索结果数组。

**results.title** (`string`): 结果标题。

**results.url** (`string`): 结果 URL。

**results.content** (`string`): 内容摘要。

**results.score** (`number`): 相关性分数。

**results.rawContent** (`string`): 完整页面内容（提出要求时）。

**responseTime** (`number`): 服务器回应时间（秒）。

## `createTavilyExtractTool()`

创建一个从一个或多个 URL 截取内容的 Tool。它会以 Markdown 或文本格式返回原始页面内容，每次请求最多可处理 20 个 URL。

**Tool ID：** `tavily-extract`

```typescript
import { createTavilyExtractTool } from '@mastra/tavily'

const extractTool = createTavilyExtractTool()
```

### 输入

**urls** (`string[]`): 要截取内容的 URL（1–20 个）。

**extractDepth** (`'basic' | 'advanced'`): 截取深度。使用 'advanced' 可截取表格与嵌入内容。

**query** (`string`): 用户意图，用来依相关性对截取的内容区块重新排序。

**includeImages** (`boolean`): 包含从页面截取的图片。

**format** (`'markdown' | 'text'`): 截取内容的输出格式。 (Default: `'markdown'`)

### 输出

**results** (`ExtractResult[]`): 成功截取的页面。

**results.url** (`string`): 页面 URL。

**results.rawContent** (`string`): 截取的页面内容。

**results.images** (`string[]`): 截取的图片 URL。

**failedResults** (`FailedResult[]`): 截取失败的 URL。

**failedResults.url** (`string`): 失败的 URL。

**failedResults.error** (`string`): 错误消息。

**responseTime** (`number`): 服务器回应时间（秒）。

## `createTavilyCrawlTool()`

创建一个从指定 URL 开始抓取网站的 Tool。它会从找到的页面截取内容，并可设置深度、广度与网域限制。

**Tool ID：** `tavily-crawl`

```typescript
import { createTavilyCrawlTool } from '@mastra/tavily'

const crawlTool = createTavilyCrawlTool()
```

### 输入

**url** (`string`): 开始抓取的根 URL。

**maxDepth** (`number`): 从 base URL 开始抓取的深度上限。

**maxBreadth** (`number`): 每页要跟随的链接数量上限。

**limit** (`number`): Crawler 停止前处理的页面总数。

**instructions** (`string`): 提供给 crawler 的自然语言 instructions。

**selectPaths** (`string[]`): 用来选取特定 URL 路径的 regex pattern。

**selectDomains** (`string[]`): 用来限制特定网域的 regex pattern。

**excludePaths** (`string[]`): 用来排除特定 URL 路径的 regex pattern。

**excludeDomains** (`string[]`): 用来排除特定网域的 regex pattern。

**allowExternal** (`boolean`): 是否跟随前往外部网域的链接。

**extractDepth** (`'basic' | 'advanced'`): 截取深度。使用 'advanced' 可截取表格与嵌入内容。

**includeImages** (`boolean`): 包含抓取页面中的图片。

**format** (`'markdown' | 'text'`): 截取内容的输出格式。 (Default: `'markdown'`)

### 输出

**baseUrl** (`string`): 已抓取的根 URL。

**results** (`CrawlResult[]`): 从找到的页面截取的内容。

**results.url** (`string`): 页面 URL。

**results.rawContent** (`string`): 截取的页面内容。

**results.images** (`string[]`): 页面上找到的图片 URL。

**responseTime** (`number`): 服务器回应时间（秒）。

## `createTavilyMapTool()`

创建一个从指定 URL 开始映射网站结构的 Tool。它会探索并返回 URL 清单，但不截取页面内容。可在针对特定目标截取前，使用此 Tool 了解网站结构。

**Tool ID：** `tavily-map`

```typescript
import { createTavilyMapTool } from '@mastra/tavily'

const mapTool = createTavilyMapTool()
```

### 输入

**url** (`string`): 开始映射网站结构的根 URL。

**maxDepth** (`number`): 从 base URL 开始映射网站结构的深度上限。

**maxBreadth** (`number`): 每页要跟随的链接数量上限。

**limit** (`number`): Mapper 停止前处理的链接总数。

**instructions** (`string`): 提供给 mapper 的自然语言 instructions。

**selectPaths** (`string[]`): 用来选取特定 URL 路径的 regex pattern。

**selectDomains** (`string[]`): 用来限制特定网域的 regex pattern。

**excludePaths** (`string[]`): 用来排除特定 URL 路径的 regex pattern。

**excludeDomains** (`string[]`): 用来排除特定网域的 regex pattern。

**allowExternal** (`boolean`): 是否包含外部网域链接。

### 输出

**baseUrl** (`string`): 已完成结构映射的根 URL。

**results** (`string[]`): 找到的 URL。

**responseTime** (`number`): 服务器回应时间（秒）。

## Agent 示例

下列示例示范结合搜索与截取功能的研究 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { createTavilySearchTool, createTavilyExtractTool } from '@mastra/tavily'

const agent = new Agent({
  id: 'web-search-agent',
  name: 'Web Search Agent',
  model: 'anthropic/claude-sonnet-4-6',
  instructions:
    'You are a web search assistant. Use search tool to find relevant pages, then use extract tool to get full content from the best results.',
  tools: {
    search: createTavilySearchTool(),
    extract: createTavilyExtractTool(),
  },
})
```

## 环境变量

| 变量               | 说明                                                          |
| ---------------- | ----------------------------------------------------------- |
| `TAVILY_API_KEY` | 你的 Tavily API key。若未将 `apiKey` 传给 factory function，则缺省使用此值。 |

## 相关内容

- [`createTool()`](https://mastra.zisheng.pro/reference/tools/create-tool)
- [Tavily API 文档](https://docs.tavily.com)