tavily-web-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

tavily-web-search

Tavily网页搜索

Purpose

功能用途

This skill enables AI agents to perform web searches using Tavily, a service optimized for AI workflows. It synthesizes answers from search results, applies domain filters, and controls search depth to deliver relevant, concise information without overwhelming the agent.

该技能使AI Agent能够通过Tavily执行网页搜索，Tavily是一款针对AI工作流优化的服务。它会从搜索结果中合成答案，应用域名过滤，并控制搜索深度，从而为Agent提供相关、简洁的信息，避免信息过载。

When to Use

适用场景

Use this skill when you need real-time web data, such as fetching current news, verifying facts, or gathering research. Apply it in scenarios where standard search engines are too verbose, like synthesizing answers for user queries, filtering results to specific domains (e.g., .edu sites), or limiting depth for quick responses. Avoid it for internal data access or when offline sources suffice.

当您需要实时网络数据时使用该技能，例如获取最新新闻、验证事实或收集研究资料。在标准搜索引擎结果过于冗长的场景中使用它，比如为用户查询合成答案、将结果过滤到特定域名（如.edu站点），或限制搜索深度以快速获取响应。如果是访问内部数据或离线数据源足够时，请避免使用该技能。

Key Capabilities

核心功能

Answer Synthesis: Automatically summarizes search results into a coherent response; specify via
```
search_depth
```
parameter (e.g., 0 for shallow, 5 for deep).
Domain Filtering: Restrict searches to domains like "example.com" using the
```
include_domains
```
flag; example:
```
include_domains=["wikipedia.org"]
```
.
Depth Control: Set search depth with
```
max_results
```
(1-10) to control result volume; higher values increase detail but raise costs.
Optimized for AI: Integrates with AI agents via API, supporting tags like "search" and "ai" for metadata embedding.
Configurable Queries: Supports query parameters for customization, such as
```
query
```
string and
```
api_key
```
for authentication.

答案合成：自动将搜索结果总结为连贯的响应；可通过
```
search_depth
```
参数指定（例如，0为浅层搜索，5为深层搜索）。
域名过滤：使用
```
include_domains
```
标志将搜索限制在特定域名，例如
```
include_domains=["wikipedia.org"]
```
。
搜索深度控制：通过
```
max_results
```
（1-10）设置搜索深度，控制结果数量；数值越高，信息越详细，但成本也会增加。
AI优化适配：通过API与AI Agent集成，支持嵌入"search"和"ai"等标签作为元数据。
可配置查询：支持自定义查询参数，如
```
query
```
字符串和用于身份验证的
```
api_key
```
。

Usage Patterns

使用模式

Always initialize with an API key via environment variable

$TAVILY_API_KEY

. For basic searches, construct a query object and call the API endpoint. Use in loops for iterative refinement, e.g., refine queries based on initial results. Pattern: Set up auth, build query with filters, execute search, then parse and synthesize the response. For agent workflows, integrate as a subtool in multi-step processes, ensuring error checks between calls.

始终通过环境变量

$TAVILY_API_KEY

初始化API密钥。对于基础搜索，构建查询对象并调用API端点。可在循环中使用以迭代优化查询，例如根据初始结果优化查询。使用流程：设置身份验证、构建带过滤条件的查询、执行搜索，然后解析并合成响应。对于Agent工作流，将其作为子工具集成到多步骤流程中，确保在调用之间进行错误检查。

Common Commands/API

常用命令/API

Tavily uses a REST API endpoint:

https://api.tavily.com/search

. Authentication requires setting

$TAVILY_API_KEY

in your environment.

Example CLI curl command:

curl -H "Content-Type: application/json" \
     -H "X-Api-Key: $TAVILY_API_KEY" \
     https://api.tavily.com/search -d '{"query": "latest AI news", "max_results": 3}'

Python code snippet for API call:

import requests
api_key = os.environ.get('TAVILY_API_KEY')
response = requests.post('https://api.tavily.com/search', headers={'X-Api-Key': api_key}, json={'query': 'climate change effects', 'include_domains': ['nytimes.com']})
results = response.json()['results']

Common flags/parameters:

```
query
```
: String, required; e.g., "OpenAI updates".
```
max_results
```
: Integer (1-10); controls depth, e.g., 5 for balanced results.
```
include_domains
```
: Array of strings; e.g., ["bbc.com", "cnn.com"] for news sites.
```
exclude_domains
```
: Array; e.g., ["socialmedia.com"] to avoid certain sites.

Tavily使用REST API端点：

https://api.tavily.com/search

。身份验证需要在环境中设置

$TAVILY_API_KEY

。

示例CLI curl命令：

curl -H "Content-Type: application/json" \
     -H "X-Api-Key: $TAVILY_API_KEY" \
     https://api.tavily.com/search -d '{"query": "latest AI news", "max_results": 3}'

