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

# Tavily Tools

`@mastra/tavily` 套件會將 [Tavily](https://app.tavily.com) API 包裝為相容於 Mastra 的 Tool。它提供搜尋、擷取、爬取與網站結構對應的 factory function。每個函式都會回傳以 [`createTool()`](https://mastra.zisheng.pro/zh-TW/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/zh-TW/reference/tools/create-tool)
- [Tavily API 文件](https://docs.tavily.com)