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

# Tools Tavily

Le package `@mastra/tavily` encapsule l’API [Tavily](https://app.tavily.com) sous forme de Tools compatibles avec Mastra. Il expose des fonctions de fabrique pour la recherche, l’extraction, l’exploration et la cartographie. Chaque fonction renvoie un Tool créé avec [`createTool()`](https://mastra.zisheng.pro/fr/reference/tools/create-tool), accompagné de schémas Zod complets d’entrée et de sortie.

## Installation

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

## Démarrage rapide

Utilisez `createTavilyTools()` pour obtenir les quatre Tools avec une configuration partagée :

```typescript
import { createTavilyTools } from '@mastra/tavily'

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

Chaque Tool peut également être créé séparément :

```typescript
import { createTavilySearchTool, createTavilyExtractTool } from '@mastra/tavily'

const searchTool = createTavilySearchTool()
const extractTool = createTavilyExtractTool({ apiKey: 'tvly-...' })
```

Par défaut, tous les Tools lisent `TAVILY_API_KEY` dans l’environnement. Vous pouvez transmettre explicitement `{ apiKey }` pour remplacer cette valeur.

## Configuration

Toutes les fonctions de fabrique acceptent `TavilyClientOptions` provenant de `@tavily/core` :

**apiKey** (`string`): Clé d’API Tavily. Utilise la variable d’environnement TAVILY\_API\_KEY comme valeur de repli.

**clientName** (`string`): Chaîne d’attribution envoyée avec chaque requête dans l’en-tête X-Client-Name. (Default: `'mastra'`)

**apiBaseURL** (`string`): URL de base de l’API Tavily.

**proxies** (`object`): Configuration du proxy transmise au client HTTP sous-jacent.

**projectId** (`string`): ID du projet Tavily servant à délimiter les requêtes.

## `createTavilyTools()`

Renvoie un objet contenant les quatre Tools avec une configuration partagée.

```typescript
import { createTavilyTools } from '@mastra/tavily'

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

**Renvoie :** `{ tavilySearch, tavilyExtract, tavilyCrawl, tavilyMap }`

## `createTavilySearchTool()`

Crée un Tool qui effectue des recherches sur le Web avec Tavily. Renvoie des résultats pertinents accompagnés d’extraits de contenu, de réponses facultatives générées par l’IA et d’images.

**ID du Tool :** `tavily-search`

```typescript
import { createTavilySearchTool } from '@mastra/tavily'

const searchTool = createTavilySearchTool()
```

### Entrée

**query** (`string`): Requête de recherche.

**searchDepth** (`'basic' | 'advanced' | 'fast' | 'ultra-fast'`): Profondeur de recherche. Utilisez 'basic' pour des résultats standard, 'advanced' pour des résultats plus complets, ou 'fast'/'ultra-fast' pour une faible latence.

**maxResults** (`number`): Nombre maximal de résultats à renvoyer (1 à 20).

**includeAnswer** (`boolean | 'basic' | 'advanced'`): Inclut un résumé de réponse généré par l’IA.

**includeImages** (`boolean`): Inclut dans la réponse les images liées à la requête.

**includeImageDescriptions** (`boolean`): Inclut une description des images renvoyées.

**includeRawContent** (`false | 'markdown' | 'text'`): Inclut le contenu HTML nettoyé de chaque résultat. Transmettez false pour le désactiver, ou 'markdown'/'text' pour choisir le format.

**includeDomains** (`string[]`): Limite les résultats à ces domaines.

**excludeDomains** (`string[]`): Exclut les résultats provenant de ces domaines.

**timeRange** (`'day' | 'week' | 'month' | 'year'`): Filtre les résultats selon leur récence.

### Sortie

**query** (`string`): Requête de recherche d’origine.

**answer** (`string`): Résumé de réponse généré par l’IA.

**images** (`{ url: string; description?: string }[]`): Images associées.

**results** (`SearchResult[]`): Tableau des résultats de recherche.

**results.title** (`string`): Titre du résultat.

**results.url** (`string`): URL du résultat.

**results.content** (`string`): Extrait de contenu.

**results.score** (`number`): Score de pertinence.

**results.rawContent** (`string`): Contenu de la page entière (si demandé).

**responseTime** (`number`): Temps de réponse du serveur, en secondes.

## `createTavilyExtractTool()`

Crée un Tool qui extrait le contenu d’une ou plusieurs URL. Renvoie le contenu brut des pages au format Markdown ou texte, avec un maximum de 20 URL par requête.

**ID du Tool :** `tavily-extract`

```typescript
import { createTavilyExtractTool } from '@mastra/tavily'

const extractTool = createTavilyExtractTool()
```

### Entrée

**urls** (`string[]`): URL dont extraire le contenu (1 à 20).

**extractDepth** (`'basic' | 'advanced'`): Profondeur d’extraction. Utilisez 'advanced' pour récupérer les tableaux et le contenu intégré.

**query** (`string`): Intention de l’utilisateur servant à reclasser les fragments de contenu extrait selon leur pertinence.

**includeImages** (`boolean`): Inclut les images extraites des pages.

**format** (`'markdown' | 'text'`): Format de sortie du contenu extrait. (Default: `'markdown'`)

### Sortie

**results** (`ExtractResult[]`): Pages extraites avec succès.

**results.url** (`string`): URL de la page.

**results.rawContent** (`string`): Contenu extrait de la page.

**results.images** (`string[]`): URL des images extraites.

**failedResults** (`FailedResult[]`): URL dont l’extraction a échoué.

**failedResults.url** (`string`): URL ayant échoué.

**failedResults.error** (`string`): Message d’erreur.

**responseTime** (`number`): Temps de réponse du serveur, en secondes.

## `createTavilyCrawlTool()`

Crée un Tool qui explore un site Web à partir d’une URL. Extrait le contenu des pages découvertes avec des contraintes configurables de profondeur, d’étendue et de domaine.

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

```typescript
import { createTavilyCrawlTool } from '@mastra/tavily'

const crawlTool = createTavilyCrawlTool()
```

### Entrée

**url** (`string`): URL racine à partir de laquelle commencer l’exploration.

**maxDepth** (`number`): Profondeur maximale de l’exploration depuis l’URL de base.

**maxBreadth** (`number`): Nombre maximal de liens à suivre par page.

**limit** (`number`): Nombre total de pages traitées par l’explorateur avant son arrêt.

**instructions** (`string`): Instructions en langage naturel destinées à l’explorateur.

**selectPaths** (`string[]`): Expressions régulières permettant de sélectionner des chemins d’URL précis.

**selectDomains** (`string[]`): Expressions régulières permettant de limiter l’exploration à certains domaines.

**excludePaths** (`string[]`): Expressions régulières permettant d’exclure certains chemins d’URL.

**excludeDomains** (`string[]`): Expressions régulières permettant d’exclure certains domaines.

**allowExternal** (`boolean`): Indique s’il faut suivre les liens vers des domaines externes.

**extractDepth** (`'basic' | 'advanced'`): Profondeur d’extraction. Utilisez 'advanced' pour récupérer les tableaux et le contenu intégré.

**includeImages** (`boolean`): Inclut les images des pages explorées.

**format** (`'markdown' | 'text'`): Format de sortie du contenu extrait. (Default: `'markdown'`)

### Sortie

**baseUrl** (`string`): URL racine qui a été explorée.

**results** (`CrawlResult[]`): Contenu extrait des pages découvertes.

**results.url** (`string`): URL de la page.

**results.rawContent** (`string`): Contenu extrait de la page.

**results.images** (`string[]`): URL des images trouvées sur la page.

**responseTime** (`number`): Temps de réponse du serveur, en secondes.

## `createTavilyMapTool()`

Crée un Tool qui cartographie la structure d’un site Web à partir d’une URL. Découvre et renvoie une liste d’URL sans extraire le contenu des pages. Utilisez-le pour comprendre la structure du site avant une extraction ciblée.

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

```typescript
import { createTavilyMapTool } from '@mastra/tavily'

const mapTool = createTavilyMapTool()
```

### Entrée

**url** (`string`): URL racine à partir de laquelle commencer la cartographie.

**maxDepth** (`number`): Profondeur maximale de la cartographie depuis l’URL de base.

**maxBreadth** (`number`): Nombre maximal de liens à suivre par page.

**limit** (`number`): Nombre total de liens traités par l’outil de cartographie avant son arrêt.

**instructions** (`string`): Instructions en langage naturel destinées à l’outil de cartographie.

**selectPaths** (`string[]`): Expressions régulières permettant de sélectionner des chemins d’URL précis.

**selectDomains** (`string[]`): Expressions régulières permettant de limiter la cartographie à certains domaines.

**excludePaths** (`string[]`): Expressions régulières permettant d’exclure certains chemins d’URL.

**excludeDomains** (`string[]`): Expressions régulières permettant d’exclure certains domaines.

**allowExternal** (`boolean`): Indique s’il faut inclure les liens vers des domaines externes.

### Sortie

**baseUrl** (`string`): URL racine qui a été cartographiée.

**results** (`string[]`): URL découvertes.

**responseTime** (`number`): Temps de réponse du serveur, en secondes.

## Exemple d’Agent

L’exemple suivant présente un Agent de recherche qui combine la recherche et l’extraction :

```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(),
  },
})
```

## Variables d’environnement

| Variable         | Description                                                                                                 |
| ---------------- | ----------------------------------------------------------------------------------------------------------- |
| `TAVILY_API_KEY` | Votre clé d’API Tavily. Utilisée par défaut lorsque `apiKey` n’est pas transmis à une fonction de fabrique. |

## Ressources associées

- [`createTool()`](https://mastra.zisheng.pro/fr/reference/tools/create-tool)
- [Documentation de l’API Tavily](https://docs.tavily.com)