智能体联网搜索 JerryLiu369/agent-web-search

Agent Web Search

为 AI Agent 而生的原生联网搜索层 — 将模型原生 Grounding 与 Agent 专属搜索 API 统一于中立契约之下。

一键部署远程 MCP

支持 Codex CLI、Claude Code、OpenCode、Hermes、DeepSeek Harness (DSH)、普通命令行脚本、Python 应用和远程 Streamable HTTP MCP 客户端。

快速上手 · 给 Agent 使用 · 搜索服务 · 配置

统一接口 · 其他接口 · 故障排查 · 常见问题 · 架构 · 开发

Agent Web Search（PyPI 包名 agent-web-search-mcp）是一个开源、MIT 许可的 AI Agent 联网搜索 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 "<问题>" 免安装直接体验），然后阅读 skills/agent-web-search/SKILL.md ——它只教 CLI 形态（走 MCP 请看形态一），llms.txt 是机器可读的文档索引。

它不是 Google、Bing、百度那种传统搜索引擎聚合器。传统聚合器通常把一个关键词请求分发给多个搜索引擎，再合并搜索结果页；Agent Web Search 聚合的是专门面向 Agent 的搜索能力：模型原生联网搜索、面向 Agent 的搜索 API，以及适合直接放入上下文的高信号来源。它们接受自然语言问题，返回模型回答、引用或结构化证据，Agent 可以直接使用。当前 Provider 集合中，只有 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+。默认启用的 Provider 组合（DDGS、Exa、Parallel）完全免 API Key，开箱即用。

免安装即刻体验

使用 uvx 体验即时搜索，不修改本地任何环境和 PATH：

直接用免 Key 默认源发起自然语言搜索 uvx --from agent-web-search-mcp agent-web-search "OpenAI Codex CLI 最新版本有哪些变化？"

查看 MCP 服务器运行参数 uvx agent-web-search-mcp --help

一键安装

推荐使用 pipx 隔离安装到全局环境（只需一次）：

推荐：全局隔离安装 pipx install agent-web-search-mcp

或安装到当前 Python 环境
python -m pip install agent-web-search-mcp

验证运行

1. 验证 CLI 并进行真实搜索 agent-web-search --version agent-web-search "OpenAI Codex CLI 最新版本有哪些变化？"

2. 验证 MCP 服务器命令 agent-web-search-mcp --help

两个命令分工明确：
- agent-web-search：面向终端交互、Shell 脚本与 Agent Skill 的直接搜索命令行工具。
- agent-web-search-mcp：面向 MCP 客户端的 Stdio 与 Streamable HTTP MCP 服务器。

选择接入形态

| 接入形态 | 适用环境 / 客户端 | 一键接入命令 |
| CLI + Skill (推荐) | 具备终端命令执行能力的 Agent（Claude Code、Codex、OpenCode、Hermes） | npx skills add JerryLiu369/agent-web-search --skill agent-web-search（详细说明） |
| MCP (Stdio) | Codex CLI、Claude Code、Cursor、Cline、Roo Code | codex mcp add agent-web-search -- agent-web-search-mcp（详细说明） |
| DSH 原生插件 | DeepSeek Harness（桌面端与网页端） | dsh plugin --profile desktop add github:JerryLiu369/agent-web-search（详细说明） |
| Hermes 原生插件 | Hermes Agent | hermes plugins install JerryLiu369/agent-web-search（详细说明） |

[!TIP]
为什么对有终端能力的 Agent 推荐 CLI + Skill： 如果你的 Agent 自身具备 Bash/命令行执行能力（如 Claude Code、Codex CLI、OpenCode 或 Hermes），CLI + Skill 是心智负担最小、最可靠的形态：无需配置繁杂的 MCP JSON 文件，没有后台常驻进程挂死或清理问题，单次命令即返回结构化高信噪比的 JSON 证据。

为什么选择 Agent Web Search

传统搜索聚合（Google/Bing/百度封装、抓取 SERP）把关键词查询发给传统搜索引擎再合并结果页。Agent Web Search 聚合的是为 Agent 构建的搜索能力：一次工具调用返回结构化、可直接引用的证据——或通过模型原生 grounding 提供商返回带明确引用的综合回答。实测基准显示了实际差异：在一个要求官方来源的中文自然语言查询上，传统 SERP 后端前 5 条结果没有任何政府域名，而 grounding 提供商返回了海关总署数据并附可用引用链接。

