tavily

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tavily AI Search

Tavily AI搜索

Overview

概述

Tavily is a search engine specifically optimized for Large Language Models and AI applications. Unlike traditional search APIs, Tavily provides AI-ready results with optional answer generation, clean content extraction, and domain filtering capabilities.

Key capabilities:

AI-generated answer summaries from search results
Clean, structured results optimized for LLM processing
Fast (
```
basic
```
) and comprehensive (
```
advanced
```
) search modes
Domain filtering (include/exclude specific sources)
News-focused search for current events
Image search with relevant visual content
Raw content extraction for deeper analysis

Tavily是专为大语言模型（LLM）和AI应用优化的搜索引擎。与传统搜索API不同，Tavily提供AI就绪的结果，支持可选的答案生成、清晰的内容提取和域名过滤功能。

核心功能：

基于搜索结果的AI生成答案摘要
针对LLM处理优化的清晰结构化结果
快速（
```
basic
```
）和全面（
```
advanced
```
）两种搜索模式
域名过滤（包含/排除特定来源）
聚焦时事的新闻搜索
含相关视觉内容的图片搜索
用于深度分析的原始内容提取

Architecture

架构

mermaid

graph TB
    A[User Query] --> B{Search Mode}
    B -->|basic| C[Fast Search<br/>1-2s response]
    B -->|advanced| D[Comprehensive Search<br/>5-10s response]
    
    C --> E[Tavily API]
    D --> E
    
    E --> F{Topic Filter}
    F -->|general| G[Broad Web Search]
    F -->|news| H[News Sources<br/>Last 7 days]
    
    G --> I[Domain Filtering]
    H --> I
    
    I --> J{Include Domains?}
    J -->|yes| K[Filter to Specific Domains]
    J -->|no| L{Exclude Domains?}
    K --> M[Search Results]
    L -->|yes| N[Remove Unwanted Domains]
    L -->|no| M
    N --> M
    
    M --> O{Response Options}
    O --> P[AI Answer<br/>Summary]
    O --> Q[Structured Results<br/>Title, URL, Content, Score]
    O --> R[Images<br/>if requested]
    O --> S[Raw HTML Content<br/>if requested]
    
    P --> T[Return to Agent]
    Q --> T
    R --> T
    S --> T
    
    style E fill:#4A90E2
    style P fill:#7ED321
    style Q fill:#7ED321
    style R fill:#F5A623
    style S fill:#F5A623

mermaid

graph TB
    A[User Query] --> B{Search Mode}
    B -->|basic| C[Fast Search<br/>1-2s response]
    B -->|advanced| D[Comprehensive Search<br/>5-10s response]
    
    C --> E[Tavily API]
    D --> E
    
    E --> F{Topic Filter}
    F -->|general| G[Broad Web Search]
    F -->|news| H[News Sources<br/>Last 7 days]
    
    G --> I[Domain Filtering]
    H --> I
    
    I --> J{Include Domains?}
    J -->|yes| K[Filter to Specific Domains]
    J -->|no| L{Exclude Domains?}
    K --> M[Search Results]
    L -->|yes| N[Remove Unwanted Domains]
    L -->|no| M
    N --> M
    
    M --> O{Response Options}
    O --> P[AI Answer<br/>Summary]
    O --> Q[Structured Results<br/>Title, URL, Content, Score]
    O --> R[Images<br/>if requested]
    O --> S[Raw HTML Content<br/>if requested]
    
    P --> T[Return to Agent]
    Q --> T
    R --> T
    S --> T
    
    style E fill:#4A90E2
    style P fill:#7ED321
    style Q fill:#7ED321
    style R fill:#F5A623
    style S fill:#F5A623

Quick Start

快速开始

Basic Search

基础搜索

bash

undefined

bash

undefined

Simple query with AI answer

带AI答案的简单查询

scripts/tavily_search.py "What is quantum computing?"

scripts/tavily_search.py "什么是量子计算？"

Multiple results

多结果查询

