Agent Web Search

Agent Web Search（PyPI：agent-web-search-mcp）是一个面向 AI Agent 的开源、 MIT 许可的网页搜索 MCP 服务、CLI 和 Python 库。它为 Agent 提供三种方式， 让其使用同一个与提供商无关的搜索核心：原生 MCP 工具、原生插件（Hermes、DeepSeek Harness），或通过标准 Agent Skill 教会 Agent 使用的 CLI。

如果你是 AI Agent： 使用 pipx install agent-web-search-mcp 安装 （或通过 uvx --from agent-web-search-mcp agent-web-search "<question>" 即刻试用）， 然后阅读 skills/agent-web-search/SKILL.md — 该文件仅介绍 CLI 路径（MCP 设置请改为遵循选项 1）。 llms.txt 是机器可读的文档索引。

这并不是 Google/Bing/Baidu 元搜索封装。传统的搜索聚合会将关键词查询分发给常规搜索引擎，再合并它们的 结果页面。Agent Web Search 聚合的则是专为 Agent 打造的搜索能力：模型原生网页 grounding、面向 Agent 的搜索 API，以及可直接用于上下文的来源；这些来源接受自然语言问题，并以 Agent 可直接使用的形式返回答案、引文或结构化证据。目前的提供商中，DDGS 是唯一的 传统搜索后端。

          Natural-language question
                      |
                      v
                 SearchEngine
          +-----------+-----------+
          |           |           |
          v           v           v
        DDGS        Model       Agent
                  grounding     APIs
                 (Responses,   (Exa,
                  ARK, Grok,    Parallel,
                  Gemini...)    Tavily...)

安装与快速开始

三个步骤，大约一分钟：立即试用、安装一次，然后连接你的 Agent。 要求： Python 3.10+。默认提供商（DDGS、Exa、Parallel）无需 API 密钥。

无需安装，立即试用

使用 uvx 测试即时搜索功能（不会修改环境）：

# Direct natural-language search with keyless defaults
uvx --from agent-web-search-mcp agent-web-search "What changed in the latest OpenAI Codex CLI?"

# Inspect MCP server arguments
uvx agent-web-search-mcp --help

安装

一次性安装到全局用户环境中（推荐）：

# Recommended isolated installation
pipx install agent-web-search-mcp

# Or install into the active Python environment
python -m pip install agent-web-search-mcp

验证

# 1. Verify the CLI and run a real search
agent-web-search --version
agent-web-search "What changed in the latest OpenAI Codex CLI?"

# 2. Verify the MCP server binary
agent-web-search-mcp --help

两个命令，各司其职：

• agent-web-search：直接用于终端、Shell 脚本和 Agent Skills 的搜索 CLI。
• agent-web-search-mcp：供 MCP 客户端使用的 Stdio 和 Streamable HTTP MCP 服务。

选择 Agent 集成方式

提示

**为什么建议具备 Shell 能力的 Agent 使用 CLI + Skill：**如果你的 Agent 已经具备终端 / bash 执行能力（例如 Claude Code、Codex CLI、OpenCode 或 Hermes），CLI + Skill 路径最简单、最可靠。无需排查 MCP JSON 配置问题，无需管理后台传输的生命周期，而且标准 Skill 还能教会 Agent 输出整洁的 stdout JSON。

为什么选择 Agent Web Search

传统的搜索聚合工具（Google/Bing/Baidu 封装工具、抓取的 SERP）会将关键词查询发送到传统搜索引擎，再合并结果页面。Agent Web Search 聚合的则是专为 Agent 打造的搜索能力：一次工具调用即可返回结构化、可直接引用的证据；也可以通过模型原生的 grounding 提供商，返回附带明确引用的综合答案。一项实测基准展示了实际差异：针对一个询问官方来源的中文自然语言查询，传统 SERP 后端在前 5 条结果中未返回任何政府域名结果，而 grounding 提供商返回了中国海关总署发布的官方数据，并附有可用的引用链接。