- 从设计上就是 Agent-native。 主要输入是完整的自然语言问题，而不是把关键词简单分发给 Google、Bing 或百度。
- 模型原生搜索后端。 ARK、Gemini、Grok、DeepSeek、Messages、智谱 Chat Search 和 Codex Alpha 可以把联网检索、模型综合回答与明确引用结合起来。
- Agent 搜索提供商。 Exa、Parallel、Brave、Perplexity、Tavily、You.com 和智谱 Web Search 提供面向 Agent 的搜索 API，输出结构化、适合引用或适合放入上下文的证据。
- 统一的 Provider-neutral 契约。 所有后端都通过同一个 MCP 工具、CLI、Python API 和统一的 results 返回；模型后端还可以返回 answer。
- Provider 相互独立。 选中的 Provider 会并发执行，一个 Provider 失败不会丢弃其他 Provider 的成功结果。
- 保留一个简单的 DDGS 后端。 DDGS 是唯一的传统搜索后端，不需要 API Key；Exa 和 Parallel 默认也可以免 Key 使用。
- 无遥测、不共享密钥。 Provider Key 只存在于运行环境变量中，项目不提供共享 API Key 服务。

搜索服务

下面按搜索能力类型划分 Provider。DDGS 是唯一的传统搜索后端；其余 Provider 分别属于模型原生搜索或面向 Agent 的搜索服务。

默认免费、无需 Key： DDGS、Exa 和 Parallel 都可以不配置 API Key 直接使用。Exa 和 Parallel 只有在提供付费 API Key 后才会切换到付费接口，否则自动使用免费 MCP。

传统搜索后端

| Provider | 官网 | 搜索后端 | API Key | 默认启用 |
| DDGS | DuckDuckGo | 传统 DuckDuckGo 搜索 | 免费 · 无需 Key | 是 |

大模型提供商

这类 Provider 使用模型原生联网搜索或 grounding 能力。响应可以同时包含模型生成的回答，以及明确的引用或其他搜索证据。

| Provider | 官网 | 模型原生搜索能力 | API Key | 默认启用 |
| ARK | 火山引擎 Ark | Responses API + 豆包联网搜索 | ARK_API_KEY | 否 |
| Codex Alpha（实验性） | 兼容 Alpha Search 的反代网关 | 模型驱动的 Alpha Search | AGENT_WEB_SEARCH_CODEX_ALPHA_API_KEY | 否 |
| DeepSeek | DeepSeek API | Anthropic Messages API 原生网页搜索 | DEEPSEEK_API_KEY | 否 |
| Gemini | Google AI | Gemini Google Search grounding | GEMINI_API_KEY | 否 |
| Grok | xAI | xAI 网页搜索和 X Search | XAI_API_KEY | 否 |
| Responses | 兼容 Responses API 的网关 | 通用 OpenAI Responses API 网页搜索 | AGENT_WEB_SEARCH_RESPONSES_API_KEY | 否 |
| Messages | 兼容 Messages API 的网关 | 通用 Anthropic Messages API 网页搜索 | AGENT_WEB_SEARCH_MESSAGES_API_KEY | 否 |
| 智谱 Chat Search | 智谱 AI | GLM Chat Completions 原生联网搜索 | ZHIPU_CHAT_SEARCH_API_KEY | 否 |

Agent 搜索提供商

这类 Provider 面向 Agent 提供搜索服务：支持自然语言查询，并返回结构化来源、高信号摘录或适合引用的元数据，而不是传统搜索页面式体验。

| Provider | 官网 | 面向 Agent 的搜索能力 | API Key | 默认启用 |
| Exa | Exa | 语义 Search API 或免费 MCP 后端 | 无 Key 免费 · 可选 EXA_API_KEY | 是 |
| Parallel | Parallel | 面向上下文的搜索 API 或免费 MCP | 无 Key 免费 · 可选 PARALLEL_API_KEY | 是 |
| Brave | Brave Search | 结构化 Web Search API | BRAVE_SEARCH_API_KEY | 否 |
| Perplexity | Perplexity API | 原生结构化 Search API | PERPLEXITY_API_KEY | 否 |
| Tavily | Tavily | 面向 Agent 的 Search API | TAVILY_API_KEY | 否 |
| You.com | You.com API | 统一网页与新闻 Search API | YDC_API_KEY | 否 |
| 智谱 Web Search | 智谱 AI | 独立的结构化 Web Search API | ZHIPU_WEB_SEARCH_API_KEY | 否 |