Python代码调用示例：

import requests
api_key = os.environ.get('TAVILY_API_KEY')
response = requests.post('https://api.tavily.com/search', headers={'X-Api-Key': api_key}, json={'query': 'climate change effects', 'include_domains': ['nytimes.com']})
results = response.json()['results']

常用参数/标志：

```
query
```
：字符串，必填；例如"OpenAI updates"。
```
max_results
```
：整数（1-10）；控制搜索深度，例如设置为5可获得平衡的结果数量。
```
include_domains
```
：字符串数组；例如
```
["bbc.com", "cnn.com"]
```
以限定新闻站点。
```
exclude_domains
```
：数组；例如
```
["socialmedia.com"]
```
以排除特定站点。

Integration Notes

集成说明

To integrate, first obtain a Tavily API key from their dashboard and set it as

$TAVILY_API_KEY

. In code, import necessary libraries (e.g., requests in Python) and handle the API response as JSON. For OpenClaw agents, add this skill to your toolset by referencing the ID "tavily-web-search" in your agent config, like:

tools: ["tavily-web-search"]

. Config format example in YAML:

tools:
  - id: tavily-web-search
    config:
      api_key_env: TAVILY_API_KEY
      default_params:
        max_results: 3

Ensure your agent checks for key availability before calling; if missing, prompt the user. Test integrations in a sandbox environment to verify response formats.

要进行集成，请先从Tavily控制台获取API密钥，并将其设置为环境变量

$TAVILY_API_KEY

。在代码中，导入必要的库（例如Python中的requests），并将API响应作为JSON处理。对于OpenClaw Agent，可通过在Agent配置中引用ID "tavily-web-search" 将该技能添加到工具集，例如：

tools: ["tavily-web-search"]

。YAML格式的配置示例：

tools:
  - id: tavily-web-search
    config:
      api_key_env: TAVILY_API_KEY
      default_params:
        max_results: 3

确保您的Agent在调用前检查密钥是否可用；如果缺失，请提示用户。在沙箱环境中测试集成，以验证响应格式。

Error Handling

错误处理

Common errors include 401 (unauthorized) for invalid API keys, 429 (rate limit exceeded), and 400 (bad request for invalid parameters). To handle: Check response status code before parsing; if 401, log "API key error: Set $TAVILY_API_KEY" and retry after user input. For 429, implement exponential backoff (e.g., wait 5 seconds then retry). Validate inputs beforehand, e.g., ensure

query

is not empty. Example error check in code:

if response.status_code == 401:
    raise ValueError("Authentication failed; ensure $TAVILY_API_KEY is set")
elif response.status_code >= 400:
    print(f"Error: {response.json().get('error')}")

常见错误包括401（未授权，API密钥无效）、429（超出速率限制）和400（请求参数无效）。处理方式：解析前检查响应状态码；如果是401，记录"API密钥错误：请设置$TAVILY_API_KEY"并在用户输入后重试。对于429错误，实现指数退避策略（例如等待5秒后重试）。提前验证输入，例如确保

query

不为空。代码中的错误检查示例：

if response.status_code == 401:
    raise ValueError("Authentication failed; ensure $TAVILY_API_KEY is set")
elif response.status_code >= 400:
    print(f"Error: {response.json().get('error')}")

Concrete Usage Examples

实际使用示例

Fact Verification: To verify recent events, use: Set query to "2023 election results" with
```
include_domains=["reuters.com"]
```
and
```
max_results=2
```
. Then, synthesize the response to extract key facts, e.g., in code:
```
synthesized_answer = summarize_results(results)
```
.
Research Assistance: For gathering AI trends, construct a query like "advancements in LLMs" with
```
search_depth=3
```
. Parse results to filter for dates or sources, then use in an agent response: "Based on Tavily search, key trends include...".

事实验证：要验证近期事件，可设置查询为"2023 election results"，并配置
```
include_domains=["reuters.com"]
```
和
```
max_results=2
```
。然后合成响应以提取关键事实，例如代码中：
```
synthesized_answer = summarize_results(results)
```
。
研究辅助：为收集AI趋势信息，构建查询如"advancements in LLMs"并设置
```
search_depth=3
```
。解析结果以筛选日期或来源，然后在Agent响应中使用："根据Tavily搜索结果，主要趋势包括..."。

Graph Relationships

关联关系

Related to: search tools (e.g., via "search" tag)
Connected via: community cluster (shares nodes with other community tools)
Links to: AI agents (through "ai" tag for embedding)
Dependencies: Requires external API (Tavily), no direct graph edges to other skills unless configured.

相关工具：搜索工具（通过"search"标签关联）
社区集群：与其他社区工具共享节点，属于同一社区集群
关联对象：AI Agent（通过嵌入"ai"标签关联）
依赖关系：需要外部API（Tavily），除非配置，否则与其他技能无直接关联。