Tavily is a specialized search API designed specifically for LLMs, enabling developers to build AI applications that can access real-time, accurate web data. Let's use the Python SDK to build with tavily.

Prerequisites

Tavily API Key Required - Get your key at https://tavily.com

Add to ~/.claude/settings.json:

{
  "env": {
    "TAVILY_API_KEY": "tvly-your-api-key-here"
  }
}

Restart Claude Code after adding your API key.

Tavily Python SDK

Installation

pip install tavily-python

Client Initialization

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# Or use environment variable TAVILY_API_KEY
client = TavilyClient()

Async client:

The async client enables parallel query execution, ideal for agentic workflows that need to gather information quickly before passing it to a model for analysis.

from tavily import AsyncTavilyClient

async_client = AsyncTavilyClient(api_key="tvly-YOUR_API_KEY")

Available Endpoints

| search() | Web search | real time data retrieval from the web

| extract() | Scrape content from URLs | Page content extraction

| crawl() and map() | Traverse website structures and simultaneously scrape pages | Documentation, site-wide extraction

| research | Out of the box research agent | ready-to-use iterative research

Choosing the Right Method

If you are building a custom agent or agentic workflow:

| Web search results | search()

| Content from specific URLs | extract()

| Content from an entire site | crawl()

| URL discovery from a site | map()

These methods give you full control but require additional work: data processing, LLM integration, and workflow orchestration.

If you want an out-of-the-box solution:

| End-to-end research with AI synthesis and built-in context engineering | research()

The research endpoint provides faster time-to-value with AI-synthesized insights, but offers less flexibility than building custom workflows.

Detailed Guides

For detailed usage instructions, parameters, patterns, and best practices:

references/search.md — Query optimization, filtering, async patterns, post-filtering strategies (regex + LLM verification)
references/extract.md — One-step vs two-step extraction, advanced mode, research pipelines
references/crawl.md — Crawl vs Map, depth/breadth control, path patterns, performance optimization
references/research.md — Usage, Streaming, structured output, polling

tavily-api-expert

安装