• **专为 Agent 原生设计。**主要接口是完整的自然语言问题，而不是向 Google、Bing 或 Baidu 分发关键词的薄封装。
• **模型原生搜索后端。**ARK、Gemini、Grok、DeepSeek、Responses、Messages、Zhipu Chat Search 和 Codex Alpha 可以将网页检索与模型生成的综合答案及明确引用结合起来。
• **Agent 搜索提供商。**Exa、Parallel、Brave、Perplexity、Tavily、You.com 和 Zhipu Web Search 提供搜索 API，旨在为下游 Agent 提供结构化、便于引用或可直接用于上下文的证据。
• **统一且与提供商无关的接口。**所有后端都可通过同一 MCP 工具、CLI、Python API 和规范化的 results 使用；基于模型的提供商还可能返回 answer。
• **提供商相互独立。**所选提供商会并行运行，一个提供商发生故障不会丢弃其他提供商的成功结果。
• **DDGS 仍是简单的备用方案。**DDGS 是唯一的传统搜索后端，无需 API 密钥，即使没有付费提供商凭据，也能让项目继续使用。Exa 和 Parallel 默认也无需密钥。
• **无遥测，不共享密钥。**提供商密钥保存在运行时环境变量中；没有共享 API 密钥服务。

Provider

Provider 列表按其提供的搜索能力类型有意拆分。只有 DDGS 是传统搜索后端；另外两组则围绕模型原生的 grounding 能力或面向 Agent 的搜索服务构建。

免费且无需密钥的默认选项： DDGS、Exa 和 Parallel 均可在无需 API 密钥的情况下使用。在提供付费 API 密钥之前，Exa 和 Parallel 会自动使用免费的 MCP 传输方式。

传统搜索后端

模型 Provider

这些 Provider 使用模型原生的搜索或 grounding 接口。其响应可以包含模型生成的答案，以及引文或其他明确的搜索证据。

Agent 搜索 Provider

这些 Provider 提供供 Agent 使用的搜索服务：自然语言查询、结构化来源条目、高信号摘录或便于引用的元数据，而非传统的搜索页面体验。

Provider 架构有意保持开放：无需更改 MCP、Hermes、CLI 或 Python 接口，即可添加其他具备搜索能力的后端。

与 Agent 一起使用

前提条件： 请先完成安装与快速入门。以下各节提供每种集成方式的详细客户端配置和命令参考。

选项 1：MCP

当 Agent 支持工具服务，且你需要类型化发现、协议级错误或远程访问时，请选择 MCP。同一个 agent-web-search-mcp 命令同时支持本地 stdio 和无状态 Streamable HTTP。

本地 stdio MCP

安装一次软件包：

# Recommended isolated installation
pipx install agent-web-search-mcp

# Or install into the active Python environment
python -m pip install agent-web-search-mcp

然后配置 MCP 客户端启动 agent-web-search-mcp：

{
  "mcpServers": {
    "agent-web-search": {
      "command": "agent-web-search-mcp",
      "args": []
    }
  }
}

如果已可使用 uvx，客户端可以使用命令 uvx 和参数 ["agent-web-search-mcp"] 运行软件包，无需持久安装。

# Codex CLI
codex mcp add agent-web-search -- agent-web-search-mcp

# Claude Code
claude mcp add agent-web-search -- agent-web-search-mcp

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "agent-web-search": {
      "type": "local",
      "command": ["agent-web-search-mcp"],
      "enabled": true
    }
  }
}

通过 HTTPS 使用远程 MCP

使用本 README 顶部的其中一个部署按钮，或自行运行同一个服务：

python -c "import secrets; print(secrets.token_urlsafe(32))"
export AGENT_WEB_SEARCH_AUTH_TOKEN="<your-generated-token>"
agent-web-search-mcp --transport http

该服务提供经过身份验证的 POST /mcp 和公开的 GET /healthz。远程 MCP 客户端的连接方式如下：

{
  "mcpServers": {
    "agent-web-search": {
      "url": "https://your-deployment.example/mcp",
      "headers": {
        "Authorization": "Bearer <your-deployment-token>"
      }
    }
  }
}

每个公开部署都必须将 AGENT_WEB_SEARCH_AUTH_TOKEN 设置为至少 32 个字符。该服务是无状态的，不会创建 MCP-Session-Id 值。

选项 2：CLI + Agent 技能

当 Agent 已具备 Shell 访问权限并支持 Agent Skills 时，请选择这种方式。该技能会教 Agent 如何调用 CLI、选择控制项、解读 results 并处理结构化故障；无需配置 MCP。

