Веб-поиск и извлечение контента

Команды для Python-зависимостей на этой странице рассчитаны на checkout исходников, подготовленный через PM. После изменения зависимостей заново активируйте checkout и перезапустите Hermes.

В Hermes Agent встроены два веб-инструмента, которые умеет вызывать модель; за ними стоит выбор из нескольких провайдеров:

• web_search — ищет в интернете и возвращает ранжированные результаты
• web_extract — забирает одну или несколько страниц по URL и вытягивает из них читаемый контент

Настраиваются оба через единый выбор бэкенда. Провайдера выбираете либо командой hermes tools, либо напрямую в config.yaml.

Бэкенды

Brave Search, DDGS, xAI и OpenAI Native работают только на поиск — если нужен ещё и web_extract, добавьте к любому из них Firecrawl/Tavily/Perplexity/Keenable/Exa/Parallel. Под капотом DDGS опирается на Python-пакет ddgs; если он ещё не установлен, выполните python -c "import pm; pm.sync_venv(['ddgs'], explicit=True)" (или дайте Hermes доустановить его при первом обращении). xAI запускает серверный инструмент web_search от Grok на Responses API — результаты генерирует LLM, а не поисковый индекс, поэтому заголовки, описания и сам выбор URL целиком приходят от модели (см. оговорку про модель доверия ниже). OpenAI Native объявляет такой же исполняемый на стороне провайдера инструмент на эндпоинте Codex Responses (см. ниже).

Разделение по возможностям: для поиска и извлечения можно задать разных провайдеров независимо друг от друга — например, SearXNG (бесплатно) для поиска и Firecrawl для извлечения. Подробности — в разделе Настройка по возможностям ниже.

Как явно выбрать бесплатный или платный путь: в hermes tools Exa, Parallel и Keenable показаны двумя строками каждый — Free (keyless) и Paid (API key). Выбор Free закрепляет анонимный endpoint вендора (даже если позже вы добавите ключ), выбор Paid — путь с ключом (и тогда отсутствие ключа даст ошибку, а не тихий откат на бесплатный тариф). Выбор сохраняется как web.provider_tier.<name>: free|paid; оставьте пустым — сработает автоопределение (ключ есть → платный путь, иначе бесключевое кольцо).

---

Как web_extract справляется с длинными страницами

Бэкенды возвращают сырой markdown страницы, а он бывает огромным — ветки форумов, документация, новости с километрами комментариев. Чтобы окно контекста оставалось рабочим, web_extract применяет детерминированный лимит по символам; никакой суммаризации через LLM тут нет:

Лимит на страницу настраивается через web.extract_char_limit в config.yaml (по умолчанию 15000, зажат в границах 2 000–500 000), а агент может поднять его на конкретный вызов аргументом char_limit.

Каждая отправка провайдеру ограничена и по времени (web.extract_timeout в config.yaml, по умолчанию 120 секунд; 0 отключает). Бэкенд, который держит ответ открытым и не заканчивает, получает ошибки таймаута по каждому URL, вместо того чтобы подвешивать вызов инструмента навсегда.

Когда обрезка мешает

Если вам нужен именно живой DOM, а не извлечённый markdown — скажем, страница на тяжёлом JS, с которой извлечение приносит крохи, — берите browser_navigate + browser_snapshot. Браузерный инструмент отдаёт живое дерево доступности (на гигантских страницах действует его собственный лимит снимка).

---

Кэширование результатов

Повторные веб-вызовы в течение короткого окна отдаются из кэша вместо обращения к платному бэкенду — это экономит кредиты и время в двух сценариях, где дубли неизбежны: разветвление на субагентов (несколько делегированных агентов копают одну и ту же тему) и повторная проверка агентом страницы, которую он читал пару минут назад.

Одинаковые параллельные поисковые запросы (например, когда субагенты одновременно бьют один и тот же запрос) схлопываются в один запрос к бэкенду — платит первый вызвавший, остальные получают тот же ответ. Запрошенные лимиты поиска округляются вверх до 10/20/50/100, так что почти одинаковые запросы (limit=5 и limit=8) используют одну запись кэша, а каждый вызывающий получает именно тот объём, который запросил.