scripts/tavily_search.py "Python best practices" --max-results 10

undefined

scripts/tavily_search.py "Python最佳实践" --max-results 10

undefined

Advanced Search

高级搜索

bash

undefined

bash

undefined

Comprehensive research mode

全面调研模式

scripts/tavily_search.py "Climate change solutions" --depth advanced

scripts/tavily_search.py "气候变化解决方案" --depth advanced

News-focused search

聚焦新闻的搜索

scripts/tavily_search.py "AI developments 2026" --topic news

undefined

scripts/tavily_search.py "2026年AI发展动态" --topic news

undefined

Domain Filtering

域名过滤

bash

undefined

bash

undefined

Search only trusted domains

仅在可信域名中搜索

scripts/tavily_search.py "Python tutorials"
--include-domains python.org docs.python.org realpython.com

scripts/tavily_search.py "Python教程"
--include-domains python.org docs.python.org realpython.com

Exclude low-quality sources

排除低质量来源

scripts/tavily_search.py "How to code"
--exclude-domains w3schools.com geeksforgeeks.org

undefined

scripts/tavily_search.py "如何编码"
--exclude-domains w3schools.com geeksforgeeks.org

undefined

With Images

图片搜索

bash

undefined

bash

undefined

Include relevant images

包含相关图片

scripts/tavily_search.py "Eiffel Tower architecture" --images

undefined

scripts/tavily_search.py "埃菲尔铁塔建筑" --images

undefined

Search Modes

搜索模式

Basic vs Advanced

基础模式vs高级模式

Mode	Speed	Coverage	Use Case
basic	1-2s	Good	Quick facts, simple queries
advanced	5-10s	Excellent	Research, complex topics, comprehensive analysis

Decision tree:

Need a quick fact or definition? → Use
```
basic
```
Researching a complex topic? → Use
```
advanced
```
Need multiple perspectives? → Use
```
advanced
```
Time-sensitive query? → Use
```
basic
```

模式	速度	覆盖范围	使用场景
basic	1-2秒	良好	快速事实查询、简单问题
advanced	5-10秒	极佳	调研、复杂主题、全面分析

决策树：

需要快速事实或定义？→ 使用
```
basic
```
调研复杂主题？→ 使用
```
advanced
```
需要多视角信息？→ 使用
```
advanced
```
时间敏感型查询？→ 使用
```
basic
```

General vs News

通用搜索vs新闻搜索

Topic	Time Range	Sources	Use Case
general	All time	Broad web	Evergreen content, tutorials, documentation
news	Last 7 days	News sites	Current events, recent developments, breaking news

Decision tree:

Query contains "latest", "recent", "current", "today"? → Use
```
news
```
Looking for historical or evergreen content? → Use
```
general
```
Need up-to-date information? → Use
```
news
```

主题	时间范围	来源	使用场景
general	全时段	全网	常青内容、教程、文档
news	最近7天	新闻站点	时事、最新动态、突发新闻

决策树：

查询包含“最新”“近期”“当前”“今日”？→ 使用
```
news
```
查找历史或常青内容？→ 使用
```
general
```
需要最新信息？→ 使用
```
news
```

API Key Setup

API密钥设置

Option 1: Clawdbot Config (Recommended)

选项1：Clawdbot配置（推荐）

Add to your Clawdbot config:

json

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-YOUR_API_KEY_HERE"
      }
    }
  }
}

Access in scripts via Clawdbot's config system.

添加到你的Clawdbot配置文件：

json

{
  "skills": {
    "entries": {
      "tavily": {
        "enabled": true,
        "apiKey": "tvly-YOUR_API_KEY_HERE"
      }
    }
  }
}

通过Clawdbot的配置系统在脚本中调用。

Option 2: Environment Variable

选项2：环境变量

bash

export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"

Add to

~/.clawdbot/.env

or your shell profile.

bash

export TAVILY_API_KEY="tvly-YOUR_API_KEY_HERE"

添加到

~/.clawdbot/.env

