Hermes agent

Поиск по X (Twitter)

Инструмент x_search даёт агенту прямой доступ к постам, профилям и тредам X (Twitter). Под капотом — встроенный инструмент x_search из Responses API xAI по адресу https://api.x.ai/v1/responses. Сам Grok гоняет поиск на стороне сервера и возвращает готовый текст со ссылками на исходные посты.

Берите его вместо web_search, когда вам нужны именно свежие обсуждения, реакции или утверждения в X. Для обычных веб-страниц по-прежнему используйте web_search / web_extract.

совет

Если вы и так платите Portal за модель xAI, вызовы Live Search списываются с того же ключа xAI, что настроен для чата. Подробнее — Nous Portal.

Аутентификация

x_search регистрируется, когда доступен любой из путей получения учётных данных xAI:

Учётные данныеИсточникНастройка
OAuth SuperGrok / X Premium+ (предпочтительно)Вход через браузер на accounts.x.ai, обновляется автоматическиhermes auth add xai-oauth — см. OAuth xAI Grok (SuperGrok / X Premium+)
XAI_API_KEYПлатный API-ключ xAIЗадаётся в ~/.hermes/.env

Оба бьют в один и тот же эндпоинт с одинаковым телом запроса — отличается лишь bearer-токен. Когда настроены оба, побеждает OAuth SuperGrok, поэтому x_search расходует квоту вашей подписки, а не платный API-бюджет.

Функция check_fn инструмента запускает резолвер учётных данных xAI каждый раз, когда список инструментов модели пересобирается. Возврат True означает, что bearer-токен можно получить, он непустой и (если срок истёк) успешно обновлён. При отозванных токенах с неудавшимся обновлением инструмент прячется из схемы — модель его попросту не видит.

Включение инструмента

Включается сам, как только присутствуют учётные данные xAI (OAuth-токен или XAI_API_KEY). Если он вам не нужен, отключите явно через hermes tools → Search → x_search.

hermes tools
# → 🐦 X (Twitter) Search   (нажмите пробел, чтобы включить)

Меню выбора предлагает два варианта учётных данных:

  1. xAI Grok OAuth (SuperGrok / Premium+) — откроет браузер на accounts.x.ai, если вы ещё не вошли
  2. API-ключ xAI — запросит XAI_API_KEY

Любой из вариантов снимает блокировку. Выбирайте те данные, что у вас уже есть; инструмент одинаково работает и с тем, и с другим. Если в итоге настроены оба, при вызове предпочтение отдаётся OAuth.

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

# ~/.hermes/config.yaml
x_search:
  # Модель xAI для вызова Responses.
  # grok-4.20-reasoning — рекомендованный вариант по умолчанию; подойдёт любая
  # модель Grok с доступом к инструменту x_search.
  model: grok-4.20-reasoning

  # Таймаут запроса в секундах. x_search может занимать 60–120 с на
  # сложных запросах — значение по умолчанию взято с запасом. Минимум: 30.
  timeout_seconds: 180

  # Сколько автоматических повторов делать при 5xx / ReadTimeout / ConnectionError.
  # Каждый повтор откатывается (1.5 × номер попытки секунд, не больше 5 с).
  retries: 2

Параметры инструмента

Агент вызывает x_search со следующими аргументами:

ПараметрТипОписание
querystring (обязательный)Что искать в X.
allowed_x_handlesstring arrayНеобязательный список хэндлов, которые включаются исключительно (не более 10). Ведущий @ отбрасывается.
excluded_x_handlesstring arrayНеобязательный список хэндлов для исключения (не более 10). Взаимоисключающий с allowed_x_handles.
from_datestringНеобязательная дата начала в формате YYYY-MM-DD.
to_datestringНеобязательная дата конца в формате YYYY-MM-DD.
enable_image_understandingbooleanПопросить xAI проанализировать изображения, прикреплённые к подходящим постам.
enable_video_understandingbooleanПопросить xAI проанализировать видео, прикреплённые к подходящим постам.

