用 Tavily 为 LLM 应用接入实时网页搜索、抽取…

当需要为智能体、RAG 或自主 Agent 集成实时网络数据（搜索、内容抽取、整站爬取、URL 发现、AI 研究）时，按此最佳实践实现生产级 Tavily 集成。

适用场景

解决思路

1. 安装 SDK：Python 用 `pip install tavily-python`，JavaScript 用 `npm install @tavily/core`。
2. 初始化客户端：`TavilyClient()` 默认读取 `TAVILY_API_KEY` 环境变量（推荐）；需要按项目统计用量时传 `project_id="your-project-id"`；需要并行查询时使用 `AsyncTavilyClient()`。
3. 按需求选择方法：自定义 Agent/工作流中，网页搜索结果用 `search()`，指定 URL 的内容用 `extract()`，整站内容用 `crawl()`，站点 URL 发现用 `map()`；开箱即用的端到端研究用 `research()`。
4. 调用 `search()` 做网页搜索：传入 `query`（保持在 400 字符以内）、`max_results`、`search_depth`（ultra-fast/fast/basic/advanced），并可用 `include_domains`、`exclude_domains`、`time_range` 过滤。
5. 调用 `extract()` 抽取指定 URL 内容：传入 `urls`（最多 20 个）、`extract_depth`，并可用 `query`、`chunks_per_source`（1-5）做定向抽取。
6. 调用 `crawl()` 做整站抽取：传入 `url`，用 `instructions` 做语义聚焦，并配置 `max_depth`、`max_breadth`、`limit`、`chunks_per_source`、`select_paths`、`exclude_paths`。
7. 调用 `map()` 做 URL 发现：传入站点 `url` 获取站点内 URL 列表。
8. 调用 `research()` 做 AI 驱动研究：传入 `input`，选择 `model`（"mini" 用于聚焦查询、"pro" 用于综合多主题研究、不确定时用 "auto"），并可用 `stream`、`output_schema`、`citation_format`；拿到 `request_id` 后轮询 `get_research(request_id)`，每 10 秒一次，直到 `status` 为 `completed` 或 `failed`，再从 `response["content"]` 取研究报告。
9. 查阅详细参考文档获取完整参数与模式：`references/sdk.md`（Python/JS SDK、异步模式、Hybrid RAG）、`references/search.md`（查询优化、搜索深度选择、域名过滤、异步、后置过滤）、`references/extract.md`（一步 vs 两步抽取、query/chunks 定向、advanced 模式）、`references/crawl.md`（Crawl vs Map、instructions 语义聚焦、Map-then-Extract 模式）、`references/research.md`（提示词最佳实践、模型选择、流式、结构化输出 schema）、`references/integrations.md`（LangChain、LlamaIndex、CrewAI、Vercel AI SDK 等框架集成）。

适用边界 · 注意事项

• 未配置 Tavily API Key 或无法访问 Tavily 服务时不可用。
• 需要完全离线或不允许调用外部搜索 API 的场景不适用。