Tavily 接入指南：让 AI Agent 拥有实时联网能力

本文基于 Tavily 官方文档整理，涵盖四种接入方式的原理、配置与实战示例，帮助你快速选择最适合自己场景的集成方案。

Tavily 是什么链接到标题

Tavily 是一个专为 AI Agent 和 LLM 优化的搜索引擎 API。与 Google、Bing 等传统搜索 API 不同，Tavily 不仅仅是返回一串 URL 和摘要——它在一次 API 调用中完成搜索、抓取、过滤、提取和排序，直接把最相关的结构化内容喂给你的模型。

核心能力：

能力	说明
Search	AI 优化的网页搜索，支持深度、领域、时间范围等精细控制
Extract	从 URL 提取干净的 Markdown/文本，支持 JS 渲染页面
Crawl	批量爬取网站多页面内容，支持语义过滤和路径筛选
Map	发现网站所有 URL，不提取内容，用于构建站点地图
Research	AI 驱动的深度研究，自动搜索、分析、生成带引用的报告

免费额度： 每月 1,000 API Credits，无需信用卡。注册即用。

四种接入方式概览链接到标题

Tavily 提供了四种接入方式，覆盖从「终端命令行」到「AI 编程助手」到「自定义 Agent」的全部场景：

方式	适合谁	复杂度	灵活度
Tavily CLI	终端用户、脚本、CI/CD	★☆☆	★★☆
Agent Skills	Claude Code / Cursor 等用户	★☆☆	★★★
MCP Server	Claude Desktop / Cursor / OpenAI	★★☆	★★★
API / SDK	后端开发者、自建 Agent	★★★	★★★

下面逐一讲解。

方式一：Tavily CLI —— 命令行直连链接到标题

tvly 是 Tavily 的命令行工具，一条命令即可搜索、提取、爬取、研究。所有命令支持 --json 输出，方便接入脚本和管道。

安装链接到标题

1
2
3
4
5
curl -fsSL https://cli.tavily.com/install.sh | bash

# 或用 pip / uv
pip install tavily-cli
# uv tool install tavily-cli

认证链接到标题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 方式一：API Key 登录（推荐）
tvly login --api-key tvly-YOUR_API_KEY

# 方式二：浏览器 OAuth
tvly login

# 方式三：环境变量
export TAVILY_API_KEY=tvly-YOUR_API_KEY

# 验证状态
tvly auth

常用命令速查链接到标题

搜索：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 基础搜索
tvly search "AI 编程助手 2025"

# 高级搜索 + AI 生成答案
tvly search "transformer 架构原理" --depth advanced --include-answer advanced

# 限定领域 + 时间范围
tvly search "Python 异步编程" --include-domains docs.python.org --time-range month

# 新闻搜索
tvly search "AI 监管" --topic news --time-range week

提取网页内容：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# 单个 URL
tvly extract "https://example.com/article" --json

# 多个 URL（最多 20 个）
tvly extract "https://a.com/p1" "https://b.com/p2" --json

# JS 渲染页面
tvly extract "https://spa-site.com" --extract-depth advanced --json

# 按查询相关性过滤
tvly extract "https://docs.python.org/3/" --query "list comprehension" --chunks-per-source 3

爬取整站：

1
2
3
4
5
6
7
8
# 爬取文档站
tvly crawl "https://docs.example.com" --max-depth 2 --limit 50

# 按路径过滤 + 保存为本地 Markdown
tvly crawl "https://example.com" --select-paths "/api/.*" --output-dir ./api-docs/

# 语义引导爬取
tvly crawl "https://docs.example.com" --instructions "只关注认证相关的页面"

站点地图发现：

1
tvly map "https://docs.example.com" --max-depth 3 --limit 200

深度研究：

1
2
3
4
5
6
7
8
# 快速研究
tvly research "React vs Vue 2025 技术选型对比"

# 专业模式 + 实时流式输出
tvly research "AI 对医疗行业的影响" --model pro --stream

# 保存报告（带引用格式）
tvly research "远程办公对生产力的影响" --citation-format apa -o report.md

交互模式：

