Tools Tavily

Le package @mastra/tavily encapsule l’API Tavily 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(), accompagné de schémas Zod complets d’entrée et de sortie.

Installation

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

Démarrage rapide

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

src/mastra/tools/index.ts

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 :

src/mastra/tools/index.ts

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

= 'mastra'

Chaîne d’attribution envoyée avec chaque requête dans l’en-tête X-Client-Name.

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.

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

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.

SearchResult

title:

string

Titre du résultat.

url:

string

URL du résultat.

content:

string

Extrait de contenu.

score:

number

Score de pertinence.

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

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'

= 'markdown'

Format de sortie du contenu extrait.

Sortie

results:

ExtractResult[]

Pages extraites avec succès.

ExtractResult

url:

string

URL de la page.

rawContent:

string

Contenu extrait de la page.

images?:

string[]

URL des images extraites.

failedResults:

FailedResult[]

URL dont l’extraction a échoué.

FailedResult

url:

string

URL ayant échoué.

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

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'

= 'markdown'

Format de sortie du contenu extrait.

Sortie

baseUrl:

string

URL racine qui a été explorée.

results:

CrawlResult[]

Contenu extrait des pages découvertes.

CrawlResult

url:

string

URL de la page.

rawContent:

string

Contenu extrait de la page.

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

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 :

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

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()
• Documentation de l’API Tavily