跳至主要內容

Tavily tools

@mastra/tavily 套件將 Tavily API 封裝成與 Mastra 兼容的 tools。它提供用於搜尋、擷取、爬取及建立網站地圖的 factory functions。每個 function 都會傳回以 createTool() 建立的 Tool，並包含完整的 Zod 輸入／輸出 schema。

安裝
安裝 的直接連結

npm install @mastra/tavily @tavily/core zod

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

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

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

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

設定
設定 的直接連結

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

apiKey?:

string
Tavily API key。如未提供，則使用 TAVILY_API_KEY 環境變數。

clientName?:

string
= 'mastra'
隨每個請求在 X-Client-Name header 中傳送的署名字串。

apiBaseURL?:

string
Tavily API 的基礎 URL。

proxies?:

object
傳遞至底層 HTTP client 的 proxy 設定。

projectId?:

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

createTavilyTools()
createtavilytools 的直接連結

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

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

excludeDomains?:

string[]
從結果中排除這些 domains。

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

Tool ID： tavily-crawl

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'
= '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
從基礎 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 範例 的直接連結

以下範例示範結合搜尋和擷取功能的研究 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。當 factory function 未有傳入 apiKey 時，預設使用此值。
On this page