Инструмент возвращает JSON с полями:

  • answer — собранный текстовый ответ от Grok
  • citations — ссылки из верхнеуровневого поля Responses API
  • inline_citations — аннотации url_citation, извлечённые из тела сообщения (каждая с url, title, start_index, end_index)
  • degraded — true, когда был задан хотя бы один сужающий фильтр (allowed_x_handles, excluded_x_handles, from_date, to_date) И оба канала ссылок вернулись пустыми. В этом случае answer собран из собственных знаний модели, а не из индекса X, так что считайте его ответом без источников. В остальных случаях false (включая ситуацию «фильтры не заданы» — широкий ответ без источников остаётся просто ответом, а не промахом фильтра)
  • degraded_reason — короткая строка с перечнем активных фильтров либо null, когда degraded равно false
  • credential_source — "xai-oauth", если сработал OAuth, "xai", если сработал API-ключ
  • model, query, provider, tool, success

Проверка дат

from_date / to_date проверяются на стороне клиента до HTTP-вызова:

  • Обе даты, если заданы, должны разбираться как YYYY-MM-DD.
  • Когда заданы обе, from_date должна быть не позже to_date.
  • from_date не может быть позже сегодняшнего дня по UTC — в ещё не наступившем окне постов попросту не существует, и вызов гарантированно вернул бы ноль ссылок.
  • to_date в будущем допускается (вполне законно запросить «со вчера по завтра», чтобы ловить посты по мере их появления).

Ошибки проверки выдаются как структурированный результат инструмента {"error": "..."} — HTTP-вызова к xAI при этом не происходит.

Пример

Разговор с агентом:

What are people on X saying about the new Grok image features? Focus on responses from @xai.

Агент сделает следующее:

  1. Вызовет x_search с query="reactions to new Grok image features", allowed_x_handles=["xai"]
  2. Получит собранный ответ плюс список ссылок на конкретные посты
  3. Ответит текстом и приложит ссылки

Решение проблем

«No xAI credentials available»

Эту ошибку инструмент выдаёт, когда отказали оба пути аутентификации. Либо задайте XAI_API_KEY в ~/.hermes/.env, либо выполните hermes auth add xai-oauth и завершите вход через браузер. После этого перезапустите сессию, чтобы агент заново перечитал реестр инструментов.

«x_search is not enabled for this model»

У модели, указанной в x_search.model, нет доступа к серверному инструменту x_search. Переключитесь на grok-4.20-reasoning (значение по умолчанию) или другую модель Grok с его поддержкой. Актуальный список смотрите в документации xAI.

Инструмент не появляется в схеме

Две возможные причины:

  1. Набор инструментов не включён. Запустите hermes tools и убедитесь, что 🐦 X (Twitter) Search отмечен галочкой.
  2. Нет учётных данных xAI. check_fn возвращает False, и схема остаётся скрытой. Запустите hermes auth status, чтобы проверить статус входа xai-oauth, и убедитесь, что XAI_API_KEY задан (если идёте через API-ключ).

degraded: true — ответ без ссылок

Если вы применили allowed_x_handles, excluded_x_handles или диапазон дат, а ответ пришёл с degraded: true, значит индекс X у xAI не нашёл подходящих постов, но Grok всё равно собрал ответ из своих обучающих данных. Такой ответ без источников — не принимайте его за реальный результат из X.

Что стоит проверить:

  • Опечатка в хэндле. Уберите @, перепроверьте написание и убедитесь, что аккаунт существует.
  • Слишком узкий диапазон дат или окно, уехавшее дальше сегодняшних постов; расширьте и повторите.
  • Пробел в индексе xAI. Некоторые активные аккаунты время от времени не всплывают в x_search, даже если постят регулярно. Повторите через несколько минут или используйте навык xurl для прямого чтения через X API, когда нужна точная лента конкретного хэндла.

Смотрите также

⌕ ESC