Agent Web Search

Мульти-провайдерный веб-поиск для ИИ-агентов.

Agent Web Search предоставляет Hermes, Codex CLI, Claude Code, OpenCode и обычным скриптам единый инструмент веб-поиска. Он запускает независимых провайдеров параллельно и возвращает нормализованные результаты. Набор провайдеров по умолчанию:

• ARK grounding — Volcengine ARK Responses API + web_search (Doubao)

• DDGS — поиск DuckDuckGo

• Exa — поиск Exa MCP (по возможности; доступность зависит от конечной точки)

Также реализованы дополнительные провайдеры:

• Gemini — привязка к Google Search через Gemini Interactions API

• Grok — xAI Responses API с нативным веб-поиском и X Search

• Tavily — Tavily Search API с нативными фильтрами по количеству результатов и временному диапазону

Архитектура основана на провайдерах, поэтому DeepSeek, Brave и другие провайдеры с поддержкой поиска могут быть добавлены без изменения интерфейсов MCP или Hermes.

Quick start

# 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-ключи в историю оболочки, исходный код, Git-коммиты или скриншоты. Используйте локальный .env/менеджер секретов и экспортируйте переменную в окружение процесса.

Related MCP server: GroundRoute

Use from Codex CLI

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

Use from 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}"}
    }
  }
}

Use from 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
    }
  }
}

Use from 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 и вызывает то же ядро Agent Web Search, которое используется в MCP и CLI. Если вы предпочитаете универсальный путь 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 collaboration rewards

Agent Web Search не требует участия в каких-либо программах вознаграждений. Пользователи, которые решат использовать ARK, могут создать собственный API-ключ и при желании ознакомиться с официальной программой вознаграждений Volcengine Collaboration. Программа может предоставлять вознаграждения в соответствии с её текущими правилами, но квота, поддерживаемые модели, срок действия и условия авторизации данных могут меняться. Проверьте официальную страницу перед участием. Участие означает принятие условий авторизации данных провайдера; оно не требуется для использования Agent Web Search.

Configuration

• ARK_API_KEY: необязательный; требуется только при включённом провайдере ARK. Принимаются ключи, разделённые запятыми/переводами строк.

• AGENT_WEB_SEARCH_PROVIDERS: набор провайдеров, включённых при запуске; по умолчанию ark,ddgs,exa.

• AGENT_WEB_SEARCH_TIMEOUT: таймаут на провайдера в секундах (по умолчанию 60).

• AGENT_WEB_SEARCH_ARK_MODELS: идентификаторы моделей ARK через запятую.

• EXA_MCP_URL: необязательное переопределение конечной точки Exa MCP.

• GEMINI_API_KEY: необязательный ключ провайдера Gemini.

• AGENT_WEB_SEARCH_GEMINI_MODEL: необязательный идентификатор модели Gemini.

• XAI_API_KEY: необязательный ключ провайдера Grok.

• AGENT_WEB_SEARCH_GROK_MODEL: необязательный идентификатор модели Grok.

• TAVILY_API_KEY: необязательный ключ провайдера Tavily.

Набор провайдеров определяется при запуске плагина Hermes или MCP-сервера. Публичная схема web_search генерируется из этого набора. Запрос может сузить набор с помощью providers, но не может активировать провайдера, который был отключён при запуске. Если grok включён при запуске, схема дополнительно предоставляет grok_search_mode со значениями web_search, x_search и both. both передаёт оба серверных инструмента xAI в одном запросе и позволяет Grok решить, какой вызвать; он не отправляет два независимых запроса.

Common search controls

Публичный интерфейс сохраняет единый набор элементов управления, не зависящий от провайдера. Каждый бэкенд сопоставляет их со своим нативным API, когда это возможно, и молча игнорирует неподдерживаемые элементы управления:

Промпт-ограничения являются best-effort для провайдеров на основе моделей; они не представлены как строгие гарантии.

Design principles

• Одно ядро, несколько адаптеров.

• Неудачный провайдер не отбрасывает успешных провайдеров.

• Ответы провайдеров помечаются как searched, error и model вместо того, чтобы считать каждый HTTP 200 успешным поиском.

• Никакой телеметрии и никакого общего сервиса API-ключей.

Development

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

License

MIT.