jimmy·research
Home/AI Infrastructure/Tavily Search Integration
中文↔English

Tavily Search Integration

把 tavily 作为 agent 运行时内 web 搜索后端的使用模式:何时使用、如何调优、以及它与原始搜索 API、Brave、Exa 和 Perplexity 的对比。

1. 为什么需要搜索层 API

Agent 框架需要一个返回干净、模型就绪内容的 web_search 工具。三种选项存在:

  1. 原始搜索 API(Google CSE、Bing Web Search)—— 返回 SERP 风格链接 + 片段。agent 然后必须抓取每个 URL、解析 HTML、去噪。按查询便宜,按有用 token 贵。
  2. 搜索层 API(tavily、Exa、You.com)—— 返回排名结果加提取的、模型就绪内容。一次调用替代搜索 + N 次抓取 + 解析。
  3. 答案引擎(Perplexity Sonar、Google Grounding)—— 返回综合答案加引用。agent 代码最少,但你失去 agent 自己 LLM 可能不同推理的原始证据。

tavily 位于第 2 档。它专为 agent 检索构建,而非人类 SERP。

2. 核心集成模式

任何 agent 运行时的最小集成:

def web_search(query: str, depth: str = "basic", **kwargs) -> list[dict]:
    r = tavily.search(
        query=query,
        search_depth=depth,             # "basic" | "advanced"
        max_results=kwargs.get("k", 5),
        include_answer=False,           # 让我们的模型做综合
        include_raw_content=True,       # 我们想要页面文本
        time_range=kwargs.get("time_range"),
        include_domains=kwargs.get("include_domains"),
        exclude_domains=kwargs.get("exclude_domains"),
    )
    return [
        {"url": x["url"], "title": x["title"], "content": x["content"]}
        for x in r["results"]
    ]

值得辩护的关键设计选择:

  • include_answer=False。agent 有自己的模型 —— 让 Tavily 综合会把搜索步骤塌缩成黑盒答案,并从拥有其余上下文的 LLM 那里偷走推理。只在没有编排器的一次性 Q&A bot 中使用 include_answer=True。
  • include_raw_content=True 当下游任务需要引用、表格提取或事实核查。仅当你只需要排名 URL 列表用单独抓取器跟进时跳过。
  • 工具级 wrapper,不是框架特定。把 Tavily 作为多个搜索后端之一封装在稳定的内部接口后面,以便你可以在不重写 prompt 的情况下对 Brave 或 Exa 做 A/B。

3. basic vs advanced —— 何时 2x 成本值得

Tavily 对 search_depth="advanced" 大致收 2x 价(2026 年 basic 1 credit、advanced 2 credit)。深度差异是真实的:

用例 深度
"X 是什么?" —— 事实、有充分文档的 basic
近期新闻、突发事件 basic + time_range="day"
竞争分析、利基 B2B 研究 advanced
用于长篇文章的引用 / 引述 advanced
deep-research-workflow 内的子查询 advanced
高量背景增强 basic

启发式:如果错误或浅薄的结果让 agent 多花一个 LLM 回合恢复就比这更贵,付费走 advanced。如果 agent 跑 200 次查询且任何单次失败都便宜,留在 basic。

4. 时间、域名和主题过滤器

三个过滤器做了大部分质量工作:

  • time_range:"day"、"week"、"month"、"year"。单一最高杠杆参数。agent 在没有时间过滤器的情况下查询"X 的当前状态"通常把 2021 年博客文章作为顶部结果浮现。
  • include_domains / exclude_domains:为技术研究白名单 ["arxiv.org", "github.com"];为几乎所有东西黑名单 ["pinterest.com", "quora.com"]。3-5 域名白名单常常击败 50 来源的开放搜索。
  • topic="news" vs "general":Tavily 把新闻查询路由通过不同管道,优先 freshness 和声誉好的媒体。

把这些编入命名搜索配置(research_technical、research_news、research_competitive),而非让调用 agent 即兴组装参数。

5. 成本经济学

2026 年 Tavily 公开定价:basic 查询 1 credit,advanced 2 credit,免费档每月 1,000 credits,付费计划起价约 $30/月含 4,000 credits。有效每查询成本落在大约 $0.005–$0.015,取决于深度和档次。

对 agent 每任务 K 次查询的对比:

  • Brave Search API:每 1,000 查询约 $3 在 free-then-paid 档上,但你仍需自己抓取和解析页面 —— 净成本由你的抓取器基建主导。
  • Exa:类似按查询,有更强的语义 / 神经检索。比"回答这个问题"更好用于"找到与此 URL 相似的页面"。
  • Perplexity Sonar:按综合答案 token 定价,而非按查询。对一次性 Q&A 更便宜;一旦你需要原始证据就更贵。
  • Google Custom Search:每 1,000 查询 $5,硬限 10k/天,仅片段。

对每任务做 20-50 次子查询的 deep-research-workflow,Tavily 在 advanced 上每任务大约跑 $0.20-$0.75。这通常对 LLM token 成本是舍入误差 —— 但足以让你应该在运行时层池化 credits,而非让每个 skill 带自己的 key。

6. 对比替代品的权衡

后端 优势 劣势
tavily agent 原生;便宜;干净提取内容 索引广度比 Google 窄
Brave Search 最大独立索引;便宜原始搜索 你构建提取层
Exa 最佳语义 / "找相似"检索 不太适合开放 Q&A
Perplexity 最佳一次性事实答案 黑盒综合;更难事实核查
Google Grounding(Gemini) 最高召回、最新 锁定 Gemini;不可跨模型移植

许多 agent 运行时收敛到的实用栈:Tavily 作为默认 web_search,Exa 作为 find_similar 工具用于引用走查,原始抓取器(Brave + Playwright)用于 Tavily 失败的付费墙或重 JS 来源的长尾。

7. 需规划的失败模式

  • 利基查询上的空结果。总是实现 fallback 链:Tavily → Brave + 抓取 → Google CSE。
  • 过时提取内容。Tavily 缓存;最近一小时更新的页面可能服务旧文本。对突发新闻配对直接抓取。
  • 突发多 agent fan-out 下的速率限制。在运行时层用 token 桶限流 client;不要让每个子代理持有自己的配额。
  • 搜索结果中的 prompt 注入。在喂给工具使用模型之前,strip / sandbox 返回的 content 字段 —— 提取的页面文本是不可信输入。

来源

Related

tavily
Last compiled: 2026-05-10