或你的Shell配置文件中。

Getting an API Key

获取API密钥

Visit https://tavily.com
Sign up for an account
Navigate to your dashboard
Generate an API key (starts with
```
tvly-
```
)
Note your plan's rate limits and credit allocation

访问https://tavily.com
注册账号
进入你的控制台
生成API密钥（以
```
tvly-
```
开头）
记录你的套餐速率限制和额度分配

Common Use Cases

常见使用场景

1. Research & Fact-Finding

1. 调研与事实核查

bash

undefined

bash

undefined

Comprehensive research with answer

带答案的全面调研

scripts/tavily_search.py "Explain quantum entanglement" --depth advanced

scripts/tavily_search.py "解释量子纠缠" --depth advanced

Multiple authoritative sources

多权威来源查询

scripts/tavily_search.py "Best practices for REST API design"
--max-results 10
--include-domains github.com microsoft.com google.com

undefined

scripts/tavily_search.py "REST API设计最佳实践"
--max-results 10
--include-domains github.com microsoft.com google.com

undefined

2. Current Events

2. 时事查询

bash

undefined

bash

undefined

Latest news

Recent developments in a field

领域近期动态

scripts/tavily_search.py "quantum computing breakthroughs"
--topic news
--depth advanced

undefined

scripts/tavily_search.py "量子计算突破"
--topic news
--depth advanced

undefined

3. Domain-Specific Research

3. 特定领域调研

bash

undefined

bash

undefined

Academic sources only

仅学术来源

scripts/tavily_search.py "machine learning algorithms"
--include-domains arxiv.org scholar.google.com ieee.org

scripts/tavily_search.py "机器学习算法"
--include-domains arxiv.org scholar.google.com ieee.org

Technical documentation

技术文档

scripts/tavily_search.py "React hooks guide"
--include-domains react.dev

undefined

scripts/tavily_search.py "React Hooks指南"
--include-domains react.dev

undefined

4. Visual Research

4. 视觉调研

bash

undefined

bash

undefined

Gather visual references

收集视觉参考

scripts/tavily_search.py "modern web design trends"
--images
--max-results 10

undefined

scripts/tavily_search.py "现代网页设计趋势"
--images
--max-results 10

undefined

5. Content Extraction

5. 内容提取

bash

undefined

bash

undefined

Get raw HTML content for deeper analysis

获取原始HTML内容用于深度分析

scripts/tavily_search.py "Python async/await"
--raw-content
--max-results 5

undefined

scripts/tavily_search.py "Python async/await"
--raw-content
--max-results 5

undefined

Response Handling

响应处理

AI Answer

AI答案

The AI-generated answer provides a concise summary synthesized from search results:

python

{
  "answer": "Quantum computing is a type of computing that uses quantum-mechanical phenomena..."
}

Use when:

Need a quick summary
Want synthesized information from multiple sources
Looking for a direct answer to a question

