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

# Tavily tools

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

## インストール

**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
```

## クイックスタート

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

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

## 設定

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

**apiKey** (`string`): Tavily API キー。指定しない場合は環境変数 TAVILY\_API\_KEY を使用します。

**clientName** (`string`): 各リクエストの X-Client-Name ヘッダーで送信される属性文字列。 (Default: `'mastra'`)

**apiBaseURL** (`string`): Tavily API のベース URL。

**proxies** (`object`): 基盤となる HTTP クライアントに渡すプロキシ設定。

**projectId** (`string`): リクエストのスコープ設定に使用する Tavily プロジェクト ID。

## `createTavilyTools()`

共通設定を使用する4つの 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 を使用して Web を検索する 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()`

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

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

**Tool ID:** `tavily-crawl`

```typescript
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'`): 抽出したコンテンツの出力形式。 (Default: `'markdown'`)

### 出力

**baseUrl** (`string`): クロールしたルート URL。

**results** (`CrawlResult[]`): 検出したページから抽出されたコンテンツ。

**results.url** (`string`): ページの URL。

**results.rawContent** (`string`): 抽出されたページコンテンツ。

**results.images** (`string[]`): ページで見つかった画像の URL。

**responseTime** (`number`): サーバーのレスポンス時間（秒）。

## `createTavilyMapTool()`

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

**Tool ID:** `tavily-map`

```typescript
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 を示します。

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

## 関連項目

- [`createTool()`](https://mastra.zisheng.pro/ja/reference/tools/create-tool)
- [Tavily API ドキュメント](https://docs.tavily.com)