1. 安装 CLI：

   pipx install agent-web-search-mcp
   # Or: python -m pip install agent-web-search-mcp
   

2. 安装附带的 agent-web-search 技能：

   npx skills add JerryLiu369/agent-web-search --skill agent-web-search
   

   如果 Agent 不使用 skills 安装程序，请将 skills/agent-web-search 复制到该客户端的 Skills 目录中。

3. 验证 CLI，然后让 Agent 执行搜索：

   agent-web-search --version
   agent-web-search "What changed in the latest OpenAI Codex CLI?"
   

CLI 成功时会向 stdout 写入一份 JSON 文档。如果所有提供方都失败，它会将共享的 all_providers_failed JSON 写入 stderr 并以状态码 1 退出，因此具备 Shell 访问权限的 Agent 可以区分实际故障和空结果。

pipx install 'git+https://github.com/JerryLiu369/agent-web-search.git'

重要

不要将 API 密钥放在 Shell 历史记录、源代码、Git 提交、屏幕截图 或已提交到版本库的 MCP 配置中。请通过服务端或本地 环境变量提供密钥。

通用请求和响应

MCP 提供一个名为 web_search 的工具；CLI 使用相同的输入参数。

调用示例：

{
  "query": "What GPU kernel generation papers were published in the past month?",
  "max_results": 5,
  "time_range": "m",
  "providers": ["ddgs", "exa"]
}

提供方选择分为两个层级：

1. AGENT_WEB_SEARCH_PROVIDERS 用于在进程启动时定义提供方集合。
2. 请求级别的 providers 参数可以缩小该集合，但无法启用启动时已禁用的提供方。

响应格式

每个成功的所选提供方都会显示在 providers 下；失败的提供方 会被省略：

{
  "query": "What GPU kernel generation papers were published in the past month?",
  "providers": {
    "ddgs": {
      "results": [
        {
          "title": "Example result",
          "url": "https://example.com/paper",
          "description": "Excerpt of the matching page",
          "published_at": "2026-08-02"
        }
      ]
    }
  }
}

如果所有所选提供方都失败，MCP 会返回工具错误。CLI 会将 相同的载荷写入 stderr，并以状态码 1 退出。两者均使用稳定的代码 all_providers_failed，并包含各提供方的诊断信息：

{
  "error": {
    "code": "all_providers_failed",
    "message": "All enabled search providers failed. Check provider configuration, credentials, quotas, and network access.",
    "provider_errors": {
      "ddgs": "RuntimeError: rate limited"
    }
  },
  "query": "What GPU kernel generation papers were published in the past month?"
}

Python API

CLI、MCP 服务和 Hermes 插件都是 agent_web_search.SearchEngine 的轻量封装， 它是公开的 Python API。 SearchRequest 接受与 MCP 工具参数相同的字段：

from agent_web_search import SearchEngine, SearchRequest

engine = SearchEngine()  # reads AGENT_WEB_SEARCH_* variables at construction

response = engine.search(
    SearchRequest(
        query="What are the latest changes to the MCP specification?",
        max_results=5,
        time_range="m",
    )
)

for name, provider in response.providers.items():
    print(f"{name}: searched={provider.searched}, results={len(provider.results)}")

if response.all_providers_failed:
    print(response.failed_provider_errors)

配置

CLI、MCP 服务或 Hermes 插件启动时会从环境变量读取配置。更改提供方设置后，请重启进程。 请参阅 .env.example，其中提供了包含所有变量注释的模板。

通用设置

示例：

export AGENT_WEB_SEARCH_PROVIDERS="ddgs,exa,brave"
export AGENT_WEB_SEARCH_TIMEOUT="30"

$env:AGENT_WEB_SEARCH_PROVIDERS = "ddgs,exa,brave"
$env:AGENT_WEB_SEARCH_TIMEOUT = "30"

HTTP 传输设置

HTTP 设置仍仅通过环境变量配置；部署文件不会引入第二种应用配置格式。

提供方设置

以下提供方专属设置涵盖所有提供方的凭据和模型控制项。上文按功能类别 介绍了受支持的提供方；本节提供详细的配置参考。

1. DDGS

DDGS 使用 DuckDuckGo，无需 API 密钥或提供方专属环境变量。安装软件包时会一并安装 ddgs Python 依赖项。

