Tavily 是專為 AI Agent 設計的 Web Search API
不是面向人類 UI 的搜尋引擎，而是面向 LLM / Agent 的即時網路資料擷取層

傳統搜尋引擎 UI（如 Google 搜尋頁）：主要為人類閱讀設計，結果通常是連結、標題與 snippet
Tavily：主要為 LLM / Agent 設計，回傳可直接進入 context 的摘要、chunks、raw content 或 structured output

"Search, extract, and crawl real-time web data in formats optimized for RAG and agent workflows"

參考：Tavily 101: AI-powered Search for Developers — Tavily Blog

核心 Endpoint

參考：Tavily Search API Reference — Tavily Docs

/search API

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-...")
response = client.search(
    query="LLM agent tool use",
    search_depth="advanced",   # ultra-fast | fast | basic | advanced
    max_results=5,
    topic="general",           # general | news | finance
    include_answer=True,       # 讓 Tavily 合成一個 AI 回答
    include_raw_content=False,
    include_domains=[],        # 白名單
    exclude_domains=[]         # 黑名單
)

search_depth 差異：

回傳結構

{
  "query": "LLM agent tool use",
  "answer": "LLM agents use tools by...",   // include_answer=True 時有
  "results": [
    {
      "title": "...",
      "url": "https://...",
      "content": "摘要文字（適合直接放進 prompt）",
      "score": 0.98
    }
  ],
  "usage": { "credits": 2 }
}

→ content 已是乾淨的純文字，不需要自己 parse HTML

跟傳統 Search API 的比較

整合框架

Tavily 直接內建進主流 LLM 框架：

# LangChain（官方目前建議使用 langchain-tavily）
from langchain_tavily import TavilySearch
tool = TavilySearch(max_results=3)

# LlamaIndex
from llama_index.tools.tavily_research import TavilyToolSpec
tool = TavilyToolSpec(api_key="tvly-...")

支援的框架：LangChain、LlamaIndex、OpenAI Agents SDK、CrewAI、Pydantic AI、n8n、Agno

參考：Tavily API Reference Introduction — Tavily Docs

適合的使用情境

RAG pipeline
  使用者問問題
    ↓
  Tavily /search → 拿到 Top-5 相關片段
    ↓
  組進 prompt → LLM 回答

Agent with tool use
  LLM 決定要搜尋
    ↓
  call Tavily tool
    ↓
  結果回傳給 LLM 繼續推理

topic 選項：

• general：通用網頁搜尋（預設）
• news：偏向最近新聞來源，適合即時資訊需求
• finance：偏向財經相關來源

認證與費用

API Key 格式：tvly-xxxxxxxxxxxxxxxx
每次 /search（basic）= 1 credit
每次 /search（advanced）= 2 credits
Free plan：1,000 credits/month

請求 header：

Authorization: Bearer tvly-xxxxxxxxxxxxxxxx

輸出範例

Input（Python）

from tavily import TavilyClient

client = TavilyClient(api_key="tvly-abc123...")
response = client.search(
    query="什麼是 HNSW？",
    search_depth="basic",
    max_results=3,
    include_answer=True,
    include_usage=True    # 預設 false，要明確開才會回傳 credit usage
)

Output（JSON）

{
  "query": "什麼是 HNSW？",
  "answer": "HNSW（Hierarchical Navigable Small World）是一種基於圖的近似最近鄰搜尋演算法，透過多層稀疏圖結構加速向量檢索...",
  "results": [
    {
      "title": "HNSW Algorithm Explained",
      "url": "https://www.pinecone.io/learn/hnsw/",
      "content": "HNSW builds a multi-layer graph where upper layers are sparse for long jumps and lower layers are dense for fine search...",
      "score": 0.97
    },
    {
      "title": "Approximate Nearest Neighbor Search",
      "url": "https://faiss.ai/...",
      "content": "...",
      "score": 0.85
    }
  ],
  "usage": { "credits": 1 }
}

results[].content 是 Tavily 已整理過的摘要 / snippet / chunks，通常可直接放入 LLM context。若需要更完整的網頁正文，應使用 /extract，或在 /search 開啟 include_raw_content。answer 是 Tavily 用搜尋結果合成的回答，適合快速問答場景。

Sources

• Tavily 101: AI-powered Search for Developers — Tavily Blog
• Tavily Search API Reference — Tavily Docs
• Tavily API Reference Introduction — Tavily Docs
• About Tavily — Tavily Docs