В кэш попадают только успешные ответы — каждый под тем запрошенным URL, который провайдер для него сообщает (страница, которую провайдер вернул, не назвав запрошенный URL, отдаётся, но не кэшируется, так что частичный или переупорядоченный пакет никогда не положит одну страницу под ключ другого URL). Ошибки всегда идут в бэкенд заново, ответы от разового бесключевого спасения в кэш не попадают (следующий вызов снова пробует ваш выбранный бэкенд), а URL, подпадающие под security.website_blocklist, из кэша не отдаются никогда. Закэшированные извлечения заново проходят через обычный конвейер обрезки — так что другой char_limit при повторном вызове работает с тем же сохранённым скрейпом.

Локальные адреса для разработки в кэш никогда не попадают. Всё, что крутится на localhost, 127.0.0.1, *.local, однословных именах в локальной сети или в приватных/link-local диапазонах IP (192.168.*, 10.*, 172.16-31.*), полностью обходит кэш извлечения — дев-серверы, сборки с hot-reload и превью артефактов в чат-GUI меняются при каждом сохранении, и закэшированная копия показала бы устаревшую сборку. Каждое обращение к локальной странице идёт вживую. (Такие адреса вообще доступны, только когда включён security.allow_private_urls.)

Тестируете через публичный интернет? Стейджинг-деплои и туннельные URL — это публичный DNS, правило про локальную разработку их не ловит: перечислите их в web.cache_exempt_hosts, и они тоже всегда будут забираться вживую. Совпадение точное, по маске *. или по суффиксу домена (mysite.dev покрывает и preview.mysite.dev):

# ~/.hermes/config.yaml
web:
  cache_exempt_hosts:
    - mysite.vercel.app
    - "*.ngrok-free.app"

# ~/.hermes/config.yaml
web:
  cache_enabled: true      # по умолчанию; false — отключить оба кэша
  cache_ttl_minutes: 20    # окно свежести, зажато в границах 1–1440

Если исследуете действительно живые данные (счёт матча, цены, breaking news) и нужен каждый вызов свежим — снизьте TTL или выставьте web.cache_enabled: false.

---

Настройка

Быстрая настройка через hermes tools

Запустите hermes tools, перейдите в Web Search & Extract и выберите провайдера. Мастер спросит нужный URL или API-ключ и сам запишет его в конфиг.

hermes tools

---

Firecrawl (по умолчанию)

Полнофункциональные поиск и извлечение. Подойдёт большинству пользователей.

# ~/.hermes/.env
FIRECRAWL_API_KEY=fc-your-key-here

Ключ получите на firecrawl.dev. Бесплатный тариф — 500 кредитов в месяц.

Self-hosted Firecrawl: вместо облачного API можно указать свой инстанс:

# ~/.hermes/.env
FIRECRAWL_API_URL=http://localhost:3002

Когда задан FIRECRAWL_API_URL, API-ключ необязателен (серверную авторизацию отключают через USE_DB_AUTHENTICATION=false).

---

SearXNG (бесплатно, self-hosted)

SearXNG — это уважающий приватность open-source-метапоисковик, который собирает результаты из 70+ поисковых систем. API-ключ не нужен — просто направьте Hermes на работающий инстанс SearXNG.

SearXNG работает только на поиск — для web_extract понадобится отдельный провайдер извлечения.

Вариант A — Self-host через Docker (рекомендуется)

Так вы получаете приватный инстанс без лимитов на частоту запросов.

1. Создайте рабочую директорию:

mkdir -p ~/searxng/searxng
cd ~/searxng

2. Напишите docker-compose.yml:

# ~/searxng/docker-compose.yml
services:
  searxng:
    image: searxng/searxng:latest
    container_name: searxng
    ports:
      - "8888:8080"
    volumes:
      - ./searxng:/etc/searxng:rw
    environment:
      - SEARXNG_BASE_URL=http://localhost:8888/
    restart: unless-stopped

3. Запустите контейнер:

docker compose up -d

4. Включите формат JSON API:

По умолчанию вывод в JSON у SearXNG выключен. Скопируйте сгенерированный конфиг и включите его:

# Скопировать автогенерируемый конфиг из контейнера
docker cp searxng:/etc/searxng/settings.yml ~/searxng/searxng/settings.yml

