跳至主要內容

Tavily Tools

@mastra/tavily 套件會將 Tavily API 包裝為相容於 Mastra 的 Tool。它提供搜尋、擷取、爬取與網站結構對應的 factory function。每個函式都會回傳以 createTool() 建立的 Tool，並包含完整的 Zod 輸入／輸出 schema。

安裝
「安裝」的直接連結

npm install @mastra/tavily @tavily/core zod

快速開始
「快速開始」的直接連結

使用 createTavilyTools() 以共用設定取得全部四個 Tool：

src/mastra/tools/index.ts
import { createTavilyTools } from '@mastra/tavily'

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

你也可以分別建立每個 Tool：

src/mastra/tools/index.ts
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
= 'mastra'
每次請求時透過 X-Client-Name header 傳送的歸屬字串。

apiBaseURL?:

string
Tavily API 的 base URL。

proxies?:

object
傳給底層 HTTP client 的 proxy 設定。

projectId?:

string
用於限定請求範圍的 Tavily project ID。

createTavilyTools()
「createtavilytools」的直接連結

回傳一個物件，其中包含共用設定的全部四個 Tool。

import { createTavilyTools } from '@mastra/tavily'

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

回傳值： { tavilySearch, tavilyExtract, tavilyCrawl, tavilyMap }

createTavilySearchTool()
「createtavilysearchtool」的直接連結

建立一個使用 Tavily 搜尋網路的 Tool。它會回傳相關結果，包括內容摘要、選填的 AI 產生答案與圖片。

Tool ID： tavily-search

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[]
搜尋結果陣列。
SearchResult

title:

string
結果標題。

url:

string
結果 URL。

content:

string
內容摘要。

score:

number
相關性分數。

rawContent?:

string
完整頁面內容（提出要求時）。

responseTime:

number
伺服器回應時間（秒）。

createTavilyExtractTool()
「createtavilyextracttool」的直接連結

建立一個從一個或多個 URL 擷取內容的 Tool。它會以 Markdown 或文字格式回傳原始頁面內容，每次請求最多可處理 20 個 URL。

Tool ID： tavily-extract

import { createTavilyExtractTool } from '@mastra/tavily'

const extractTool = createTavilyExtractTool()

輸入
「輸入」的直接連結

urls:

string[]
要擷取內容的 URL（1–20 個）。

extractDepth?:

'basic' | 'advanced'
擷取深度。使用 'advanced' 可擷取表格與嵌入內容。

query?:

string
使用者意圖，用來依相關性對擷取的內容區塊重新排序。

includeImages?:

boolean
包含從頁面擷取的圖片。

format?:

'markdown' | 'text'
= 'markdown'
擷取內容的輸出格式。

輸出
「輸出」的直接連結

results:

ExtractResult[]
成功擷取的頁面。
ExtractResult

url:

string
頁面 URL。

rawContent:

string
擷取的頁面內容。

images?:

string[]
擷取的圖片 URL。

failedResults:

FailedResult[]
擷取失敗的 URL。
FailedResult

url:

string
失敗的 URL。

error:

string
錯誤訊息。

responseTime:

number
伺服器回應時間（秒）。

createTavilyCrawlTool()
「createtavilycrawltool」的直接連結

建立一個從指定 URL 開始爬取網站的 Tool。它會從找到的頁面擷取內容，並可設定深度、廣度與網域限制。

Tool ID： tavily-crawl

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'
= 'markdown'
擷取內容的輸出格式。

輸出
「輸出」的直接連結

baseUrl:

string
已爬取的根 URL。

results:

CrawlResult[]
從找到的頁面擷取的內容。
CrawlResult

url:

string
頁面 URL。

rawContent:

string
擷取的頁面內容。

images?:

string[]
頁面上找到的圖片 URL。

responseTime:

number
伺服器回應時間（秒）。

createTavilyMapTool()
「createtavilymaptool」的直接連結

建立一個從指定 URL 開始對應網站結構的 Tool。它會探索並回傳 URL 清單，但不擷取頁面內容。可在針對特定目標擷取前，使用此 Tool 了解網站結構。

Tool ID： tavily-map

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 範例」的直接連結

下列範例示範結合搜尋與擷取功能的研究 Agent：

src/mastra/agents/index.ts
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，則預設使用此值。
On this page