HH AI Agent — AI-агент для автоматического поиска вакансий и откликов на hh.ru

· 2 мин чтения
ai-agents automation python llm job-search
📂 Исходный код на GitHub

Автономный AI-агент для поиска работы: сканирует вакансии на HH.ru через антидетект-браузер, анализирует соответствие профилю кандидата с помощью LLM (Ollama, Mistral или любой OpenAI-compatible), пишет сопроводительные письма и отправляет карточки вакансий в Telegram с inline-кнопкой подтверждения отклика.

HH AI Agent — AI-агент для автоматического поиска вакансий и откликов на hh.ru

HH AI Agent — AI-агент для автоматического поиска вакансий и откликов на hh.ru

HH AI Agent — это open-source агент на Python (лицензия MIT), который берёт на себя рутину поиска работы: он автоматически ищет вакансии на HH.ru, оценивает их соответствие вашему профилю через LLM, генерирует сопроводительные письма и присылает подходящие варианты прямо в Telegram. Проект набрал более 220 звёзд на GitHub, а главное его отличие от «безликих автокликеров» — продуманная модель безопасности: ни один реальный отклик не отправляется без явного нажатия кнопки владельцем аккаунта.

Как это работает

Конвейер агента выглядит так:

  1. Поиск вакансий — агент через браузерный бэкенд сканирует HH.ru (за основу взят CloakBrowser с поддержкой Playwright как запасного варианта)
  2. Анализ через LLM — каждая вакансия сравнивается с вашим профилем: модель оценивает, насколько позиция вам подходит, и объясняет почему
  3. Генерация сопроводительного письма — под конкретную вакансию пишется индивидуальное cover letter
  4. Карточка в Telegram — подходящая вакансия приходит ботом в виде карточки с кратким объяснением совпадения, рейтингом компании с HH и сворачиваемым сопроводительным письмом
  5. Подтверждённый отклик — реальный отклик происходит только после нажатия inline-кнопки «Откликнуться»

Быстрый старт

Весь процесс настройки automatизирован интерактивным мастером:

python setup_wizard.py

Wizard последовательно спросит:

  1. Токен Telegram-бота (создаётся через @BotFather) и ваш User ID
  2. Какой AI-провайдер использовать — Ollama локально, Mistral API или любой OpenAI-compatible
  3. Данные вашего профиля для анализа вакансий
  4. Режим работы

После этого мастер создаст файлы .env и profile.yaml, проверит конфигурацию и подскажет дальнейшие шаги. Изменить настройки позже можно командой:

python setup_wizard.py --edit

Требования

  • Python 3.11+
  • Telegram Bot (через @BotFather)
  • Один из LLM-провайдеров
  • CloakBrowser — устанавливается автоматически через wizard

Режимы работы

Режим Описание
dry_run Ищет и анализирует вакансии, присылает превью в Telegram — без реальных откликов
approval Присылает вакансию с кнопкой «Откликнуться» — отклик только после вашего нажатия

Авторы рекомендуют начинать с dry_run и переходить на approval только после того, как вы убедитесь, что агент правильно понимает ваш профиль. Если rich messages в Telegram недоступны, бот отправляет обычную HTML-карточку вакансии.

LLM-провайдеры

Агент не привязан к одному вендору и работает с тремя вариантами:

Ollama (рекомендуется — локально и бесплатно)

ollama pull llama3

Устанавливаете Ollama, загружаете модель и выбираете Ollama в wizard. Вакансии и профиль остаются на вашей машине.

Mistral API (облачный)

Регистрация на console.mistral.ai, создание API-ключа и ввод его в wizard. Важно: wizard создаёт отдельный MISTRAL_KEYS_MASTER_KEY для локального шифрования ключей — сохраните резервную копию, без неё уже сохранённые ключи расшифровать нельзя. Управлять ключами после запуска можно командой /mistral_keys; в Telegram и логах показываются только последние четыре символа ключей.

