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

# Tavily tools

`@mastra/tavily` 套件將 [Tavily](https://app.tavily.com) API 封裝成與 Mastra 兼容的 tools。它提供用於搜尋、擷取、爬取及建立網站地圖的 factory functions。每個 function 都會傳回以 [`createTool()`](https://mastra.zisheng.pro/zh-HK/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()` 以共用設定取得全部四個 tools：

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

所有 tools 預設會從環境讀取 `TAVILY_API_KEY`。你可以明確傳入 `{ apiKey }` 以覆寫此設定。

## 設定

所有 factory functions 均接受來自 `@tavily/core` 的 `TavilyClientOptions`：

**apiKey** (`string`): Tavily API key。如未提供，則使用 TAVILY\_API\_KEY 環境變數。

**clientName** (`string`): 隨每個請求在 X-Client-Name header 中傳送的署名字串。 (Default: `'mastra'`)

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

**proxies** (`object`): 傳遞至底層 HTTP client 的 proxy 設定。

**projectId** (`string`): 用於界定請求範圍的 Tavily project ID。

## `createTavilyTools()`

傳回包含全部四個 tools 並共用設定的 object。

```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[]`): 將結果限制於這些 domains。

**excludeDomains** (`string[]`): 從結果中排除這些 domains。

**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。從發現的頁面擷取內容，並可設定深度、廣度及 domain 限制。

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

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

const crawlTool = createTavilyCrawlTool()
```

### 輸入

**url** (`string`): 開始爬取的根 URL。

**maxDepth** (`number`): 從基礎 URL 開始爬取的最大深度。

**maxBreadth** (`number`): 每個頁面最多可跟隨的連結數目。

**limit** (`number`): 爬蟲停止前處理的頁面總數。

**instructions** (`string`): 提供給爬蟲的自然語言指示。

**selectPaths** (`string[]`): 用於選取特定 URL paths 的 Regex patterns。

**selectDomains** (`string[]`): 用於限制為特定 domains 的 Regex patterns。

**excludePaths** (`string[]`): 用於排除特定 URL paths 的 Regex patterns。

**excludeDomains** (`string[]`): 用於排除特定 domains 的 Regex patterns。

**allowExternal** (`boolean`): 是否跟隨前往外部 domains 的連結。

**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`): 從基礎 URL 開始建立網站地圖的最大深度。

**maxBreadth** (`number`): 每個頁面最多可跟隨的連結數目。

**limit** (`number`): 網站地圖工具停止前處理的連結總數。

**instructions** (`string`): 提供給網站地圖工具的自然語言指示。

**selectPaths** (`string[]`): 用於選取特定 URL paths 的 Regex patterns。

**selectDomains** (`string[]`): 用於限制為特定 domains 的 Regex patterns。

**excludePaths** (`string[]`): 用於排除特定 URL paths 的 Regex patterns。

**excludeDomains** (`string[]`): 用於排除特定 domains 的 Regex patterns。

**allowExternal** (`boolean`): 是否包含外部 domain 的連結。

### 輸出

**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。當 factory function 未有傳入 `apiKey` 時，預設使用此值。 |

## 相關內容

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