tavily-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tavily

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

Tavily是一款为LLM设计的搜索API，可让AI应用访问实时网络数据。

Prerequisites

前提条件

Tavily API Key Required - Get your key at https://app.tavily.com (1,000 free API credits/month, no credit card required)

Add to

~/.claude/settings.json

json

{
  "env": {
    "TAVILY_API_KEY": "tvly-YOUR_API_KEY"
  }
}

Restart Claude Code after adding your API key.

需要Tavily API密钥 - 前往https://app.tavily.com获取密钥（每月1000个免费API额度，无需信用卡）

添加到

~/.claude/settings.json

中：

json

{
  "env": {
    "TAVILY_API_KEY": "tvly-YOUR_API_KEY"
  }
}

添加API密钥后重启Claude Code。

Installation

安装

Python:

bash

pip install tavily-python

JavaScript:

bash

npm install @tavily/core

See references/sdk.md for complete SDK reference.

Python：

bash

pip install tavily-python

JavaScript：

bash

npm install @tavily/core

完整SDK参考请查看**references/sdk.md**。

Client Initialization

客户端初始化

python

from tavily import TavilyClient

python

from tavily import TavilyClient

Option 1: Uses TAVILY_API_KEY env var (recommended)

选项1：使用TAVILY_API_KEY环境变量（推荐）

client = TavilyClient()

Option 2: Explicit API key

选项2：显式传入API密钥

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

Option 3: With project tracking (for usage organization)

选项3：带项目追踪（用于使用情况管理）

client = TavilyClient(api_key="tvly-YOUR_API_KEY", project_id="your-project-id")

Async client for parallel queries

用于并行查询的异步客户端

from tavily import AsyncTavilyClient async_client = AsyncTavilyClient()

undefined

from tavily import AsyncTavilyClient async_client = AsyncTavilyClient()

undefined

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

适用于自定义Agent/工作流：

需求	方法
网页搜索结果	`search()`
特定URL的内容	`extract()`
整个站点的内容	`crawl()`
站点中的URL发现	`map()`

适用于开箱即用的研究场景：

需求	方法
带AI合成的端到端研究	`research()`

Quick Reference

快速参考

search() - Web Search

search() - 网页搜索

python

response = client.search(
    query="quantum computing breakthroughs",  # Keep under 400 chars
    max_results=10,
    search_depth="advanced",  # 2 credits, highest relevance
    topic="general"  # or "news", "finance"
)

for result in response["results"]:
    print(f"{result['title']}: {result['score']}")

Key parameters:

query

max_results

search_depth

(ultra-fast/fast/basic/advanced),

topic

include_domains

exclude_domains

time_range

python

response = client.search(
    query="quantum computing breakthroughs",  # 保持在400字符以内
    max_results=10,
    search_depth="advanced",  # 2个额度，相关性最高
    topic="general"  # 或 "news"、"finance"
)

for result in response["results"]:
    print(f"{result['title']}: {result['score']}")

关键参数：

query

、

max_results

、

search_depth

（ultra-fast/fast/basic/advanced）、

topic

、

include_domains

、

exclude_domains

、

time_range

extract() - URL Content Extraction

extract() - URL内容提取

python

undefined

python

undefined

Two-step pattern (recommended for control)

两步式模式（推荐用于精准控制）

search_results = client.search(query="Python async best practices") urls = [r["url"] for r in search_results["results"] if r["score"] > 0.5] extracted = client.extract( urls=urls[:20], query="async patterns", # Reranks chunks by relevance chunks_per_source=3 # Prevents context explosion )


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

search_results = client.search(query="Python async best practices") urls = [r["url"] for r in search_results["results"] if r["score"] > 0.5] extracted = client.extract( urls=urls[:20], query="async patterns", # 根据相关性重新排序内容块 chunks_per_source=3 # 避免上下文过载 )


关键参数：`urls`（最多20个）、`extract_depth`、`query`、`chunks_per_source`（1-5）

crawl() - Site-Wide Extraction

crawl() - 全站内容提取

python

response = client.crawl(
    url="https://docs.example.com",
    max_depth=2,
    instructions="Find API documentation pages",  # Semantic focus
    chunks_per_source=3,  # Token optimization
    select_paths=["/docs/.*", "/api/.*"]
)

Key parameters:

url

max_depth

max_breadth

limit

instructions

chunks_per_source

select_paths

exclude_paths

python

response = client.crawl(
    url="https://docs.example.com",
    max_depth=2,
    instructions="Find API documentation pages",  # 语义聚焦
    chunks_per_source=3,  # Token优化
    select_paths=["/docs/.*", "/api/.*"]
)

关键参数：

url

、

max_depth

、

max_breadth

、

limit

、

instructions

、

chunks_per_source

、

select_paths

、

exclude_paths

map() - URL Discovery

map() - URL发现

python

response = client.map(
    url="https://docs.example.com",
    max_depth=2,
    instructions="Find all API and guide pages"
)
api_docs = [url for url in response["results"] if "/api/" in url]

python

response = client.map(
    url="https://docs.example.com",
    max_depth=2,
    instructions="Find all API and guide pages"
)
api_docs = [url for url in response["results"] if "/api/" in url]

research() - AI-Powered Research

research() - AI驱动的研究

python

import time

python

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"]

result = client.research( input="Analyze competitive landscape for X in SMB market", model="pro" # 或 "mini"用于聚焦查询，不确定时用"auto" ) 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`

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"]) # 研究报告


关键参数：`input`、`model`（"mini"/"pro"/"auto"）、`stream`、`output_schema`、`citation_format`

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

如需完整参数、响应字段、模式和示例，请查看：

references/sdk.md - Python & JavaScript SDK参考、异步模式、混合RAG
references/search.md - 查询优化、搜索深度选择、域名过滤、异步模式、后过滤
references/extract.md - 一步式vs两步式提取、目标查询/内容块、高级模式
references/crawl.md - Crawl与Map对比、语义聚焦指令、使用场景、Map-then-Extract模式
references/research.md - 提示词最佳实践、模型选择、流式传输、结构化输出 schema
references/integrations.md - LangChain、LlamaIndex、CrewAI、Vercel AI SDK及框架集成