Agent Web Search（agent-web-search-mcp） Skill 技能

技能简介

Agent Web Search（agent-web-search-mcp）是一个面向 AI Agent 的原生网页搜索 MCP 工具，同时支持本地 stdio 和远程 Streamable HTTP 两种接入方式。与传统搜索引擎聚合器不同，它聚合的是模型原生联网搜索（如 Gemini、DeepSeek、Grok）和专业 Agent 搜索服务（如 Exa、Perplexity、Tavily），返回自然语言答案和可溯源的结构化结果，而非传统搜索结果页。

该工具支持 MCP 2.x 协议，兼容 Codex CLI、Claude Code、OpenCode、Hermes 等主流 Agent，也可通过 Python API 或 CLI 独立使用。内置 14 个搜索 Provider，默认无需 API Key 即可调用 DDGS（DuckDuckGo）、Exa 和 Parallel 三个免费 Provider。

核心能力

1. 多 Provider 聚合搜索：支持 14 个搜索后端（DDGS、Exa、Parallel、Brave、Perplexity、Tavily、You.com、ARK、Gemini、Grok、DeepSeek、Codex Alpha、Zhipu Web Search、Zhipu Chat Search），统一返回格式
2. MCP 2.x 原生工具：web_search 工具接受自然语言问题 + 时间范围 + 结果数量，标准化返回结构化 JSON
3. 零配置免费使用：默认启用 DDGS（无需 Key）、Exa 和 Parallel（免费 MCP 模式），开箱即用
4. 远程 MCP 部署：支持 HTTPS 远程连接，部署到 Vercel/Railway/Render/Zeabur 后通过 Bearer Token 鉴权
5. Agent Skill 接入：为命令行环境提供标准 Skill 包，通过 npx skills add 安装，无需配置 MCP
6. Python API 封装：SearchEngine 类可直接在 Python 代码中调用搜索能力
7. 并发独立 Provider：每个 Provider 独立运行，一个失败不影响其他 Provider 的结果

安装配置

前置条件：Python 3.10+

方式一：pip 安装（推荐）

pipx install agent-web-search-mcp
# 或
python -m pip install agent-web-search-mcp

方式二：开发模式从源码安装

git clone https://github.com/JerryLiu369/agent-web-search.git
cd agent-web-search
pip install -e '.[dev]'

方式三：uvx 免安装运行

如果系统中已安装 uvx，可直接运行而无需持久安装：

uvx agent-web-search-mcp

使用步骤

第一步：确认 Agent 支持的接入方式

• MCP 原生工具（推荐）：适用于 Codex CLI、Claude Code、OpenCode 等支持 MCP 工具发现的 Agent
• Agent Skill + CLI：适用于有 Shell 访问权限且支持 Agent Skill 的 Agent（如 Claude Code 配置 Skill 目录）

第二步：配置 MCP 客户端（以 Claude Code 为例）

在 Claude Code 配置文件中添加：

{
  "mcpServers": {
    "agent-web-search": {
      "command": "agent-web-search-mcp"
    }
  }
}

第三步：配置搜索 Provider（可选）

默认使用 DDGS、Exa、Parallel 三个免费 Provider。如需启用更多 Provider，设置环境变量：

export AGENT_WEB_SEARCH_PROVIDERS="ddgs,exa,parallel,perplexity,tavily"

第四步：执行搜索

Agent 调用 web_search 工具，传入自然语言查询：

{
  "query": "过去一个月关于 LLM 推理优化的最新论文",
  "max_results": 5,
  "time_range": "m",
  "providers": ["ddgs", "exa"]
}

适用场景

1. Agent 实时信息查询：需要获取最新新闻、技术文档或市场数据的 AI Agent，通过模型原生搜索返回带引用的答案
2. 代码与文档研究：Agent 在编写代码前搜索相关技术文档、开源项目或 API 使用示例
3. 多源交叉验证：需要同时从多个搜索 Provider 获取结果并比对的场景（如学术研究、市场调研）
4. 结构化知识抽取：从 Exa、Perplexity 等 Agent 搜索服务中提取高信号段落作为上下文

适用人群

• AI 应用开发者：需要为 AI Agent 快速集成网页搜索能力的开发者
• Claude Code / Codex CLI 用户：希望 Agent 在编程时能够主动搜索最新技术文档和解决方案
• RAG 系统构建者：需要高质量、结构化、可溯源的搜索结果作为知识库输入

工作原理

Agent Web Search 的核心是一个 Provider 中立搜索引擎 SearchEngine。用户传入自然语言查询后，引擎并发调用所有启用的 Provider，每个 Provider 将请求转换为各自后端 API 格式并获取结果。成功返回的 Provider 结果合并为统一 JSON 格式（包含 answer 字段和 results 数组），失败的 Provider 从响应中省略并记录在 provider_errors 中。

对于模型原生 Provider（如 Gemini、DeepSeek），响应包含模型生成的文字答案；对于传统搜索 Provider（如 DDGS），响应仅包含结构化结果列表。

官方链接

• GitHub 仓库：https://github.com/JerryLiu369/agent-web-search
• PyPI 安装包：https://pypi.org/project/agent-web-search-mcp/
• 中文 README：https://github.com/JerryLiu369/agent-web-search/blob/main/README.zh-CN.md
• MCP 协议：https://modelcontextprotocol.io/