2. Exa

Exa 支持付费和无密钥两种模式。

如果未设置 EXA_API_KEY，Exa 会尽力回退到其免费 MCP 端点。 付费 API 通常提供更高的配额和可靠性。

3. Parallel

Parallel 会返回信息密集、按排名排序的摘录，供大模型上下文使用。一个 parallel 提供方会自动选择其传输方式：

• 不提供密钥时，会使用 Parallel 的免费 Search MCP。
• 设置 PARALLEL_API_KEY 后，会使用付费 Search REST API。

两种传输方式都会将 excerpts 映射到通用结果描述，因此调用 Agent 无需区分 parallel-free 和 parallel。

Parallel 默认启用，密钥为可选项。

4. ARK（推荐）

Volcengine ARK 通过 Responses API 使用由模型支持的搜索 grounding。 提供密钥后，将 ark 添加到 AGENT_WEB_SEARCH_PROVIDERS。

配置一个模型时，该模型保持固定；配置多个模型时，后续请求会按轮询方式选择。配置多个 ARK 密钥时，每个请求都会选择一个密钥。

5. Brave

提供密钥后，将 brave 添加到 AGENT_WEB_SEARCH_PROVIDERS。

6. Gemini

Gemini 会尽力将通用结果和时间控制映射为提示词约束。配置一个模型时，该模型保持固定；配置多个模型时，后续请求会按轮询方式选择。

7. Grok

配置一个模型时，该模型保持固定；配置多个模型时，后续请求会按轮询方式选择。

启用 Grok 后，公开工具架构会添加 grok_search_mode：

• web_search 搜索网页。
• x_search 使用原生日期筛选条件搜索 X（如果可用）。
• both 在一次请求中同时提供两个服务端工具，并由 Grok 选择；不会发出两次独立的模型请求。

8. Codex Alpha（实验性）

codex_alpha 提供方仅使用网关 API 密钥和一个实现 /v1/alpha/search 的完整端点（该提供方不会追加路径）；它不处理 Codex OAuth 令牌。设置端点、密钥和可选模型，然后将 codex_alpha 添加到 AGENT_WEB_SEARCH_PROVIDERS：

该提供方会发送标准的 search_query 命令，并返回标准网页搜索结果。

9. DeepSeek

DeepSeek 使用官方兼容 Anthropic 的 Messages API 和原生 web_search_20250305 服务端工具。它会保留模型生成的最终文本， 并仅将明确的 web_search_result 块映射为标准化结果。因此，有效响应的 answer 可以有内容，而 results 列表为空。

提供密钥后，将 deepseek 添加到 AGENT_WEB_SEARCH_PROVIDERS。 Provider 会在配置的基础 URL 后追加 /v1/messages。多个模型会按轮询方式 用于后续请求。

10. Perplexity

此 Provider 使用 Perplexity 原生结构化 Search API。它返回结果行，而不是 Sonar 生成的散文式回答；与 OpenRouter 的兼容性有意不在此 Provider 的范围内。

提供密钥后，将 perplexity 添加到 AGENT_WEB_SEARCH_PROVIDERS。

11. Tavily

提供密钥后，将 tavily 添加到 AGENT_WEB_SEARCH_PROVIDERS。

12. You.com

You.com 返回统一的网页和新闻部分。Agent Web Search 会合并两者， 对 URL 去重，并将 max_results 应用于合并后的结果列表。

提供密钥后，将 you 添加到 AGENT_WEB_SEARCH_PROVIDERS。

13. Zhipu Web Search

Zhipu Web Search 使用中国区独立 Web Search API，并返回结构化搜索行。它是与 Zhipu Chat Search 分开的 Provider；实现不会在这两个接口之间回退。

提供密钥后，将 zhipu_web_search 添加到 AGENT_WEB_SEARCH_PROVIDERS。 Provider 会在配置的基础 URL 后追加 /api/paas/v4/web_search。

14. Zhipu Chat Search

Zhipu Chat Search 使用中国区 GLM Chat Completions API 和原生网页搜索功能。 它会返回模型回答，以及仅包含明确的顶层搜索行；回答文本中提及的 URL 不会被 视为引文。它是与 Zhipu Web Search 分开的 Provider，且不会在 API 和 Chat 之间回退。

