Tavily 搜索 API 配置指南（AI Agent 专用搜索）

本文基于 Hermes Agent 环境的实际配置过程，介绍 Tavily 搜索 API 的用途、申请与配置方法。

什么是 Tavily

Tavily 是一个专为 AI Agent / LLM 设计的搜索 API。与普通搜索引擎 API 不同，Tavily 直接返回经过提炼的结构化结果（标题、内容摘要、来源链接、相关性问题），而不是一页原始 HTML，省去了抓取、清洗、解析的环节。

典型用途：

• Agent 的实时信息检索（新闻、文档、价格、行情）

• 给大模型补充最新知识（解决知识截止日期问题）

• 自动化日报 / 周报的数据采集

第一步：申请 API Key

1. 打开官网 https://tavily.com，注册账号

2. 进入 Dashboard → API Keys，创建你的 Key

3. 免费额度：每月 1000 次搜索（个人学习完全够用），付费版支持更多配额与更快的速率

第二步：配置到 Hermes 环境

在 Hermes 中，Tavily 作为 web 工具集的搜索后端之一。配置方式：把 Key 写入环境变量文件：

# ~/.hermes/.env
TAVILY_API_KEY=tvly-xxxxxxxxxxxxxxxx

配置完成后，用 hermes status 验证：

Tavily        ✓ tvly...xxxx

显示 ✓ 即表示 Key 已生效，agent 的 web_search 工具会自动使用它。

第三步：API 基础用法

curl 示例

curl -X POST "https://api.tavily.com/search" \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "tvly-xxxxxxxx",
    "query": "2026年储能行业政策",
    "search_depth": "basic",
    "max_results": 5
  }'

Python 示例

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-xxxxxxxx")
result = client.search(
    query="AI Agent 企业落地案例",
    search_depth="advanced",   # advanced 更深层爬取
    max_results=10,
    topic="news",              # 限定新闻类内容
    days=7,                    # 只看最近 7 天
)
for r in result["results"]:
    print(r["title"], "-", r["url"])

常用参数

在 Agent 工作流中的位置

以本机的「AI 每日热点报告」为例，cron 任务每天 07:00 触发：

1. agent 用 web_search（Tavily 后端）搜索最近 24-48 小时热点

2. 筛选高热度事件 → 生成中文摘要

3. 附上原文链接 → 输出日报

Tavily 的价值在于结果即结构化数据，agent 可以直接消费，不需要自己写爬虫。

注意事项

• Key 不要提交到 git：.env 文件本身就在 gitignore 列表里

• 额度监控：免费版 1000 次/月，深度搜索（advanced）消耗更快，批量任务优先用 basic

• 时效性：days 参数对新闻类查询很关键，日报类任务建议显式指定