Tavily Tools

@mastra/tavily 包将 Tavily API 封装为与 Mastra 兼容的 Tool。它提供搜索、提取、抓取和网站结构映射 factory function。每个函数都返回使用 createTool() 创建的 Tool，并包含完整的 Zod 输入/输出 schema。

安装

npm

npm install @mastra/tavily @tavily/core zod

pnpm

pnpm add @mastra/tavily @tavily/core zod

Yarn

yarn add @mastra/tavily @tavily/core zod

Bun

bun add @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()

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

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

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()

创建一个从一个或多个 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()

创建一个从指定 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()

创建一个从指定 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：

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，则缺省使用此值。

相关内容

• createTool()
• Tavily API 文档