Имейте в виду: при использовании Mistral текст вакансий и ваш профиль уходят во внешний API.

OpenAI-compatible

Поддерживается любой сервис с эндпоинтом /chat/completions — LocalAI, LM Studio, Groq и тому подобные. В wizard достаточно указать URL и ключ.

Telegram-команды

Команда Описание
/start Краткая справка
/status Режим, состояние, статистика
/pause Приостановить поиск
/resume Возобновить поиск
/pending Вакансии, ожидающие решения
/stats Статистика по статусам
/diagnostics Результат последнего цикла и состояние circuit breaker
/mistral_keys Список, проверка, добавление и удаление Mistral-ключей
/cancel Отменить ввод CAPTCHA

Архитектура

Проект устроен как набор небольших модулей с чётким разделением ответственности:

Файл Ответственность
config.py Валидация .env и profile.yaml
browser_backend.py CloakBrowser / Playwright адаптер
hh_client.py Поиск, чтение страниц, отправка откликов
llm/ Ollama / Mistral / OpenAI-compatible адаптеры, retry, квота
ai_analyzer.py Анализ вакансий, генерация писем
database.py SQLite-состояние, лимиты, переходы статусов
approval.py Единственный разрешённый инициатор реального отклика
tg_bot.py Telegram-команды, превью, inline-кнопки
main.py Основной цикл агента
setup_wizard.py Интерактивный мастер настройки

Ключевой модуль с точки зрения безопасности — approval.py: именно он является единственной точкой, откуда может быть инициирован реальный отклик.

Безопасность

Модель безопасности здесь продумана серьёзно:

  • Реальный отклик требует трёх одновременных условий: APP_MODE=approval + ENABLE_REAL_APPLY=true + нажатие кнопки вашим Telegram ID
  • Одноразовое разрешение действует 30 минут после нажатия
  • Массового автоматического режима нет в принципе
  • .env, profile.yaml и .browser-profile/ исключены из Git
  • Токены, cookies и полный .env не записываются в логи

Архитектуру безопасного конвейера — от поиска вакансий до approval-механизма с permit-токенами — спроектировал kkonstantin08, а базовые проверки и валидацию конфигурации реализовал danscMax.

Типичные ошибки

Ошибка Решение
Configuration error Заполнить все обязательные поля через python setup_wizard.py --edit
CloakBrowser failed to start Проверить python -m cloakbrowser info, при необходимости переключиться на BROWSER_BACKEND=playwright
HH.ru login is required Запустить с BROWSER_HEADLESS=false и войти вручную
LLM check failed Проверить endpoint, ключ и дневную квоту через python main.py --check-llm
Invalid model response Проверить провайдера и модель — вакансия безопасно пропускается

Разработка

Тесты проекта не обращаются к HH.ru, Telegram или внешним LLM — всё изолировано:

python -m compileall .
pytest -q

Ограничения и важные оговорки

Честный список ограничений из README:

  • Автоматизация может нарушать правила HH.ru — ответственность за аккаунт несёт пользователь
  • CloakBrowser не гарантирует отсутствие детектирования или CAPTCHA
  • Нет proxy, GeoIP-ротации и внешних CAPTCHA-сервисов
  • Рассчитано на одного владельца и одну SQLite-базу
  • Сопроводительное письмо всегда нужно читать в Telegram перед откликом

Автор прямо предупреждает: автоматизация HH.ru нарушает пользовательское соглашение, использовать нужно на свой страх и риск — автор не несёт ответственности за возможные ограничения аккаунта.

Итог

HH AI Agent — показательный пример того, как строить персональных AI-агентов с реальными действиями в внешнем мире, не теряя контроля: LLM анализирует и готовит, человек одобряет, а механизм permit-токенов гарантирует, что между первым и вторым ничего не проскочит. Репозиторий: fikstt2/hh-ai-agent. Вопросы и предложения — автору в Telegram: @fikstt3.

Источник: https://github.com/fikstt2/hh-ai-agent

Похожие материалы