X (Twitter) Поиск

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

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

подсказка

Если вы всё равно платите Portal за модель xAI, вызовы Live Search тарифицируются по тому же ключу xAI, который настроен для чата. См. Nous Portal.

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

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

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

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

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

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

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

vibeos tools
# → 🐦 X (Twitter) Search   (нажмите пробел для включения)

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

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

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

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

# ~/.vibeos/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.5x секунд попытки, не более 5 с).
  retries: 2

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

Агент вызывает x_search с этими аргументами:

Параметр	Тип	Описание
query	строка (обязательно)	Что искать на X.
allowed_x_handles	массив строк	Необязательный список хендлов для исключительного включения (макс. 10). Начальный @ удаляется.
excluded_x_handles	массив строк	Необязательный список хендлов для исключения (макс. 10). Взаимоисключающ с allowed_x_handles.
from_date	строка	Необязательная дата начала в формате YYYY-MM-DD.
to_date	строка	Необязательная дата окончания в формате YYYY-MM-DD.
enable_image_understanding	булев	Запросить у xAI анализ изображений, прикреплённых к подходящим постам.
enable_video_understanding	булев	Запросить у 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.

Пример

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

Что говорят на X о новых функциях изображений Grok? Сосредоточься на ответах от @xai.

Агент:

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

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

«Учётные данные xAI недоступны»

Инструмент показывает это, когда оба пути аутентификации не работают. Установите XAI_API_KEY в ~/.vibeos/.env или выполните vibeos auth add xai-oauth и завершите вход в браузере. Затем перезапустите сессию, чтобы агент перечитал реестр инструментов.

«x_search не включён для этой модели»

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

Инструмент не отображается в схеме

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

1. Набор инструментов не включён. Выполните vibeos tools и убедитесь, что 🐦 X (Twitter) Search отмечен.
2. Нет учётных данных xAI. check_fn возвращает False, поэтому схема остаётся скрытой. Выполните vibeos 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, когда вам нужна точная временная шкала хендла.

См. также

• xAI Grok OAuth (SuperGrok / Premium+) — руководство по настройке OAuth
• Веб-поиск и извлечение — для общего (не X) веб-поиска
• Справочник инструментов — полный каталог инструментов