Provider 架构是开放的：添加新的搜索后端时，不需要修改 MCP、Hermes、CLI 或 Python 接口。

给 Agent 使用

前置要求： 请先完成 安装与快速上手。下文针对各接入形态提供详细的客户端配置与命令参考。

形态一：MCP

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

本地 stdio MCP

先安装一次：

推荐：隔离安装 pipx install agent-web-search-mcp

或安装到当前 Python 环境
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、Claude Code 和 OpenCode 示例

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

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

OpenCode：

{
"$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-domain>/mcp",
"headers": {
"Authorization": "Bearer <your-deployment-token>"
}
}
}
}

所有公网部署都必须设置至少 32 个字符的 AGENT_WEB_SEARCH_AUTH_TOKEN。
服务端无状态，不会创建 MCP-Session-Id。

形态二：CLI + Agent Skill

当 Agent 已经有 Shell 能力并支持 Agent Skills 时，选择这个形态。Skill 会教 Agent 调用 CLI、选择控制参数、理解 results 并处理结构化失败，不需要配置 MCP Server。

1. 安装 CLI：

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

2. 安装仓库内的 agent-web-search Skill：

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 "OpenAI Codex CLI 最新版本有哪些变化？"

CLI 成功时向 stdout 写入一个 JSON 文档。如果所有 Provider 都失败，它会向 stderr 写入统一的 all_providers_failed JSON，并以状态码 1 退出，因此 Agent 可以区分真正的失败和空结果。

| CLI 选项 | MCP 参数 | 取值 | 默认值 |
| 位置参数 QUERY | query | 1–4,000 个字符的自然语言问题 | 必填 |
| --provider（可重复） | providers | 已启用的 Provider 名 | 所有已启用 |
| --max-results | max_results | 1–20 | 5 |
| --time-range | time_range | d、w、m、y | — |
| --grok-search-mode | grok_search_mode | web_search、x_search、both | web_search |

从 GitHub 安装最新开发版本

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

[!IMPORTANT]
不要把 API Key 写入 Shell 历史、源代码、Git 提交、截图或纳入版本控制的 MCP 配置。请通过服务端或本地环境变量提供 Key。

统一请求与响应

MCP 对外注册一个名为 web_search 的工具；CLI 映射到同一组输入。

| 参数 | 类型 | 必填 | 默认值 | 说明 |
| query | string，1–4,000 个字符 | 是 | — | 完整的自然语言搜索问题 |
| max_results | integer，1–20 | 否 | 5 | 期望返回的最大结果数量 |
| time_range | d、w、m、y | 否 | — | 过去一天、一周、一月或一年 |
| providers | string 数组 | 否 | 所有已启用 Provider | 将本次请求限制在指定的已启用 Provider 中 |
| grok_search_mode | web_search、x_search、both | 否 | web_search | 仅在启用 Grok 时可用 |

调用示例：

{
"query": "过去一个月发表了哪些 GPU 内核生成方向的论文？", "max_results": 5, "time_range": "m",
"providers": ["ddgs", "exa"]
}

Provider 选择分为两层：

1. AGENT_WEB_SEARCH_PROVIDERS 决定进程启动时启用哪些 Provider。
2. 请求级 providers 参数可以进一步缩小范围，但不能启用启动时未启用的 Provider。

响应格式

每个成功返回的 Provider 会出现在 providers 字段中；失败的 Provider 会被剔除：

{
"query": "过去一个月发表了哪些 GPU 内核生成方向的论文？",
"providers": {
"ddgs": {
"results": [
{
"title": "Example result",
"url": "https://example.com/paper",
"description": "Excerpt of the matching page",
"published_at": "2026-08-02"
}
]
}
}
}

