Agent Web Search

面向 AI 智能体的多提供商网络搜索。

Agent Web Search 为 Hermes、Codex CLI、Claude Code、OpenCode 以及普通脚本提供一致的网络搜索工具。它并发运行独立的提供商，并返回标准化结果。默认提供商集合为：

• ARK grounding — Volcengine ARK Responses API + web_search（豆包）

• DDGS — DuckDuckGo 搜索

• Exa — Exa MCP 搜索（尽力而为；可用性取决于端点）

还实现了可选的提供商：

• Gemini — 通过 Gemini Interactions API 进行 Google 搜索 grounding

• Grok — xAI Responses API，支持原生网络搜索和 X 搜索

• Tavily — Tavily 搜索 API，支持原生结果数量和时域筛选

架构基于提供商，因此无需更改 MCP 或 Hermes 接口即可添加 DeepSeek、Brave 和其他支持搜索的提供商。

快速开始

# Omit this line when the ARK provider is not enabled.
export ARK_API_KEY="your_ark_api_key"
pipx install 'git+https://github.com/JerryLiu369/agent-web-search.git'
agent-web-search-mcp

不要将 API 密钥放在 shell 历史、源代码、Git 提交或屏幕截图中。使用本地 .env/密钥管理器，并在进程环境中导出该变量。

Related MCP server: GroundRoute

从 Codex CLI 使用

export ARK_API_KEY="your_ark_api_key"
codex mcp add agent-web-search -- \
  agent-web-search-mcp
codex mcp list

从 Claude Code 使用

export ARK_API_KEY="your_ark_api_key"
claude mcp add agent-web-search -- \
  agent-web-search-mcp

或添加项目 .mcp.json：

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

从 OpenCode 使用

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

从 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

该插件注册标准的 web_search 工具，并调用与 MCP 和 CLI 相同的 Agent Web Search 核心。如果您更喜欢通用的 MCP 路径，Hermes 也可以使用 hermes mcp add 连接。

GitHub 安装程序会安装该包及其可选依赖项：

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

Hermes 需要显式的 --allow-tool-override 授权，因为此插件有意替换其内置的 web_search 工具。启用后启动新的 Hermes 会话；如果您使用消息通道，请重启网关。

CLI

agent-web-search "What changed in the latest OpenAI Codex CLI?"
agent-web-search "GPU kernel generation papers from the past month" --time-range m --max-results 5
agent-web-search "latest news" --provider ark --provider ddgs

Volcengine 协作奖励

Agent Web Search 不要求参与任何奖励计划。选择使用 ARK 的用户可以创建自己的 API 密钥，并可选查看官方 Volcengine 协作奖励计划。该计划可能根据其当前规则提供奖励资源，但配额、支持的模型、有效期和数据授权条款可能发生变化。在加入前请查看官方页面。参与即表示接受提供商的数据授权条款；这不是使用 Agent Web Search 所必需的。

配置

• ARK_API_KEY：可选；仅在启用 ARK 提供商时需要。接受逗号/换行分隔的密钥。

• AGENT_WEB_SEARCH_PROVIDERS：启动时启用的提供商集合；默认为 ark,ddgs,exa。

• AGENT_WEB_SEARCH_TIMEOUT：每个提供商的超时时间（秒）（默认 60）。

• AGENT_WEB_SEARCH_ARK_MODELS：逗号分隔的 ARK 模型 ID。

• EXA_MCP_URL：可选的 Exa MCP 端点覆盖。

• GEMINI_API_KEY：可选的 Gemini 提供商密钥。

• AGENT_WEB_SEARCH_GEMINI_MODEL：可选的 Gemini 模型 ID。

• XAI_API_KEY：可选的 Grok 提供商密钥。

• AGENT_WEB_SEARCH_GROK_MODEL：可选的 Grok 模型 ID。

• TAVILY_API_KEY：可选的 Tavily 提供商密钥。

提供商集合在 Hermes 插件或 MCP 服务器启动时解析。公共 web_search 模式从该集合生成。请求可以使用 providers 缩小集合，但无法激活在启动时禁用的提供商。如果 grok 在启动时启用，则模式还会额外暴露 grok_search_mode，其值为 web_search、x_search 和 both。both 在一次请求中传递 xAI 服务器端的两个工具，并让 Grok 决定调用哪个；它不会发送两个独立的请求。

通用搜索控制

公共接口保持一组与提供商无关的控制。每个后端在可能的情况下将其映射到其原生 API，并静默忽略不支持的控制：

提示约束对于基于模型的提供商是尽力而为的；它们不被视为严格保证。

设计原则

• 一个核心，多个适配器。

• 失败的提供商不会丢弃成功的提供商。

• 提供商响应标记为 searched、error 和 model，而不是假装每个 HTTP 200 都是成功的搜索。

• 无遥测，无共享 API 密钥服务。

开发

python -m venv .venv
. .venv/bin/activate
pip install -e '.[dev,ddgs,mcp]'
pytest -q
ruff check .

许可证

MIT。