Agent Web Search 是一个开源的、MIT 许可的网页搜索 MCP 服务器、命令行工具与 Python 库，专为 AI 智能体设计。它并非 Google/Bing/百度 传统元搜索聚合器：传统聚合会把关键词分发到常规引擎再合并结果页，而 Agent Web Search 聚合的是为智能体构建的搜索能力，包括模型原生联网搜索、面向智能体的搜索 API，以及能接受自然语言问题并直接返回答案、引用或结构化证据的来源。当前提供商中仅 DDGS 属于传统搜索后端。
用途与定位 该项目为智能体提供统一的中立搜索契约，使其可通过同一个 MCP 工具、CLI、Python API 获取归一化结果，部分模型后端还可返回答案。它适用于 Claude Code、Hermes、DeepSeek Harness（DSH）、OpenCode、Codex CLI 等支持 shell 或 MCP 的智能体，也适用于普通 shell 脚本、Python 应用和远程 Streamable HTTP MCP 客户端。
主要能力 分为三类搜索能力：
- 传统搜索后端：DDGS，使用 DuckDuckGo，无需 API 密钥，随包安装 ddgs 依赖。
- 模型提供商：使用模型原生搜索或联网表面，可返回模型生成的答案及引用或显式搜索证据。包括 ARK、Gemini、Grok、DeepSeek、Responses、Messages、Zhipu Chat Search、Codex Alpha。
- 智能体搜索提供商：面向智能体消费，支持自然语言查询、结构化来源行、高信号摘录或适合引用的元数据。包括 Exa、Parallel、Brave、Perplexity、Tavily、You.com、智谱 Web Search。 其他特性：各提供商可并发运行，单提供商失败不会丢弃其他成功结果；默认免费无密钥的提供商为 DDGS、Exa、Parallel；无遥测，无共享密钥服务，密钥通过运行时环境变量提供；提供商架构开放，可在不改变 MCP、Hermes、CLI 或 Python 接口的情况下新增搜索后端。
使用方式 三种接入形态：原生 MCP 工具、原生插件（Hermes、DeepSeek Harness），或通过标准 Agent Skill 教会智能体使用的 CLI。要求 Python 3.10+。 快速开始：
- 免安装试用：uvx --from agent-web-search-mcp agent-web-search "<question>"。
- 推荐安装到全局用户环境：pipx install agent-web-search-mcp，或 python -m pip install agent-web-search-mcp。 两个命令：agent-web-search 为搜索 CLI；agent-web-search-mcp 为 stdio 与 Streamable HTTP MCP 服务器。 方式一 MCP：安装包后配置 MCP 客户端启动 agent-web-search-mcp；若已有 uvx，可用 command uvx、args ["agent-web-search-mcp"] 免持久安装运行。远程部署暴露需认证的 POST /mcp 与公开 GET /healthz；任何公开部署必须设置 AGENT_WEB_SEARCH_AUTH_TOKEN 且至少 32 字符；服务器无状态，不创建 MCP-Session-Id。 方式二 CLI + Agent Skill（推荐给具备终端执行能力的智能体）：安装 pipx install agent-web-search-mcp，通过 npx skills add JerryLiu369/agent-web-search --skill agent-web-search 安装附带 Skill（若不支持 skills 安装器，则复制 skills/agent-web-search 到客户端 Skills 目录），然后智能体即可调用 CLI 搜索。成功时 CLI 向 stdout 写入一个 JSON 文档；若所有提供商失败，则向 stderr 写入共享的 all_providers_failed JSON 并以状态码 1 退出，便于区分真实失败与空结果。
请求与响应 MCP 暴露一个名为 web_search 的工具，CLI 映射相同输入。提供商选择分两级：AGENT_WEB_SEARCH_PROVIDERS 定义进程启动时的提供商集合；请求级 providers 参数可收窄该集合，但不能启用启动时已禁用的提供商。每个成功提供商结果出现在 providers 下，失败者被省略；若全部失败则返回工具错误，使用稳定代码 all_providers_failed 并包含各提供商诊断。CLI、MCP 服务器与 Hermes 插件都是 agent_web_search.SearchEngine 的薄封装，SearchRequest 接受与 MCP 工具参数相同的字段。
提供商配置要点 配置从环境变量读取，更改后需重启进程。DDGS 无需密钥。Exa 支持付费与无密钥模式，无 EXA_API_KEY 时尽力回退到免费 MCP 端点。Parallel 返回信息密集、面向 LLM 上下文的摘录，无密钥用免费 Search MCP，有 PARALLEL_API_KEY 用付费 Search REST API，默认启用且密钥可选。ARK 使用 Responses API 的模型联网搜索，可配置多模型轮询与多密钥。Brave、Tavily、Perplexity、You.com、智谱 Web Search、智谱 Chat Search、Gemini、Grok、DeepSeek、Codex Alpha 等均需在提供密钥后加入 AGENT_WEB_SEARCH_PROVIDERS。Grok 启用后工具模式增加 grok_search_mode（web_search、x_search、both）。DeepSeek 使用官方 Anthropic 兼容 Messages API 与原生 web_search_20250305 服务器工具。Perplexity 使用原生结构化 Search API，返回结果行而非 Sonar 散文答案。You.com 合并网页与新闻并按 max_results 去重。智谱 Web Search 与智谱 Chat Search 是两个独立提供商，无 API/Chat 回退。
限制与注意事项 不得将 API 密钥放入 shell 历史、源代码、Git 提交、截图或已签入的 MCP 配置，应通过服务器端或本地环境变量提供。各提供商的配额、支持模型、有效期与数据授权条款可能变化，需查阅官方条款。DDGS 是唯一传统搜索后端。远程部署必须设置认证令牌。部分提供商可能返回有答案但结果列表为空的有效响应。详情与未列出的其他提供商配置，资料中未完全提供，请参考项目仓库与 .env.example 模板。