提供密钥后，将 zhipu_chat_search 添加到 AGENT_WEB_SEARCH_PROVIDERS。 Provider 会在配置的基础 URL 后追加 /api/paas/v4/chat/completions。 多个已配置模型会按轮询方式用于后续请求。

15. Responses

Responses 是通用的 OpenAI Responses API 客户端，适用于在 POST {base_url}/responses 提供服务端网页搜索工具的网关。它会遍历 output 数组（绝不假设结果位于 output[0]），将 web_search_call 操作来源和 url_citation 注释映射为规范化结果，并保留模型生成的回答。如果响应只有一条消息且不含 URL，则保留回答，返回空的 results，并将 searched 标记为 false。

提供密钥后，将 responses 添加到 AGENT_WEB_SEARCH_PROVIDERS。 如果配置了多个模型，后续请求会按轮询方式选择模型。

16. Messages

Messages 是通用的 Anthropic Messages API 客户端，适用于在 POST {base_url}/v1/messages 提供服务端网页搜索工具的网关。它会遍历 content 数组（绝不假设结果位于单个内容块中），将 web_search_tool_result / web_search_result 内容块映射为规范化结果，根据引用或结果域名补全缺失的标题，并保留模型生成的回答。如果响应只有文本且不含 URL，则保留回答，返回空的 results，并将 searched 标记为 false。

提供密钥后，将 messages 添加到 AGENT_WEB_SEARCH_PROVIDERS。 如果配置了多个模型，后续请求会按轮询方式选择模型。

常见搜索控制项

每个提供商都会尽可能将共享控制项映射到其原生 API，并忽略不支持的控制项。

基于提示词的控制尽力而为，并非严格保证。

其他接口

原生 Hermes 插件

直接从 GitHub 安装原生插件：

pip install 'ddgs>=9.0'
hermes plugins install JerryLiu369/agent-web-search --no-enable
hermes plugins enable agent-web-search --allow-tool-override

该插件会有意替换 Hermes 内置的 web_search 工具，因此必须授予显式的 --allow-tool-override 权限。启用后，请启动新的 Hermes 会话；使用消息渠道时，请重启网关。

Hermes 也可以通过通用 MCP 集成进行连接，而不使用原生插件。

原生 DeepSeek Harness 插件

直接从 GitHub 安装原生插件（桌面和 CLI 配置均适用——桌面应用自带 dsh plugin 命令，因此无需手动放置文件）：

dsh plugin --profile <profile> add github:JerryLiu369/agent-web-search
python -m pip install agent-web-search-mcp

该插件会有意替换 DSH 原生 web_search 接口背后的实现，同时保留相同的面向模型的工具名称、提示词、规范化来源和引用 UI。它不会公开 mcp__...__web_search 工具。请在与 DSH 相同的环境中安装 agent-web-search-mcp Python 命令；如果 DSH 没有立即识别到新提供商，请重启 DSH。此桥接会将内置提供商的工作委托给该命令，同时 DSH 保留其原生设置、历史记录和诊断信息。完整步骤和可直接复制粘贴的安装提示词，请参阅 integrations/dsh/docs/INSTALL.md。

DSH 也可以通过内置 MCP 客户端进行连接，而不使用原生插件。

故障排除

• all_providers_failed — 所有选定的提供商都发生错误。MCP 会将此次调用标记为错误；CLI 会将诊断信息写入 stderr 并以状态码 1 退出。请检查密钥、配额和网络访问。遇到临时限流时，重试一次可能会有帮助。
• 找不到 agent-web-search — 使用 pipx 或 pip 安装 PyPI 软件包，然后启动新的 shell，使其脚本目录加入 PATH。
• HTTP 401 invalid_token — Authorization: Bearer … 标头必须与 AGENT_WEB_SEARCH_AUTH_TOKEN 匹配，且该令牌至少需要 32 个字符。
• 响应中缺少某个提供商 — 成功响应会省略失败的提供商。Python API 会在 response.failed_provider_errors 中提供失败原因。
• 更改提供商后没有效果 — 提供商设置只会在启动时读取；更改后请重启 CLI、MCP 服务或 Hermes 插件。
• MCP 客户端在工具返回前超时 — AGENT_WEB_SEARCH_TIMEOUT 限制的是单次上游 HTTP 调用，而不是整个搜索过程。无密钥的 Parallel 最多会发起 3 次调用，ARK 也可能追加一次后续请求，因此最坏情况下耗时为 3 × AGENT_WEB_SEARCH_TIMEOUT；请据此配置 MCP 客户端的工具超时时间。