1
2
3
4
tvly          # 进入 REPL
# > search "最新 AI 新闻"
# > extract https://example.com
# > exit

小贴士链接到标题

所有命令加 --json 可获得机器可读输出，方便 jq 管道处理
人类可读信息输出到 stderr，JSON 数据输出到 stdout，互不干扰
退出码：0 成功，2 参数错误，3 认证失败，4 API 错误

方式二：Agent Skills —— AI 编程助手一键接入链接到标题

如果你使用 Claude Code、OpenCode、Cursor、Cline、Windsurf 等 AI 编程助手，Agent Skills 是最省心的接入方式。安装后，AI 会自动判断何时调用 Tavily，无需手动配置。

安装链接到标题

1
2
3
4
5
6
7
8
# 第一步：安装 Tavily CLI（Skills 的底层引擎）
curl -fsSL https://cli.tavily.com/install.sh | bash

# 第二步：安装所有 Skills
npx skills add tavily-ai/skills --all

# 或只安装单个 Skill
npx skills add tavily-ai/skills --skill tavily-search

安装后重启你的 AI 编程助手即可。

安装范围：项目级 vs 全局链接到标题

npx skills add 的安装位置取决于你的工作目录：

1
2
3
4
5
# 在项目目录下安装 → 仅该项目生效（写入 .agents/skills/）
cd /your/project && npx skills add tavily-ai/skills --all

# 加 -g 参数 → 全局安装（写入 ~/.agents/skills/），所有项目生效
npx skills add tavily-ai/skills --all -g

目录对应关系：

安装方式	文件位置	作用范围
项目级（默认）	`<project>/.agents/skills/`	仅当前项目
全局（`-g`）	`~/.agents/skills/`	所有项目

查看当前安装情况：

1
2
npx skills list          # 查看项目级 Skills
npx skills list -g       # 查看全局 Skills

如果之前在项目目录安装了 Skills，想改为全局可用，可以手动移动：

1
mv /your/project/.agents/skills/tavily-* ~/.agents/skills/

也可以在 ~ 目录下直接执行安装命令，效果等同于 -g。

更新 Skills 链接到标题

Skills 支持更新，当上游仓库发布新版本时，可以一键升级：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# 更新所有 Skills（会提示选择更新项目级还是全局）
npx skills update

# 仅更新项目级
npx skills update -p

# 仅更新全局
npx skills update -g

# 更新指定 Skill
npx skills update tavily-search

# 跳过确认提示，自动检测范围
npx skills update -y

更新机制会从 GitHub 源仓库拉取最新的 SKILL.md 文件覆盖本地版本，同时更新 skills-lock.json 中的哈希值。

卸载 Skills 链接到标题

1
2
3
4
5
6
7
8
# 交互式选择要卸载的 Skills
npx skills remove

# 卸载指定 Skill
npx skills remove tavily-search

# 从全局范围卸载
npx skills remove tavily-search -g

可用 Skills 一览链接到标题

Skill	功能	触发场景
`tavily-search`	网页搜索	“搜索最新的 AI 监管新闻”
`tavily-extract`	URL 内容提取	“提取这篇文章的内容”
`tavily-crawl`	站点批量爬取	“爬取 Stripe API 文档”
`tavily-map`	URL 发现	“列出这个站点的所有页面”
`tavily-research`	深度研究报告	“研究 AI Agent 框架的竞争格局”
`tavily-best-practices`	最佳实践参考	“/tavily-best-practices”

使用方式链接到标题

自动触发 —— 直接用自然语言描述需求，AI 自动选择合适的 Skill：

1
搜索最新的 AI 监管新闻

1
爬取 Stripe API 文档并保存到本地

1
研究 AI 编程助手的竞争格局

显式调用 —— 使用斜杠命令精确控制：

1
2
3
4
/tavily-search React 最佳实践
/tavily-extract https://example.com/blog/post
/tavily-crawl https://docs.example.com
/tavily-research AI Agent 框架对比 -o report.json

高效工作流：Map → Extract 链接到标题

1
2
先 /tavily-map 发现站点结构，找到目标页面 URL
再 /tavily-extract 提取特定页面内容

