Tavily

Objectif

Fournir une interface basée sur curl pour l'API REST de Tavily pour la recherche web, l'extraction, la cartographie, le crawling et la recherche optionnelle. Retourner des résultats structurés adaptés aux workflows LLM et aux investigations multi-étapes.

Quand l'utiliser

• Utiliser quand une tâche nécessite des informations web en direct, l'extraction de sites, la cartographie ou le crawling.
• Utiliser quand des recherches web sont nécessaires et qu'aucun outil intégré n'est disponible, ou quand la sortie compatible LLM de Tavily (résumés, chunks, sources, citations) est bénéfique.
• Utiliser quand une tâche nécessite des résultats de recherche structurés, l'extraction ou la découverte de sites à partir de Tavily.

Environnement requis

• Nécessite TAVILY_API_KEY dans l'environnement.
• Si TAVILY_API_KEY manque, inviter l'utilisateur à fournir la clé API avant de continuer.

URL de base et authentification

• URL de base : https://api.tavily.com
• Authentification : Authorization: Bearer $TAVILY_API_KEY
• Type de contenu : Content-Type: application/json
• Suivi de projet optionnel : ajouter X-Project-ID: <project-id> si l'attribution de projet est nécessaire.

Cartographie des outils (REST Tavily)

1) search → POST /search

Utiliser pour la recherche web avec extraction optionnelle de réponse et de contenu.

Requête minimale recommandée :

curl -sS -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "query": "<query>",
    "search_depth": "basic",
    "max_results": 5,
    "include_answer": true,
    "include_raw_content": false,
    "include_images": false
  }'

Paramètres clés (tous optionnels sauf mention) :

• query (requis) : texte de recherche
• search_depth : basic | advanced | fast | ultra-fast
• chunks_per_source : 1–3 (advanced uniquement)
• max_results : 0–20
• topic : general | news | finance
• time_range : day|week|month|year|d|w|m|y
• start_date, end_date : YYYY-MM-DD
• include_answer : false | true | basic | advanced
• include_raw_content : false | true | markdown | text
• include_images : booléen
• include_image_descriptions : booléen
• include_favicon : booléen
• include_domains, exclude_domains : tableaux de chaînes
• country : nom du pays (topic general uniquement)
• auto_parameters : booléen
• include_usage : booléen

Champs de réponse attendus :

• answer (si demandé), results[] avec title, url, content, score, raw_content (optionnel), favicon (optionnel)
• response_time, usage, request_id

2) extract → POST /extract

Utiliser pour extraire le contenu d'URLs spécifiques.

curl -sS -X POST "https://api.tavily.com/extract" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "urls": ["https://example.com/article"],
    "query": "<optional intent for reranking>",
    "chunks_per_source": 3,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false,
    "include_favicon": false
  }'

Paramètres clés :

• urls (requis) : tableau d'URLs
• query : reclasser les chunks par intention
• chunks_per_source : 1–5 (uniquement si query fourni)
• extract_depth : basic | advanced
• format : markdown | text
• timeout : 1–60 secondes
• include_usage : booléen

Champs de réponse attendus :

• results[] avec url, raw_content, images, favicon
• failed_results[], response_time, usage, request_id

3) map → POST /map

Utiliser pour générer une cartographie de site (découverte d'URL uniquement).

curl -sS -X POST "https://api.tavily.com/map" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "allow_external": true
  }'

Paramètres clés :

• url (requis)
• instructions : guide en langage naturel (augmente le coût)
• max_depth : 1–5
• max_breadth : 1+
• limit : 1+
• select_paths, select_domains, exclude_paths, exclude_domains : tableaux de chaînes regex
• allow_external : booléen
• timeout : 10–150 secondes
• include_usage : booléen

Champs de réponse attendus :

• base_url, results[] (liste d'URLs), response_time, usage, request_id

4) crawl → POST /crawl

Utiliser pour la traversée de site avec extraction intégrée.

curl -sS -X POST "https://api.tavily.com/crawl" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "url": "https://docs.tavily.com",
    "instructions": "Find all pages about the Python SDK",
    "max_depth": 1,
    "max_breadth": 20,
    "limit": 50,
    "extract_depth": "basic",
    "format": "markdown",
    "include_images": false
  }'

Paramètres clés :

• url (requis)
• instructions : optionnel ; augmente le coût et active chunks_per_source
• chunks_per_source : 1–5 (uniquement avec instructions)
• max_depth, max_breadth, limit : idem que map
• extract_depth : basic | advanced
• format : markdown | text
• include_images, include_favicon, allow_external
• timeout : 10–150 secondes
• include_usage : booléen

Champs de réponse attendus :

• base_url, results[] avec url, raw_content, favicon
• response_time, usage, request_id

Workflow de recherche optionnel (Investigation approfondie)

Utiliser quand une requête nécessite une analyse multi-étapes et des citations.

create research task → POST /research

curl -sS -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{
    "input": "<research question>",
    "model": "auto",
    "stream": false,
    "citation_format": "numbered"
  }'

Champs de réponse attendus :

• request_id, created_at, status (pending), input, model, response_time

get research status → GET /research/{request_id}

curl -sS -X GET "https://api.tavily.com/research/<request_id>" \
  -H "Authorization: Bearer $TAVILY_API_KEY"

Champs de réponse attendus :

• status : completed
• content : texte du rapport ou objet structuré
• sources[] : { title, url, favicon }

streaming research (SSE)

Définir "stream": true dans le corps POST et utiliser curl avec -N pour streamer les événements :

curl -N -X POST "https://api.tavily.com/research" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TAVILY_API_KEY" \
  -d '{"input":"<question>","stream":true,"model":"pro"}'

Gérer les événements SSE (tool calls, tool responses, content chunks, sources, done).

Notes d'utilisation

• Traiter search, extract, map et crawl comme les endpoints principaux pour la découverte et la récupération de contenu.
• Retourner des résultats structurés avec URLs, titres et résumés pour une utilisation facile en aval.
• Utiliser par défaut des paramètres conservateurs (search_depth: basic, max_results: 5) sauf si une meilleure couverture est nécessaire.
• Réutiliser des corps de requête cohérents entre les appels pour garder les résultats prévisibles.

Gestion des erreurs

• Si une requête retourne 401/403, inviter à fournir ou revérifier TAVILY_API_KEY.
• Si des timeouts surviennent, réduire max_depth/limit ou utiliser search_depth: basic.
• Si les réponses sont trop volumineuses, baisser max_results ou chunks_per_source.