メインコンテンツへ移動

Tavily tools

@mastra/tavily パッケージは、Tavily API を Mastra 互換の Tool としてラップします。検索、抽出、クロール、マップ用のファクトリー関数を公開しています。各関数は、完全な Zod 入出力スキーマを備えた createTool() で作成された Tool を返します。

インストール
インストールへの直接リンク

npm install @mastra/tavily @tavily/core zod

クイックスタート
クイックスタートへの直接リンク

共通設定を使用する4つの Tool をすべて取得するには、createTavilyTools() を使用します。

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 } を渡すと上書きできます。

設定
設定への直接リンク

すべてのファクトリー関数は、@tavily/core の TavilyClientOptions を受け取ります。

apiKey?:

string
Tavily API キー。指定しない場合は環境変数 TAVILY_API_KEY を使用します。

clientName?:

string
= 'mastra'
各リクエストの X-Client-Name ヘッダーで送信される属性文字列。

apiBaseURL?:

string
Tavily API のベース URL。

proxies?:

object
基盤となる HTTP クライアントに渡すプロキシ設定。

projectId?:

string
リクエストのスコープ設定に使用する Tavily プロジェクト ID。

createTavilyTools()
createtavilytoolsへの直接リンク

共通設定を使用する4つの 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 を使用して Web を検索する 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への直接リンク

1つ以上の URL からコンテンツを抽出する Tool を作成します。1回のリクエストにつき最大20件の URL から、生のページコンテンツを Markdown またはテキスト形式で返します。

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 を起点に Web サイトをクロールする Tool を作成します。設定可能な深さ、幅、ドメイン制約に従って、検出したページからコンテンツを抽出します。

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 パスを選択する正規表現パターン。

selectDomains?:

string[]
特定のドメインに限定する正規表現パターン。

excludePaths?:

string[]
特定の URL パスを除外する正規表現パターン。

excludeDomains?:

string[]
特定のドメインを除外する正規表現パターン。

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 を起点に Web サイトの構造をマッピングする Tool を作成します。ページコンテンツは抽出せず、URL を検出して一覧を返します。対象を絞った抽出の前にサイト構造を把握するために使用します。

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 パスを選択する正規表現パターン。

selectDomains?:

string[]
特定のドメインに限定する正規表現パターン。

excludePaths?:

string[]
特定の URL パスを除外する正規表現パターン。

excludeDomains?:

string[]
特定のドメインを除外する正規表現パターン。

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_KEYTavily API キー。ファクトリー関数に apiKey を渡さなかった場合のデフォルトとして使用されます。
On this page