这比爬取整个站点更高效。

方式三：MCP Server —— 模型上下文协议接入链接到标题

MCP（Model Context Protocol）是 Anthropic 制定的开放标准，让 AI 系统能与外部数据源和工具双向通信。Tavily MCP Server 让任何 MCP 客户端直接使用 Tavily 的搜索和提取能力。

远程 MCP（推荐，零安装）链接到标题

最简单的方式，只需一个 URL：

1
https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>

接入 Cursor 链接到标题

在 mcp.json 中添加：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "tavily-remote-mcp": {
      "command": "npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>",
      "env": {}
    }
  }
}

接入 Claude Desktop 链接到标题

打开 Claude Desktop → 点击双滑块按钮 → 添加集成 → 输入远程 MCP URL → 确认。

接入 Claude Code 链接到标题

1
claude mcp add tavily-remote-mcp --transport http https://mcp.tavily.com/mcp/

首次使用时会打开浏览器完成 OAuth 授权，无需在 URL 中放 API Key。

或手动配置 .claude/settings.json：

1
2
3
4
5
6
7
8
{
  "mcpServers": {
    "tavily-remote-mcp": {
      "type": "http",
      "url": "https://mcp.tavily.com/mcp/"
    }
  }
}

接入 OpenAI 链接到标题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
from openai import OpenAI

client = OpenAI()

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "mcp",
            "server_label": "tavily",
            "server_url": "https://mcp.tavily.com/mcp/?tavilyApiKey=<your-api-key>",
            "require_approval": "never",
        },
    ],
    input="搜索最新的量子计算进展",
)

print(resp.output_text)

设置默认参数链接到标题

通过 DEFAULT_PARAMETERS 头部或环境变量预设默认行为：

1
2
3
4
5
{
  "include_images": true,
  "search_depth": "advanced",
  "max_results": 10
}

本地 MCP 链接到标题

需要 Node.js v20+：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
  "mcpServers": {
    "tavily-mcp": {
      "command": "npx",
      "args": ["-y", "tavily-mcp@0.1.3"],
      "env": {
        "TAVILY_API_KEY": "tvly-YOUR_API_KEY",
        "DEFAULT_PARAMETERS": "{\"search_depth\": \"advanced\", \"max_results\": 15}"
      }
    }
  }
}

OAuth 认证链接到标题

远程 MCP 支持 OAuth 认证，无需在 URL 中暴露 API Key。使用 mcp_auth_default 命名的 Key 可控制 OAuth 场景下使用哪个 API Key（个人 Key 优先于团队 Key）。

清除 OAuth 凭证重新认证：

1
rm -rf ~/.mcp-auth

方式四：API / SDK —— 自定义集成链接到标题

适合后端开发者和自建 Agent 场景。Tavily 提供了 Python SDK、JavaScript SDK 和 REST API。

Python 示例：

1
2
3
4
5
6
7
8
9
from tavily_python import TavilyClient

client = TavilyClient(api_key="tvly-YOUR_API_KEY")

# 搜索
results = client.search("AI agent frameworks", max_results=5, search_depth="advanced")

# 提取
extracted = client.extract(["https://example.com/article"])

JavaScript 示例：

1
2
3
4
5
6
7
8
import { tavily } from "@tavily/core";

const client = tavily({ apiKey: "tvly-YOUR_API_KEY" });

const results = await client.search("AI agent frameworks", {
  maxResults: 5,
  searchDepth: "advanced",
});

Tavily 还与 LangChain、LlamaIndex、Vercel AI SDK、CrewAI、Dify、n8n 等 20+ 框架和平台有官方集成。

如何选择链接到标题

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
你用什么工具？
│
├─ 终端 / 脚本 ────────→ Tavily CLI
│
├─ Claude Code / Cursor ─→ Agent Skills（自动生效）
│
├─ Claude Desktop ──────→ MCP Server（远程）
│
├─ 自建 Agent / 后端 ───→ API / SDK
│
└─ 其他 MCP 客户端 ─────→ MCP Server（远程或本地）