Откройте ~/searxng/searxng/settings.yml. Если там есть use_default_settings: true, файл содержит только ваши переопределения — всё остальное наследуется из встроенных умолчаний. Чтобы включить ответы в JSON для Hermes, добавьте такое переопределение:

search:
  formats:
    - html
    - json

Ваш settings.yml должен выглядеть примерно так:

# Read the documentation before extending the defaults:
# https://docs.searxng.org/admin/settings/

use_default_settings: true

server:
  secret_key: "abcdef12345678"
  image_proxy: true

search:
  formats:
    - html
    - json

5. Перезапустите, чтобы применить:

docker cp ~/searxng/searxng/settings.yml searxng:/etc/searxng/settings.yml
docker restart searxng

6. Проверьте, что всё работает:

curl -s "http://localhost:8888/search?q=test&format=json" | python3 -c \
  "import sys,json; d=json.load(sys.stdin); print(f'{len(d[\"results\"])} results')"

В ответ должно прийти что-то вроде 10 results. Если получаете 403 Forbidden, формат JSON всё ещё выключен — перепроверьте шаг 4.

7. Настройте Hermes:

# ~/.hermes/.env
SEARXNG_URL=http://localhost:8888

Затем выберите SearXNG как бэкенд поиска в ~/.hermes/config.yaml:

web:
  search_backend: "searxng"

Или через hermes tools → Web Search & Extract → SearXNG.

---

Вариант B — Публичный инстанс

Публичные инстансы SearXNG перечислены на searx.space. Отфильтруйте те, где включён формат JSON (показано в таблице).

# ~/.hermes/.env
SEARXNG_URL=https://searx.example.com

---

Сочетание SearXNG с провайдером извлечения

SearXNG отвечает за поиск; для web_extract нужен отдельный провайдер. Задайте ключи по возможностям:

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"
  extract_backend: "firecrawl"   # или tavily, perplexity, keenable, exa, parallel

С такой конфигурацией Hermes гоняет все поисковые запросы через SearXNG, а извлечение URL — через Firecrawl, совмещая бесплатный поиск с качественным извлечением.

---

Tavily

ИИ-оптимизированные поиск и извлечение. Выберите Tavily в hermes tools (или задайте web.backend: tavily), чтобы работать без ключа и без аккаунта (с ограничением частоты запросов). Задайте API-ключ, если нужны более высокие лимиты.

# необязательно — при бесключевом доступе после выбора Tavily этот шаг можно пропустить
# ~/.hermes/.env
TAVILY_API_KEY=tvly-your-key-here

Ключ получите на app.tavily.com. Подробности — в Tavily keyless.

---

Perplexity

Search API от Perplexity возвращает ранжированную выдачу с датами из собственного индекса Perplexity (web_search). Для web_extract используется тот же маршрут релевантных запросу фрагментов, что и в официальном CLI pplx: вы получаете те куски страницы, которые относятся к делу, с пропусками, помеченными …, а не дословный дамп страницы целиком — когда нужна вся страница, ставьте в web.extract_backend Firecrawl, Exa или Parallel. По ключу работает только у самого Perplexity; управляемый маршрут Nous (любая идентичность Nous, включая гостей) отдаёт web_search без ключа.

# ~/.hermes/.env
PERPLEXITY_API_KEY=pplx-your-key-here

Ключ получите на perplexity.ai/account/api. Переменная PERPLEXITY_BASE_URL пустит запросы через прокси.

---

Exa

Нейропоиск с семантическим пониманием запроса. Хорош для ресёрча и подбора концептуально близкого контента.

# ~/.hermes/.env
EXA_API_KEY=your-exa-key-here

Ключ получите на exa.ai. Бесплатный тариф — 1 000 поисков в месяц.

---

Parallel

ИИ-нативный поиск и извлечение с возможностями глубокого ресёрча.

# ~/.hermes/.env
PARALLEL_API_KEY=your-parallel-key-here

Доступ оформляется на parallel.ai.

---

xAI (Grok)

Прогоняет web_search через серверный инструмент web_search от Grok на Responses API. Сам поиск выполняет Grok и возвращает топ результатов в виде структурированного JSON.

Работает с любым способом аутентификации — без новых переменных окружения и без отдельного мастера настройки:

# ~/.hermes/.env (через переменную окружения)
XAI_API_KEY=sk-xai-your-key-here