常见问题

什么是 Agent Web Search？

Agent Web Search 是一个面向 AI Agent 的开源网络搜索层。它通过 MCP 服务（stdio 或 Streamable HTTP）、CLI 和 Python API 提供一个 web_search 工具。该工具在后台运行模型原生搜索 grounding 提供商（ARK、Gemini、Grok、DeepSeek、Zhipu Chat Search、Codex Alpha，以及通用 Responses/Messages 网关）、Agent 搜索 API（Exa、Parallel、Brave、Perplexity、Tavily、You.com、Zhipu Web Search）和作为传统备用方案的 DuckDuckGo，然后返回一个规范化的 JSON 响应。

有没有无需 API 密钥的免费网络搜索 MCP 服务？

有。默认提供商组——DDGS、Exa 和 Parallel——无需任何 API 密钥即可使用。在设置 EXA_API_KEY 或 PARALLEL_API_KEY 之前，Exa 和 Parallel 会尽力使用其免费 MCP 端点。付费提供商需通过 AGENT_WEB_SEARCH_PROVIDERS 选择启用。

它与 Google/Bing 元搜索 MCP 有何不同？

元搜索服务会抓取传统搜索结果页面并将其合并。Agent Web Search 聚合专为 Agent 构建的搜索服务，包括模型原生 grounding，后者会返回带有引用的综合 answer。与 open-webSearch 的正面对比基准测试记录了其中的差异及其注意事项：来自数据中心 IP 的 SERP 抓取经常遭到机器人拦截，而由 API 支持的提供商则会减少结果行数，而非不返回任何结果。

它适用于哪些 Agent 和客户端？

任何支持 stdio 或 Streamable HTTP 的 MCP 客户端都适用，包括 Codex CLI、Claude Code、OpenCode、Cursor、Cline 和 Claude Desktop。Hermes 提供原生插件。支持 Shell 的 Agent 可以使用附带的 Agent Skill 配合 CLI，而无需使用 MCP。

我应该使用 MCP 服务，还是 CLI + Skill？

当客户端支持工具服务，且你需要类型化的工具发现、协议级错误或远程部署时，使用 MCP。当 Agent 已具备 Shell 且支持 Agent Skills 时，使用 CLI + Skill；它无需 MCP 配置。两者返回的响应结构相同。

我可以使用自己的 OpenAI 或 Anthropic 兼容网关进行搜索 grounding 吗？

可以。responses 提供商会调用任何带有服务端网络搜索工具的 OpenAI Responses API 网关；messages 提供商对 Anthropic Messages API 网关也采用相同方式。通过提供商设置中的变量设置基础 URL、密钥和模型。

我可以将它托管为远程 MCP 服务吗？

可以。agent-web-search-mcp --transport http 会在 POST /mcp 提供无状态的 Streamable HTTP，并使用 Bearer 令牌进行身份验证。项目提供了适用于 Vercel、Railway、Render 和 Zeabur 的一键部署模板，仓库中也包含 Dockerfile。

它会收集遥测数据或存储我的 API 密钥吗？

不会。它不收集遥测数据，也不提供共享密钥服务。提供商凭据会从运行搜索的机器或服务器的环境变量中读取，绝不会作为工具参数接收。

开发

使用 uv 可保持开发环境隔离且可复现：

git clone https://github.com/JerryLiu369/agent-web-search.git
cd agent-web-search
uv venv
uv pip install -e '.[dev]'
uv run --extra dev pytest -q
uv run ruff check .

python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install -e '.[dev]'
pytest -q
ruff check .

ARCHITECTURE.md 是设计的权威依据，AGENTS.md 列出了不可妥协的约束。在更改传输方式、配置、身份验证、部署、提供商或工具架构之前，请先阅读这两份文件；确保 stdio 和 HTTP 的行为一致，并在同一次更改中确保 pytest 和 ruff 均通过。

许可证

MIT