你的场景	推荐方式	理由
快速搜索、脚本自动化	CLI	最轻量，一行命令搞定
日常 AI 编程、让 AI 自动联网	Skills	零配置，AI 自动判断何时调用
Claude Desktop / Cursor 深度集成	MCP	原生协议支持，双向通信
生产级 Agent、RAG 系统	API/SDK	完全控制，灵活定制

常见问题链接到标题

Q: 免费额度够用吗？ 每月 1,000 Credits。一次基础搜索约 1 Credit，高级搜索约 2 Credits，提取约 1 Credit。轻度使用完全够，生产环境可升级付费计划。

Q: CLI 和 Skills 是什么关系？ Skills 底层调用的是 CLI（tvly 命令）。Skills 安装后会在 AI 编程助手中注册指令，AI 根据上下文自动选择合适的 CLI 命令执行。

Q: MCP 和 Skills 有什么区别？ MCP 是标准协议，任何 MCP 客户端都能用；Skills 是专为 AI 编程助手（Claude Code、Cursor 等）设计的，通过 CLI 工作。如果你同时用 Cursor 和 Claude Desktop，可以 MCP + Skills 同时安装。

Q: 支持中文搜索吗？ 完全支持。搜索结果取决于互联网上的内容，中文查询会返回中文结果。

Q: API Key 在哪里获取？ app.tavily.com 免费注册，在 Dashboard 中即可看到 API Key。

Q: Skills 装在项目目录下还是全局？有什么区别？ 默认装在当前项目目录的 .agents/skills/ 下，仅在该项目生效。加 -g 参数或在 ~ 目录下安装则全局生效。全局安装后所有项目都能使用这些 Skills。

Q: Skills 怎么更新？能更新吗？ 可以。npx skills update 一键更新所有 Skills，npx skills update -g 更新全局的，npx skills update <skill-name> 更新单个。更新会从 GitHub 拉取最新版本并覆盖本地文件。

参考链接链接到标题

官方文档：docs.tavily.com
API Key 注册：app.tavily.com
MCP Server GitHub：github.com/tavily-ai/tavily-mcp
Agent Skills GitHub：github.com/tavily-ai/skills
CLI PyPI：pypi.org/project/tavily-cli
API Playground：app.tavily.com/playground

Tavily 是什么 链接到标题

四种接入方式概览 链接到标题

方式一：Tavily CLI —— 命令行直连 链接到标题

安装 链接到标题

认证 链接到标题

常用命令速查 链接到标题

小贴士 链接到标题

方式二：Agent Skills —— AI 编程助手一键接入 链接到标题

安装 链接到标题

安装范围：项目级 vs 全局 链接到标题

更新 Skills 链接到标题

卸载 Skills 链接到标题

可用 Skills 一览 链接到标题

使用方式 链接到标题

高效工作流：Map → Extract 链接到标题

方式三：MCP Server —— 模型上下文协议接入 链接到标题

远程 MCP（推荐，零安装） 链接到标题

接入 Cursor 链接到标题

接入 Claude Desktop 链接到标题

接入 Claude Code 链接到标题

接入 OpenAI 链接到标题

设置默认参数 链接到标题

本地 MCP 链接到标题

OAuth 认证 链接到标题

方式四：API / SDK —— 自定义集成 链接到标题

如何选择 链接到标题

常见问题 链接到标题

参考链接 链接到标题

Tavily 是什么链接到标题

四种接入方式概览链接到标题

方式一：Tavily CLI —— 命令行直连链接到标题

安装链接到标题

认证链接到标题

常用命令速查链接到标题

小贴士链接到标题

方式二：Agent Skills —— AI 编程助手一键接入链接到标题

安装链接到标题

安装范围：项目级 vs 全局链接到标题

可用 Skills 一览链接到标题

使用方式链接到标题

方式三：MCP Server —— 模型上下文协议接入链接到标题

远程 MCP（推荐，零安装）链接到标题

设置默认参数链接到标题

OAuth 认证链接到标题

方式四：API / SDK —— 自定义集成链接到标题

如何选择链接到标题

常见问题链接到标题

参考链接链接到标题