или для подписчиков SuperGrok:

hermes auth add xai-oauth

Затем выберите xAI как бэкенд поиска:

# ~/.hermes/config.yaml
web:
  backend: "xai"

Необязательные параметры:

web:
  backend: "xai"
  xai:
    model: grok-build-0.1        # reasoning-модель, нужная для web_search (по умолчанию)
    allowed_domains:             # необязательно, максимум 5 — взаимоисключающе с excluded_domains
      - arxiv.org
    excluded_domains:            # необязательно, максимум 5
      - example-spam.com
    timeout: 90                  # секунды (по умолчанию)

Только поиск — для web_extract добавьте Firecrawl / Tavily / Keenable / Exa / Parallel. При ответе 401 провайдер один раз принудительно обновляет OAuth-токен и повторяет запрос (это закрывает отзыв токена посреди окна и непрозрачные токены, которые упреждающая проверка срока не может разобрать); для учётных данных из переменной окружения повтор пропускается.

OpenAI Native (Codex Responses)

Объявляет исполняемый на стороне провайдера инструмент OpenAI web_search на эндпоинте Codex Responses (подписки ChatGPT/Codex). Поиском модель управляет на сервере и вплетает результаты в собственный ответ — клиентский поиск Hermes в этом режиме не запускает никогда.

# ~/.hermes/config.yaml
web:
  search_backend: "openai-native"

Требования и границы:

• Учётные данные: OAuth-вход openai-codex (hermes auth add openai-codex). Своего API-ключа у этого бэкенда нет; без входа он просто недоступен.
• Транспорт: встроенный инструмент есть только у эндпоинта Codex Responses. На любом другом транспорте — пользовательском OpenAI-совместимом base_url или модели не от OpenAI — клиентская функция web_search остаётся как есть, потому что нельзя рассчитывать, что эндпоинт предоставит этот инструмент. Для таких случаев укажите в web.search_backend обычного провайдера.
• Только поиск: встроенный инструмент покрывает поиск, но не извлечение. Если нужен ещё и web_extract, добавьте Firecrawl (или другой бэкенд с извлечением) через web.extract_backend.

В любом случае инструмент один. Выбор этого бэкенда заменяет клиентскую функцию web_search встроенным инструментом один к одному — это не дополнительное разрешение. Сессия, в наборе инструментов которой нет web_search, серверный поиск не получит никогда.

---

Конфигурация

Один бэкенд

Задайте одного провайдера на все веб-возможности:

# ~/.hermes/config.yaml
web:
  backend: "searxng"   # firecrawl | searxng | brave-free | ddgs | tavily | perplexity | keenable | exa | parallel | xai

Настройка по возможностям

Можно использовать разных провайдеров для поиска и для извлечения. Так удобно совмещать бесплатный поиск (SearXNG) с платным провайдером извлечения или наоборот:

# ~/.hermes/config.yaml
web:
  search_backend: "searxng"     # используется web_search
  extract_backend: "firecrawl"  # используется web_extract

Если ключ по возможности пуст, эта возможность проваливается на web.backend. Автоопределение по имеющемуся API-ключу или URL включается только тогда, когда общий выбор веб-бэкенда (web.backend или управляемая строка hermes tools) не записывался ни разу: как только общий выбор существует, среда выполнения всегда следует ему, и добавление ключа в .env веб-трафик не перенаправит. Ключ по возможности влияет только на свою возможность: один лишь web.extract_backend оставляет web_search на автоопределённом бэкенде.

Порядок приоритета (по каждой возможности):

1. web.search_backend / web.extract_backend (явно по возможности; nous = управляемый Tool Gateway только для этой возможности, см. Tool Gateway)
2. web.backend (общий фолбэк; nous = управляемый Tool Gateway)
3. Автоопределение по переменным окружения (общий выбор не записан)

Автоопределение

Если общий бэкенд не выбирался ни разу (web.backend не записан ни вами, ни через hermes tools), Hermes берёт первый доступный — по тому, какие учётные данные выставлены:

