tavily-best-practices

Tavily is a web-search service built for AI apps to call, and this is the guide to wiring it into your own Python or JavaScript program and picking the right call for the job.

WHEN TO USE

SCOPE

USE FOR

Add Tavily web search or content extraction to a Python or JavaScript agent.
Decide which Tavily method to call: search, extract, crawl, map, or research.
Wire Tavily results into LangChain, LlamaIndex, CrewAI, or the Vercel AI SDK.
Blend live web results with your own stored documents when answering a question.

This is a saved copy of the skill's SKILL.md instructions. It may differ from the upstream file or the version you install.

In this document (6)

Tavily

Tavily is a search API designed for LLMs, enabling AI applications to access real-time web data.

Installation

Python:

pip install tavily-python

JavaScript:

npm install @tavily/core

See references/sdk.md for complete SDK reference.

Client Initialization

from tavily import TavilyClient

# Uses TAVILY_API_KEY env var (recommended)
client = TavilyClient()

#With project tracking (for usage organization)
client = TavilyClient(project_id="your-project-id")

# Async client for parallel queries
from tavily import AsyncTavilyClient
async_client = AsyncTavilyClient()

Choosing the Right Method

For custom agents/workflows:

Need	Method
Web search results	`search()`
Content from specific URLs	`extract()`
Content from entire site	`crawl()`
URL discovery from site	`map()`

For out-of-the-box research:

Need	Method
End-to-end research with AI synthesis	`research()`

Quick Reference

search() - Web Search

response = client.search(
    query="quantum computing breakthroughs",  # Keep under 400 chars
    max_results=10,
    search_depth="advanced"
)
print(response)

Key parameters: query, max_results, search_depth (ultra-fast/fast/basic/advanced), include_domains, exclude_domains, time_range

See references/search.md for complete search reference.

extract() - URL Content Extraction

# Simple one-step extraction
response = client.extract(
    urls=["https://docs.example.com"],
    extract_depth="advanced"
)
print(response)

Key parameters: urls (max 20), extract_depth, query, chunks_per_source (1-5)

See references/extract.md for complete extract reference.

crawl() - Site-Wide Extraction

response = client.crawl(
    url="https://docs.example.com",
    instructions="Find API documentation pages",  # Semantic focus
    extract_depth="advanced"
)
print(response)

Key parameters: url, max_depth, max_breadth, limit, instructions, chunks_per_source, select_paths, exclude_paths

See references/crawl.md for complete crawl reference.

map() - URL Discovery

response = client.map(
    url="https://docs.example.com"
)
print(response)

research() - AI-Powered Research

import time

# For comprehensive multi-topic research
result = client.research(
    input="Analyze competitive landscape for X in SMB market",
    model="pro"  # or "mini" for focused queries, "auto" when unsure
)
request_id = result["request_id"]

# Poll until completed
response = client.get_research(request_id)
while response["status"] not in ["completed", "failed"]:
    time.sleep(10)
    response = client.get_research(request_id)

print(response["content"])  # The research report

Key parameters: input, model ("mini"/"pro"/"auto"), stream, output_schema, citation_format

See references/research.md for complete research reference.

Detailed Guides

For complete parameters, response fields, patterns, and examples:

references/sdk.md - Python & JavaScript SDK reference, async patterns, Hybrid RAG
references/search.md - Query optimization, search depth selection, domain filtering, async patterns, post-filtering
references/extract.md - One-step vs two-step extraction, query/chunks for targeting, advanced mode
references/crawl.md - Crawl vs Map, instructions for semantic focus, use cases, Map-then-Extract pattern
references/research.md - Prompting best practices, model selection, streaming, structured output schemas
references/integrations.md - LangChain, LlamaIndex, CrewAI, Vercel AI SDK, and framework integrations

This skill ships inside the Tavily Agent Skills plugin.

Run this outside your AI tool, using Node.js 22.20.0 or newer. Skills CLI 1.7.2 skips skill selection; prompts cancel installation without an interactive terminal. If choosing Project when asked about installation scope, open your project's folder before running this.

Install checklist

Check selected tools if a picker appears; Claude Code may be unchecked under Additional agents. ↑/↓ moves, Space toggles selections, Enter confirms.
Without a tool picker, check Installing to: for your intended tool. Stop if it names a different tool.
If asked, choose Symlink (Recommended) for shared files or Copy to all agents for separate copies; review the summary before confirming installation.
Install the find-skills skill? defaults to Yes, adding another skill for all projects. Choose No if you don't want that extra installation.

Skills CLI 1.7.2 sends install data to skills.sh by default, including the source, skill names, target tools and file details; GitHub sources are reported only when GitHub confirms the repository is public, while other remote sources can also be reported. Confirmed-public GitHub sources also trigger a security-audit request. Before installing, set the environment variable DO_NOT_TRACK=1 or DISABLE_TELEMETRY=1 to disable both.

npx skills add tavily-ai/skills --skill "tavily-best-practices" --full-depth

After installing for Claude Code, open it in the installation project if you chose Project; Global makes the skill available across projects on this computer. Once Claude Code loads the skill, its description helps Claude decide when to use it.

If installation created a top-level skills folder that did not exist when your Claude Code session started, run /reload-skills in that session. Run it again after later changes in that folder.

What's inside

Files included with this skill.

View on GitHub

Same repository

tavily-cli
Set up, authenticate, update, troubleshoot, or choose between Tavily CLI web commands. Use when the user asks about the Tavily CLI, installing Tavily skills, first-time setup, authentication, keyless limits, CLI updates, or which Tavily command to use. For an ordinary web task, use the specific search, extract, map, crawl, research, or dynamic-search skill instead.Read full description
tavily-crawl
Crawl websites and extract content from multiple pages via the Tavily CLI. Use this skill when the user wants to crawl a site, download documentation, extract an entire docs section, bulk-extract pages, save a site as local markdown files, or says "crawl", "get all the pages", "download the docs", "extract everything under /docs", "bulk extract", or needs content from many pages on the same domain. Supports depth/breadth control, path filtering, semantic instructions, and saving each page as a local markdown file.Read full description
tavily-dynamic-search
Programmatic Tavily search with context isolation. Use when web search or extraction will return large results that need filtering, deduplication, or multi-step triage before they enter the model context. Use tavily-search for ordinary lookups and tavily-research for end-to-end cited synthesis.Read full description
tavily-extract
Extract clean markdown or text content from specific URLs via the Tavily CLI. Use this skill when the user has one or more URLs and wants their content, says "extract", "grab the content from", "pull the text from", "get the page at", "read this webpage", or needs clean text from web pages. Handles JavaScript-rendered pages, returns LLM-optimized markdown, and supports query-focused chunking for targeted extraction. Can process up to 20 URLs in a single call.Read full description
tavily-map
Discover and list all URLs on a website without extracting content, via the Tavily CLI. Use this skill when the user wants to find a specific page on a large site, list all URLs, see the site structure, find where something is on a domain, or says "map the site", "find the URL for", "what pages are on", "list all pages", or "site structure". Faster than crawling — returns URLs only. Essential when you know the site but not the exact page. Combine with extract for targeted content retrieval.Read full description
tavily-research
Conduct comprehensive AI-powered research with citations via the Tavily CLI. Use this skill when the user wants deep research, a detailed report, a comparison, market analysis, literature review, or says "research", "investigate", "analyze in depth", "compare X vs Y", "what does the market look like for", or needs multi-source synthesis with explicit citations. Returns a structured report grounded in web sources. Takes 30-120 seconds. For quick fact-finding, use tavily-search instead.Read full description