Skip when (

--no-answer

Only need source URLs
Want to form your own synthesis
Conserving API credits

AI生成的答案是从搜索结果中合成的简洁摘要：

python

{
  "answer": "量子计算是一种利用量子力学现象的计算方式..."
}

适用场景：

需要快速摘要
希望获取多来源合成信息
寻找问题的直接答案

禁用场景（使用

--no-answer

）：

仅需要来源URL
希望自行合成信息
节省API额度

Structured Results

结构化结果

Each result includes:

```
title
```
: Page title
```
url
```
: Source URL
```
content
```
: Extracted text snippet
```
score
```
: Relevance score (0-1)
```
raw_content
```
: Full HTML (if
```
--raw-content
```
enabled)

每个结果包含：

```
title
```
: 页面标题
```
url
```
: 来源URL
```
content
```
: 提取的文本片段
```
score
```
: 相关度评分（0-1）
```
raw_content
```
: 完整HTML（若启用
```
--raw-content
```
）

Images

图片

When

--images

is enabled, returns URLs of relevant images found during search.

当启用

--images

时，返回搜索到的相关图片URL。

Best Practices

最佳实践

1. Choose the Right Search Depth

1. 选择合适的搜索深度

Start with
```
basic
```
for most queries (faster, cheaper)
Escalate to
```
advanced
```
only when:
- Initial results are insufficient
- Topic is complex or nuanced
- Need comprehensive coverage

大多数查询优先使用
```
basic
```
（更快、更经济）
仅在以下情况升级到
```
advanced
```
：
- 初始结果不足
- 主题复杂或涉及细节
- 需要全面覆盖

2. Use Domain Filtering Strategically

2. 策略性使用域名过滤

Include domains for:

Academic research (
```
.edu
```
domains)
Official documentation (official project sites)
Trusted news sources
Known authoritative sources

Exclude domains for:

Known low-quality content farms
Irrelevant content types (Pinterest for non-visual queries)
Sites with paywalls or access restrictions

包含域名的场景：

学术调研（
```
.edu
```
域名）
官方文档（项目官方站点）
可信新闻来源
已知权威来源

排除域名的场景：

已知低质量内容农场
无关内容类型（非视觉查询排除Pinterest）
有付费墙或访问限制的站点

3. Optimize for Cost

3. 成本优化

Use
```
basic
```
depth as default
Limit
```
max_results
```
to what you'll actually use
Disable
```
include_raw_content
```
unless needed
Cache results locally for repeated queries

默认使用
```
basic
```
深度
将
```
max_results
```
限制为实际需要的数量
除非必要，禁用
```
include_raw_content
```
对重复查询实现本地缓存

4. Handle Errors Gracefully

4. 优雅处理错误

The script provides helpful error messages:

bash

undefined

脚本提供实用的错误提示：

bash

undefined

Missing API key

缺少API密钥

Error: Tavily API key required Setup: Set TAVILY_API_KEY environment variable or pass --api-key

Package not installed

未安装依赖包

Error: tavily-python package not installed To install: pip install tavily-python

undefined

Error: tavily-python package not installed To install: pip install tavily-python

undefined

Integration Patterns

集成模式

Programmatic Usage

程序化调用

python

from tavily_search import search

result = search(
    query="What is machine learning?",
    api_key="tvly-...",
    search_depth="advanced",
    max_results=10
)

if result.get("success"):
    print(result["answer"])
    for item in result["results"]:
        print(f"{item['title']}: {item['url']}")

python

from tavily_search import search

result = search(
    query="什么是机器学习？",
    api_key="tvly-...",
    search_depth="advanced",
    max_results=10
)

if result.get("success"):
    print(result["answer"])
    for item in result["results"]:
        print(f"{item['title']}: {item['url']}")

JSON Output for Parsing

输出JSON用于解析

bash

scripts/tavily_search.py "Python tutorials" --json > results.json

bash

scripts/tavily_search.py "Python教程" --json > results.json

Chaining with Other Tools

与其他工具链式调用

bash

undefined

bash

undefined

Search and extract content

搜索并提取内容

scripts/tavily_search.py "React documentation" --json |
jq -r '.results[].url' |
xargs -I {} curl -s {}

undefined

scripts/tavily_search.py "React文档" --json |
jq -r '.results[].url' |
xargs -I {} curl -s {}

undefined

Comparison with Other Search APIs

与其他搜索API的对比

vs Brave Search:

✅ AI answer generation
✅ Raw content extraction
✅ Better domain filtering
❌ Slower than Brave
❌ Costs credits

vs Perplexity:

✅ More control over sources
✅ Raw content available
✅ Dedicated news mode
≈ Similar answer quality
≈ Similar speed

vs Google Custom Search:

✅ LLM-optimized results
✅ Answer generation
✅ Simpler API
❌ Smaller index
≈ Similar cost structure

vs Brave Search：

✅ AI答案生成
✅ 原始内容提取
✅ 更优的域名过滤
❌ 比Brave慢
❌ 消耗额度

vs Perplexity：

✅ 对来源有更多控制权
✅ 可获取原始内容
✅ 专属新闻模式
≈ 相似的答案质量
≈ 相似的速度

vs Google Custom Search：

✅ 针对LLM优化的结果
✅ 答案生成
✅ 更简洁的API
❌ 索引规模更小
≈ 相似的成本结构

Troubleshooting

故障排除

Script Won't Run

脚本无法运行

bash

undefined

bash

undefined

Make executable

设置可执行权限

chmod +x scripts/tavily_search.py

Check Python version (requires 3.6+)

检查Python版本（需要3.6+）

python3 --version

Install dependencies

安装依赖

pip install tavily-python

undefined

pip install tavily-python

undefined

API Key Issues

API密钥问题

bash

undefined

bash

undefined

Verify API key format (should start with tvly-)

验证API密钥格式（应以tvly-开头）

echo $TAVILY_API_KEY

Test with explicit key

使用显式密钥测试

scripts/tavily_search.py "test" --api-key "tvly-..."

undefined

scripts/tavily_search.py "test" --api-key "tvly-..."

undefined

Rate Limit Errors

速率限制错误

Check your plan's credit allocation at https://tavily.com
Reduce
```
max_results
```
to conserve credits
Use
```
basic
```
depth instead of
```
advanced
```
Implement local caching for repeated queries

访问https://tavily.com查看你的套餐额度
减少
```
max_results
```
以节省额度
使用
```
basic
```
深度替代
```
advanced
```
对重复查询实现本地缓存

Resources

资源

See api-reference.md for:

Complete API parameter documentation
Response format specifications
Error handling details
Cost and rate limit information
Advanced usage examples

查看api-reference.md获取：

完整的API参数文档
响应格式规范
错误处理细节
成本和速率限制信息
高级使用示例

Dependencies

依赖

Python 3.6+
```
tavily-python
```
package (install:
```
pip install tavily-python
```
)
Valid Tavily API key

Python 3.6+
```
tavily-python
```
包（安装：
```
pip install tavily-python
```
）
有效的Tavily API密钥

Credits & Attribution

致谢与归属

Tavily API: https://tavily.com
Python SDK: https://github.com/tavily-ai/tavily-python
Documentation: https://docs.tavily.com

Tavily API: https://tavily.com
Python SDK: https://github.com/tavily-ai/tavily-python
文档: https://docs.tavily.com

tavily

Original

Translation

Tavily AI Search

Tavily AI搜索

Overview

概述

Architecture

架构

Quick Start

快速开始

Basic Search

基础搜索

Simple query with AI answer

带AI答案的简单查询

Multiple results

多结果查询

Advanced Search

高级搜索

Comprehensive research mode

全面调研模式

News-focused search

聚焦新闻的搜索

Domain Filtering

域名过滤

Search only trusted domains

仅在可信域名中搜索

Exclude low-quality sources

排除低质量来源

With Images

图片搜索

Include relevant images

包含相关图片

Search Modes

搜索模式

Basic vs Advanced

基础模式vs高级模式

General vs News

通用搜索vs新闻搜索

API Key Setup

API密钥设置

Option 1: Clawdbot Config (Recommended)

选项1：Clawdbot配置（推荐）

Option 2: Environment Variable

选项2：环境变量

Getting an API Key

获取API密钥

Common Use Cases

常见使用场景

1. Research & Fact-Finding

1. 调研与事实核查

Comprehensive research with answer

带答案的全面调研

Multiple authoritative sources

多权威来源查询

2. Current Events

2. 时事查询

Latest news

最新新闻

Recent developments in a field

领域近期动态

3. Domain-Specific Research

3. 特定领域调研

Academic sources only

仅学术来源

Technical documentation

技术文档

4. Visual Research

4. 视觉调研

Gather visual references

收集视觉参考

5. Content Extraction

5. 内容提取

Get raw HTML content for deeper analysis

获取原始HTML内容用于深度分析

Response Handling

响应处理

AI Answer

AI答案

Structured Results