| 字段 | 含义 |
| answer | 后端生成时返回的文本回答，无则省略该字段 |
| results | 结果行：title、url、description，以及可选的 published_at 和 author |

如果选中的 Provider 全部失败，MCP 会返回工具错误；CLI 则把同一载荷写入 stderr 并以状态码 1 退出。两者都使用稳定错误码 all_providers_failed，并附带各 Provider 的诊断信息：

{
"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": "过去一个月发表了哪些 GPU 内核生成方向的论文？"
}

Python API

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

from agent_web_search import SearchEngine, SearchRequest

engine = SearchEngine() # 构造时读取 AGENT_WEB_SEARCH_* 环境变量

response = engine.search(
SearchRequest(query="MCP 规范最近有哪些变化？", 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 插件启动时会读取环境变量。修改 Provider 设置后需要重启对应进程。仓库内的 .env.example 以注释模板的形式列出了全部变量。

通用设置

| 变量 | 默认值 | 用途 |
| AGENT_WEB_SEARCH_PROVIDERS | ddgs,exa,parallel | 以逗号分隔的启动时启用 Provider 列表 |
| AGENT_WEB_SEARCH_TIMEOUT | 60 | 单次上游 HTTP 调用的 socket 超时。多步 Provider 会成倍放大：keyless Parallel 最多发 3 个请求（最坏 3×），ARK 可能追加续写请求（最坏 2×），因此整次搜索最长可达该值的 3 倍 |

示例：

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 传输设置

| 变量 | 默认值 | 用途 |
| AGENT_WEB_SEARCH_MCP_TRANSPORT | stdio | 可选 stdio 或 http；--transport 可以覆盖它 |
| AGENT_WEB_SEARCH_HTTP_HOST | 0.0.0.0 | 容器部署时的 HTTP 监听地址 |
| AGENT_WEB_SEARCH_HTTP_PORT | PORT 或 8000 | HTTP 监听端口；显式值优先于平台 PORT |
| AGENT_WEB_SEARCH_AUTH_TOKEN | — | HTTP 必需的 Bearer Token，至少 32 个字符 |
| AGENT_WEB_SEARCH_ALLOW_ANONYMOUS | false | 为可信网络或临时 Demo 显式关闭 HTTP 鉴权 |
| AGENT_WEB_SEARCH_HTTP_ALLOWED_HOSTS | — | 可选、逗号分隔的 Host 白名单 |
| AGENT_WEB_SEARCH_HTTP_ALLOWED_ORIGINS | — | 可选、逗号分隔的 Origin 白名单；必须同时配置 Host |
| AGENT_WEB_SEARCH_HTTP_LOG_LEVEL | info | 容器服务器的 Uvicorn 日志级别 |

HTTP 设置仍然全部来自环境变量；部署文件不会引入第二套应用配置格式。

Provider 设置

Provider 的专用设置如下，包含全部 Provider 的凭据和模型参数。上面的支持列表按搜索能力分组；本节是具体配置参考。

1. DDGS

DDGS 使用 DuckDuckGo，不需要 API Key 或 Provider 专用环境变量。包安装时会自动安装 ddgs Python 依赖。

2. Exa

Exa 同时支持付费和免 Key 模式。

| 变量 | 必填 | 用途 |
| EXA_API_KEY | 否 | 设置后使用付费 Search API |
| EXA_MCP_URL | 否 | 未设置 API Key 时覆盖默认免费 MCP 地址 |

未设置 EXA_API_KEY 时，Exa 会尽力通过免费 MCP 端点搜索。付费 API 通常具有更高的配额和可靠性。

3. Parallel

Parallel 返回适合放入 LLM 上下文的信息密集型摘录。统一的 parallel Provider 会自动选择传输方式：

- 未设置 Key 时，使用 Parallel 免费 Search MCP。
- 设置 PARALLEL_API_KEY 后，使用付费 Search REST API。

两种方式都会把 excerpts 映射到统一结果的 description 字段，调用 Agent 无需区分 parallel-free 和 parallel。

| 变量 | 必填 | 用途 |
| PARALLEL_API_KEY | 否 | 启用付费 API；省略时使用免费 MCP |

Parallel 默认启用，Key 为可选项。

4. ARK（推荐）

火山引擎 ARK 通过 Responses API 提供模型驱动的联网搜索。配置 Key 后，将 ark 加入 AGENT_WEB_SEARCH_PROVIDERS。

| 变量 | 必填 | 用途 |
| ARK_API_KEY | 是 | 单个 Key，或用逗号/换行分隔的多个 Key |
| AGENT_WEB_SEARCH_ARK_MODELS | 否 | 用逗号/换行分隔的 ARK 模型 ID；默认 glm-5-2-260617,doubao-seed-2-1-turbo-260628,deepseek-v4-flash-ga-260731 |

只配置一个模型时会固定使用该模型；配置多个模型时，连续请求会轮询选择模型。配置多个 ARK Key 时，每次请求会选择一个 Key。

可选的火山引擎协作奖励计划信息

使用 Agent Web Search 不要求参加奖励计划。ARK 用户可以自行查看官方的火山引擎协作奖励计划。配额、支持模型、有效期和数据授权条款可能变化，请在选择加入前查看官方最新条款。参与计划并不是使用 Agent Web Search 的前提。

5. Brave

| 变量 | 必填 | 用途 |
| BRAVE_SEARCH_API_KEY | 是 | Brave Web Search API 凭据 |

配置 Key 后，将 brave 加入 AGENT_WEB_SEARCH_PROVIDERS。

6. Gemini

| 变量 | 必填 | 用途 |
| GEMINI_API_KEY | 是 | Google AI API 凭据 |
| AGENT_WEB_SEARCH_GEMINI_MODELS | 否 | 用逗号/换行分隔的 Gemini 模型 ID；默认 gemini-3.7-flash |

Gemini 会把通用的结果数量和时间控制尽力转换为 Prompt 约束。只配置一个模型时固定使用该模型；配置多个模型时连续请求会轮询选择模型。

7. Grok

| 变量 | 必填 | 用途 |
| XAI_API_KEY | 是 | xAI API 凭据 |
| AGENT_WEB_SEARCH_GROK_MODELS | 否 | 用逗号/换行分隔的 Grok 模型 ID；默认 grok-4.6 |

只配置一个模型时固定使用该模型；配置多个模型时连续请求会轮询选择模型。

启用 Grok 后，公开工具 Schema 会增加 grok_search_mode：

- web_search 搜索网页。
- x_search 搜索 X，并在可用时采用原生日期过滤器。
- both 在一次请求中同时向服务端暴露这两种工具并让 Grok 选择；它不会发起两个独立的模型请求。

8. Codex Alpha（实验性）

该 Provider 只通过 API key 调用实现 /v1/alpha/search 的兼容网关；网关内部使用的 OAuth 不属于本项目的认证方式。配置完整 endpoint（Provider 不会自动拼接路径）、key 和可选模型后，将 codex_alpha 加入 AGENT_WEB_SEARCH_PROVIDERS：

| 变量 | 必填 | 用途 |
| AGENT_WEB_SEARCH_CODEX_ALPHA_ENDPOINT | 是 | 完整 Alpha Search endpoint URL |
| AGENT_WEB_SEARCH_CODEX_ALPHA_API_KEY | 是 | 网关 Bearer API key |
| AGENT_WEB_SEARCH_CODEX_ALPHA_MODEL | 否 | 模型 ID，默认 gpt-5.6-luna |

该 Provider 只发送普通的 search_query 命令并返回标准网页搜索结果。

9. DeepSeek

DeepSeek 使用官方 Anthropic 兼容 Messages API 和原生 web_search_20250305 服务端工具。Provider 会保留模型最终生成的文本，只把明确出现的 web_search_result 结果块映射为统一结果。因此，响应可以只有 answer，而 results 为空。

| 变量 | 必填 | 用途 |
| DEEPSEEK_API_KEY | 是 | DeepSeek API 凭据 |
| AGENT_WEB_SEARCH_DEEPSEEK_BASE_URL | 否 | Anthropic API 基础地址，默认 https://api.deepseek.com/anthropic |
| AGENT_WEB_SEARCH_DEEPSEEK_MODELS | 否 | 用逗号或换行分隔的模型 ID，默认 deepseek-v4-flash |

配置 Key 后，将 deepseek 加入 AGENT_WEB_SEARCH_PROVIDERS。Provider 会在配置的基础地址后追加 /v1/messages。配置多个模型时，连续请求会轮询选择模型。

10. Perplexity

该 Provider 使用 Perplexity 原生的结构化 Search API，返回搜索结果行，而不是由 Sonar 生成的文本回答。该 Provider 不包含 OpenRouter 兼容逻辑。

| 变量 | 必填 | 用途 |
| PERPLEXITY_API_KEY | 是 | Perplexity Search API 凭据 |

配置 Key 后，将 perplexity 加入 AGENT_WEB_SEARCH_PROVIDERS。

11. Tavily

| 变量 | 必填 | 用途 |
| TAVILY_API_KEY | 是 | Tavily Search API 凭据 |

配置 Key 后，将 tavily 加入 AGENT_WEB_SEARCH_PROVIDERS。

12. You.com

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

| 变量 | 必填 | 用途 |
| YDC_API_KEY | 是 | You.com Search API 凭据 |

配置 Key 后，将 you 加入 AGENT_WEB_SEARCH_PROVIDERS。

13. 智谱 Web Search

智谱 Web Search 使用中国区独立的 Web Search API，返回结构化搜索结果。它与智谱 Chat Search 是两个独立 Provider，二者之间不会互相 fallback。

| 变量 | 必填 | 用途 |
| ZHIPU_WEB_SEARCH_API_KEY | 是 | 智谱 Web Search API 凭据 |
| AGENT_WEB_SEARCH_ZHIPU_WEB_SEARCH_BASE_URL | 否 | 中国区 API 基础地址，默认 https://open.bigmodel.cn |

配置 Key 后，将 zhipu_web_search 加入 AGENT_WEB_SEARCH_PROVIDERS。Provider 会在基础地址后追加 /api/paas/v4/web_search。

14. 智谱 Chat Search

智谱 Chat Search 使用中国区 GLM Chat Completions API 的原生联网搜索能力。它返回模型回答和明确的顶层搜索结果；回答正文中提到的 URL 不会被猜测成引用。它与智谱 Web Search 是两个独立 Provider，不存在 API/Chat fallback。

| 变量 | 必填 | 用途 |
| ZHIPU_CHAT_SEARCH_API_KEY | 是 | 智谱 Chat Search API 凭据 |
| AGENT_WEB_SEARCH_ZHIPU_CHAT_BASE_URL | 否 | 中国区 API 基础地址，默认 https://open.bigmodel.cn |
| AGENT_WEB_SEARCH_ZHIPU_CHAT_MODELS | 否 | 用逗号/换行分隔的 GLM 模型 ID，默认 glm-5.3-flash |

配置 Key 后，将 zhipu_chat_search 加入 AGENT_WEB_SEARCH_PROVIDERS。Provider 会在基础地址后追加 /api/paas/v4/chat/completions。配置多个模型时，连续请求会轮询选择模型。

15. Responses

Responses 是通用 OpenAI Responses API 客户端，适用于在 POST {base_url}/responses 暴露服务端网页搜索工具的网关。它遍历 output 数组（不假设 output[0] 即为结果），将 web_search_call 的 action sources 和 url_citation 引用统一为标准结果，并保留模型生成的回答。只有 message 而没有任何 URL 的响应会保留回答、返回空 results，并将 searched 标记为 false。

| 变量 | 必填 | 用途 |
| AGENT_WEB_SEARCH_RESPONSES_BASE_URL | 否 | 基础地址；默认 https://api.openai.com/v1。无 /v1 后缀时追加 /v1/responses，否则追加 /responses |
| AGENT_WEB_SEARCH_RESPONSES_API_KEY | 是 | Bearer 凭据；可回退到 OPENAI_API_KEY |
| AGENT_WEB_SEARCH_RESPONSES_MODELS | 否 | 用逗号/换行分隔的模型 ID，默认 gpt-5-mini |
| AGENT_WEB_SEARCH_RESPONSES_TOOL_TYPE | 否 | 搜索工具类型，默认 web_search |
| AGENT_WEB_SEARCH_RESPONSES_TIMEOUT | 否 | 单次请求超时（秒）；设置后覆盖 AGENT_WEB_SEARCH_TIMEOUT |

配置 Key 后，将 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。

| 变量 | 必填 | 用途 |
| AGENT_WEB_SEARCH_MESSAGES_BASE_URL | 否 | 基础地址；默认 https://api.anthropic.com，会自动追加 /v1/messages |
| AGENT_WEB_SEARCH_MESSAGES_ENDPOINT | 否 | 完整 endpoint 覆盖；优先级高于基础地址 |
| AGENT_WEB_SEARCH_MESSAGES_API_KEY | 是 | x-api-key 凭据 |
| AGENT_WEB_SEARCH_MESSAGES_MODELS | 否 | 用逗号/换行分隔的模型 ID，默认 claude-3-7-sonnet-20250219,claude-3-5-haiku-20241022 |
| AGENT_WEB_SEARCH_MESSAGES_TOOL_TYPE | 否 | 搜索工具类型，默认 web_search_20250305 |
| AGENT_WEB_SEARCH_MESSAGES_TOOL_NAME | 否 | 搜索工具名称，默认 web_search |
| AGENT_WEB_SEARCH_MESSAGES_TIMEOUT | 否 | 单次请求超时（秒）；设置后覆盖 AGENT_WEB_SEARCH_TIMEOUT |

配置 Key 后，将 messages 加入 AGENT_WEB_SEARCH_PROVIDERS。配置多个模型时，连续请求会轮询选择模型。

通用搜索控制

每个 Provider 会尽可能将公共控制参数映射到原生 API，不支持的参数会被忽略。

| Provider | max_results | time_range |
| DDGS | 原生 max_results | 原生 timelimit |
| Exa | 原生结果数量 | 原生发布日期 |
| Parallel | REST：原生 max_results；keyless MCP：客户端截断（results[:max_results]） | 忽略 |
| ARK | 原生 limit | Prompt 约束 |
| Brave | 原生 count | 原生 freshness |
| Gemini | Prompt 约束 | Prompt 约束 |
| Grok | Prompt 约束 | Prompt；X Search 还会使用原生日期参数 |
| Codex Alpha | 本地结果截断 | 忽略 |
| DeepSeek | 本地搜索结果截断 | Prompt 约束 |
| Messages | 本地去重并截断 | Prompt 约束 |
| Perplexity | 原生 max_results | 原生时间范围过滤 |
| Tavily | 原生 max_results | 原生 time_range |
| You.com | 原生 count，合并后截断 | 原生 freshness |
| 智谱 Web Search | 原生 count，本地去重并截断 | 原生时间范围过滤 |
| 智谱 Chat Search | 原生 count，本地去重并截断 | 原生时间范围过滤 |
| Responses | 本地去重并截断 | Prompt 约束 |

基于 Prompt 的控制属于尽力而为，不是严格保证。

其他接口

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 会话；通过消息渠道使用时还需要重启 gateway。

Hermes 也可以不安装原生插件，而是通过通用 MCP 集成连接本项目。

DeepSeek Harness 原生插件

直接从 GitHub 安装原生插件（桌面版和 CLI 版 profile 都一样 —— 桌面版自带 dsh plugin 命令，无需手动放置文件）：

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

该插件会有意替换 DSH 原生 web_search seam 背后的实现 —— 保持同一个模型可见工具名、提示词、规范化来源和引用卡片；不会暴露 mcp__...__web_search 工具。请把 agent-web-search-mcp Python 命令安装在 DSH 所用的同一环境中，装完重启 DSH。桥接层把内置 Provider 委托给该命令，同时保留 DSH 原生设置、历史与诊断。完整步骤和一段可直接粘贴的安装 prompt 见 integrations/dsh/docs/INSTALL.md。

DSH 也可以不装原生插件，而是用自带的 MCP 客户端连接本项目。

故障排查

- all_providers_failed —— 所有 Provider 都失败了。MCP 会标记工具错误；CLI 会把诊断写入 stderr 并退出 1。请检查 Key、配额和网络；临时限流可以有界重试一次。
- 找不到 agent-web-search —— 使用 pipx 或 pip 安装 PyPI 包，然后重新打开 Shell，确保脚本目录已经加入 PATH。
- HTTP 401 invalid_token —— Authorization: Bearer … 请求头必须与 AGENT_WEB_SEARCH_AUTH_TOKEN 一致，且该 Token 至少 32 个字符。
- 响应里少了某个 Provider —— 失败的 Provider 会从成功响应中剔除。Python API 可以通过 response.failed_provider_errors 查看原因。
- 修改 Provider 配置不生效 —— Provider 设置只在进程启动时读取一次；修改后请重启 CLI、MCP 服务器或 Hermes 插件。
- MCP 客户端在工具返回前超时 —— AGENT_WEB_SEARCH_TIMEOUT 限定的是单次上游 HTTP 调用的超时，不是整次搜索。keyless Parallel 最多发 3 个请求，ARK 可能追加续写请求，最坏总耗时是其 3 倍；请据此设置 MCP 客户端的 tool 超时。

常见问题

Agent Web Search 是什么？

Agent Web Search 是面向 AI Agent 的开源联网搜索层。它通过 MCP 服务器（stdio 或 Streamable HTTP）、CLI 和 Python API 暴露同一个 web_search 工具。工具背后并发调用模型原生搜索 grounding（ARK、Gemini、Grok、DeepSeek、智谱 Chat Search、 Codex Alpha（实验性）以及通用 Responses/Messages 网关）、Agent 搜索 API（Exa、Parallel、Brave、 Perplexity、Tavily、You.com、智谱 Web Search），并以 DuckDuckGo 作为传统搜索兜底，最终返回统一格式的 JSON。

有没有不需要 API Key 的免费联网搜索 MCP？

有。默认 Provider 组合 DDGS、Exa、Parallel 都不需要 API Key。在设置 EXA_API_KEY 或 PARALLEL_API_KEY 之前，Exa 和 Parallel 会尽力使用各自的免费 MCP 端点。付费 Provider 需要通过 AGENT_WEB_SEARCH_PROVIDERS 显式启用。

它和 Google/Bing 元搜索类 MCP 有什么区别？

元搜索服务器抓取传统搜索结果页再合并。Agent Web Search 聚合的是面向 Agent 的搜索服务，其中模型原生 grounding 会返回带引用的综合 answer。
与 open-webSearch 的对比基准 记录了这种差异及其前提：从数据中心 IP 抓取 SERP 经常被反爬拦截，而基于 API 的 Provider 只会返回更少结果，不会完全为空。

支持哪些 Agent 和客户端？

任何支持 stdio 或 Streamable HTTP 的 MCP 客户端，包括 Codex CLI、Claude Code、 OpenCode、Cursor、Cline 和 Claude Desktop。Hermes 有原生插件。具备 Shell 能力的 Agent 也可以不用 MCP，而是通过 CLI 加内置 Agent Skill 使用。

应该用 MCP 还是 CLI + Skill？

客户端支持工具服务器、需要类型化工具发现、协议级错误或远程部署时，用 MCP。
Agent 已有 Shell 且支持 Agent Skills 时，用 CLI + Skill，无需任何 MCP 配置。
两者返回的响应格式相同。

能否接入自己的 OpenAI 或 Anthropic 兼容网关做搜索 grounding？

可以。responses Provider 可调用任何带服务端联网搜索工具的 OpenAI Responses API 网关，messages Provider 对 Anthropic Messages API 网关做同样的事。Base URL、Key 和模型通过 Provider 设置 中的环境变量配置。

能否部署为远程 MCP 服务器？

可以。agent-web-search-mcp --transport http 在 POST /mcp 提供无状态 Streamable HTTP 服务，并默认启用 Bearer Token 认证。仓库提供 Vercel、Railway、 Render、Zeabur 一键部署模板和 Dockerfile。

会收集遥测数据或保存我的 API Key 吗？

不会。项目没有遥测，也没有共享 Key 服务。Provider 凭据只从执行搜索的本机或服务器环境变量读取，不会作为工具参数传入。

开发

使用 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 .

标准 venv + pip 方式

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 列出了不可妥协的约束。在修改 Transport、配置、鉴权、部署、Provider 或工具 Schema 之前，请先阅读这两份文档，保持 stdio 与 HTTP 行为一致，并在同一改动中保持 pytest 和 ruff 通过。

许可证

MIT