| name | tavily-search |
| description | 使用 Tavily API 进行实时网页搜索。当用户需要搜索最新信息、查找资料、核实事实、研究话题时触发。支持自然语言如 "搜索XX"、"查一下XX"、"帮我找XX"、"search for XX"、"look up XX" 等。也作为 /tavily-search slash command 被调用。 |
Tavily Search
通过 Tavily Search API 执行实时网页搜索，获取最新、准确的信息。
API 配置
- API 端点:
https://api.tavily.com/search
- API Key: 从环境变量
TAVILY_API_KEY 读取
- 请求方式: POST，Content-Type: application/json
关键参数
| 参数 | 类型 | 默认值 | 说明 |
|---|
api_key | string | 必填 | 从 $TAVILY_API_KEY 环境变量读取 |
query | string | 必填 | 搜索查询字符串 |
search_depth | string | "advanced" | "basic" 快速搜索，"advanced" 深度搜索 |
max_results | number | 10 | 返回结果数，范围 1-20 |
include_answer | boolean | true | 是否包含 AI 生成的摘要回答 |
include_domains | array | 无 | 限定搜索域名列表 |
exclude_domains | array | 无 | 排除的域名列表 |
include_raw_content | boolean | false | 是否包含页面原始内容 |
days | number | 无 | 仅返回最近 N 天内的内容（如 7 表示一周内） |
执行流程
Step 1: 检查 API Key
首先检查环境变量是否设置：
echo $TAVILY_API_KEY
如果为空，告知用户需要设置 TAVILY_API_KEY 环境变量。获取方式：访问 https://tavily.com 注册并获取 API key。
Step 2: 理解用户意图
分析用户的搜索请求，确定：
- 查询语句：提炼核心搜索词，英文查询通常效果更好
- 搜索深度：简单事实用
basic，需要全面信息的复杂话题用 advanced
- 结果数量：快速了解用 5 条，深入研究用 10-20 条
- 时间范围：如果用户关心最新信息，加上
days 参数
- 域名过滤：如果用户指定了来源偏好，使用
include_domains 或 exclude_domains
Step 3: 执行搜索
使用 curl 调用 Tavily API。将 JSON body 写入临时文件以避免 shell 转义问题：
curl -s -X POST "https://api.tavily.com/search" \
-H "Content-Type: application/json" \
-d '{
"api_key": "'"$TAVILY_API_KEY"'",
"query": "搜索查询",
"search_depth": "advanced",
"max_results": 10,
"include_answer": true
}'
Step 4: 格式化输出
将 API 返回的结果整理为清晰易读的格式。必须包含：
- AI 摘要（如果存在）：首先展示
answer 字段作为概览
- 结果列表：每条结果包含：
- 标题（可点击的 URL）
- 内容摘要
- 相关性评分（score，0-1 之间）
- 查询信息：响应时间、结果数量
输出格式模板：
## 搜索结果：{query}
> {answer} （AI 摘要）
### 相关结果
1. **[{title}]({url})** `相关度: {score}`
{content}
2. **[{title}]({url})** `相关度: {score}`
{content}
...
---
*共 {n} 条结果 · 响应时间 {response_time}s*
高级用法
限定时间范围
用户要最新信息时，添加 days 参数：
curl -s -X POST "https://api.tavily.com/search" \
-H "Content-Type: application/json" \
-d '{"api_key": "'"$TAVILY_API_KEY"'", "query": "...", "days": 7, ...}'
限定或排除域名
"include_domains": ["github.com", "stackoverflow.com"]
"exclude_domains": ["pinterest.com", "quora.com"]
获取完整内容
需要更详细的上下文时，设置 "include_raw_content": true。注意这会增加响应体积。
错误处理
| 错误 | 原因 | 处理 |
|---|
TAVILY_API_KEY 为空 | 未配置 API key | 引导用户去 tavily.com 注册获取 key，然后 export TAVILY_API_KEY=xxx |
| API 返回 401 | API key 无效 | 提示用户检查 key 是否正确 |
| API 返回 429 | 超出速率限制 | 告知用户稍后重试，免费版有每日限额 |
| API 返回 500+ | 服务端错误 | 稍后重试或联系用户确认 |
curl 网络错误 | 网络不通 | 检查网络连接 |
| 返回结果为空 | 搜索无匹配 | 尝试更通用的关键词或去掉过滤条件 |
注意事项
- Tavily 免费版每天有查询次数限制，具体限额见 tavily.com/pricing
- 英文查询通常比中文查询返回更多高质量结果
advanced 深度搜索耗时更长但结果更全面- 结果中的
score 是 0-1 的相关性评分，越高越相关
- 如果用户需要的是实时新闻，配合
days: 1 或 days: 3 使用