Бесключевое кольцо бесплатных тарифов: когда нет ни одной учётки из таблицы выше, запросы по очереди уходят к публичным бесплатным тарифам вендоров кольца (Exa, Parallel, Firecrawl, Keenable) — веб-инструменты работают на свежей установке вообще без настройки, а запрос, упёршийся в лимит частоты, или поиск, который вендор отклонил, автоматически переезжает на следующего вендора в кольце. Закрепите одного вендора в hermes tools, чтобы остановить ротацию (тогда кольцо служит только цепочкой подстраховки при лимитах). Все бесплатные тарифы ограничены вендорами по частоте при всплесках нагрузки; ровная обычная нагрузка проходит нормально. Чтобы выключить уровень, задайте web.keyless_fallback: false — тогда без учётных данных веб-инструменты будут недоступны, пока не настроен провайдер. Идентичности Nous (в том числе гостевой) этот переключатель не касается: управляемый web_search по-прежнему работает, а для web_extract нужен настроенный провайдер.

Разовое бесключевое спасение для бэкендов с ключом: если ваш выбранный бэкенд с ключом — включая маршрут через Nous Tool Gateway (web.backend: nous) — провалил вызов (неверный ключ, авария, недоступный шлюз, 5xx на стороне провайдера), именно этот вызов автоматически повторяется на бесключевом кольце, а не отдаёт ошибку — в результате указано, кто из вендоров его обслужил и почему (rescued_from / backend_error). Переключение не залипает: следующий же вызов web_search/web_extract снова идёт в ваш бэкенд. Отключается через web.keyless_rescue: false (а также автоматически выключено, когда выключен keyless_fallback).

Веб-поиска xAI в цепочке автоопределения нет: наличие XAI_API_KEY (или вход через xAI Grok OAuth) само по себе не направляет веб-трафик через xAI, ведь эти же учётные данные используются для инференса, TTS и генерации картинок, а для веба пользователю может быть нужен другой бэкенд. Подключайте его явно через web.backend: "xai".

---

Проверка настройки

Выполните hermes setup, чтобы увидеть, какой веб-бэкенд распознан:

✅ Web Search & Extract (searxng)

В checkout исходников модуль можно проверить и напрямую — после активации PM. Используйте тот домашний каталог, веб-настройки которого хотите посмотреть:

# Из checkout исходников Hermes, в чистой оболочке
source ./activate
python -m tools.web_tools

Это выведет активный бэкенд и его статус:

✅ Web backend: searxng
   Using SearXNG (search only): http://localhost:8888

---

Устранение неполадок

web_search возвращает {"success": false}

• Проверьте, что SEARXNG_URL доступен: curl -s "http://localhost:8888/search?q=test&format=json"
• Если приходит HTTP 403, формат JSON выключен — добавьте json в список formats в settings.yml и перезапустите
• Если приходит ошибка соединения, контейнер, возможно, не запущен: docker ps | grep searxng

web_extract сообщает «search-only backend»

SearXNG не умеет извлекать содержимое URL. Укажите в web.extract_backend провайдера с поддержкой извлечения:

web:
  search_backend: "searxng"
  extract_backend: "firecrawl"  # или tavily / perplexity / keenable / exa / parallel

SearXNG возвращает 0 результатов

Некоторые публичные инстансы отключают отдельные поисковые движки или категории. Попробуйте:

• Другой запрос
• Другой публичный инстанс с searx.space
• Self-hosting собственного инстанса для стабильной выдачи

Лимит запросов на публичном инстансе

Переходите на собственный инстанс (см. Вариант A выше). С Docker у вашего инстанса лимитов на запросы нет.

web_extract возвращает обрезанный контент со сноской [TRUNCATED]

Так и задумано для страниц сверх лимита по символам. Сноска называет файл на диске с полным очищенным текстом и точный вызов read_file, чтобы дочитать пропущенную середину. Хотите видеть больше прямо в ответе — поднимите web.extract_char_limit в config.yaml или передайте больший char_limit в самом вызове.

---

Опциональный навык: searxng-search

Если агенту нужно обращаться к SearXNG через curl напрямую (например, как фолбэк, когда веб-набор инструментов недоступен), установите опциональный навык searxng-search:

hermes skills install official/research/searxng-search

Этот навык учит агента:

• Вызывать JSON API SearXNG через curl или Python
• Фильтровать по категории (general, news, science и т. д.)
• Обрабатывать пагинацию и ошибочные случаи
• Аккуратно переключаться на фолбэк, когда SearXNG недоступен