🛠️ Технологии

Нативный платформенный плагин для Hermes Agent

Подключает мессенджер MAX через Bot API — полная интеграция с AI-агентом

_{🎨 Designed by BR-DESIGN}

📋 Содержание

Возможности
Установка
Настройка
Использование
Архитектура
Сравнение с Telegram Bot API
Лицензия

✨ Возможности

Фича	Статус
Приём и отправка текстовых сообщений	✅
Inline keyboard (кнопки с callback)	✅
Индикатор «Печатает...»	✅
Markdown-форматирование	✅
Белый список пользователей	✅
Webhook + Long Polling	✅
Отправка изображений (через upload API)	✅

📦 Установка

Из исходников

# Клонируйте репозиторий в папку плагинов Hermes
git clone https://github.com/RuslanStrogov/max-hermes-plugin.git \
  ~/.hermes/plugins/platforms/max

# Перезапустите Hermes Gateway
hermes gateway restart

Через hermes plugins (если опубликован)

hermes plugins install max-platform

⚙️ Настройка

1. Создайте бота в MAX

⚠️ Важно: Создание ботов на платформе MAX доступно только юридическим лицам, ИП и самозанятым (резидентам РФ). Физическим лицам создание ботов недоступно.

Тип профиля	Кол-во ботов
Организация / ИП	Несколько (не ограничено платформой)
Самозанятый	Ограничено

Пошаговая инструкция:

Перейдите на портал MAX для партнёров
Создайте и верифицируйте профиль организации, ИП или самозанятого
В панели управления нажмите «Добавить бота»
Заполните данные бота (карточка):
- Название — от 1 до 59 символов
- Никнейм — генерируется автоматически (должен заканчиваться на _bot)
- Сайт организации, логотип и описание
Нажмите «Готово» — бот создан и отправлен на модерацию
Дождитесь уведомления о прохождении модерации
После модерации получите токен бота

Подробнее: MAX для разработчиков — Создание чат-бота

2. Настройте переменные окружения

# Добавьте в ~/.hermes/.env
MAX_BOT_TOKEN=your_bot_token_here
MAX_WEBHOOK_URL=https://your-domain.com/webhook
MAX_WEBHOOK_SECRET=your_secret

Или через config.yaml:

gateway:
  platforms:
    max:
      enabled: true
      extra:
        token: "your_bot_token"
        webhook_url: "https://your-domain.com/webhook"
        allowed_users: []

3. Настройте сервер

Nginx reverse proxy:

server {
    listen 443 ssl;
    server_name your-domain.com;

    location /webhook {
        proxy_pass http://127.0.0.1:8787;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

4. Запустите

hermes gateway restart

🚀 Использование

После подключения бот будет автоматически:

Принимать сообщения от пользователей MAX
Передавать их агенту Hermes
Отправлять ответы обратно в MAX

Inline keyboard

Агент может отправлять сообщения с кнопками:

buttons = [
    [{"text": "Да", "payload": "yes"}, {"text": "Нет", "payload": "no"}]
]

🏗️ Архитектура

┌──────────┐   webhook    ┌─────────────────┐   native    ┌──────────────┐
│          │ ──────────►  │                 │ ──────────►  │              │
│ MAX Bot  │              │ MAX Hermes      │              │ Hermes Agent │
│ API      │ ◄──────────  │ Plugin          │ ◄──────────  │              │
│          │  send_msg    │ (Python)        │  response    │              │
└──────────┘              └─────────────────┘              └──────────────┘

Пользователь пишет боту в MAX
MAX API отправляет webhook на плагин
Плагин передаёт сообщение в Hermes Agent
Ответ Hermes отправляется обратно в MAX через Bot API

📊 Сравнение с Telegram Bot API

Возможность	Telegram	MAX Bot API
Webhook	✅	✅
Long Polling	✅	✅
Inline keyboard	✅	✅
Reply keyboard	✅	❌ (только inline)
Callback buttons	✅	✅
Send/Edit/Delete messages	✅	✅
Typing indicator	✅	✅
Read receipts	✅	❌
Bot commands menu	✅	❌
Send images/files	✅	✅ (через upload)
Group chats	✅	✅
Channels	✅	✅

📄 Лицензия

MIT License. См. LICENSE.

🔗 Связанные проекты

Проект	Описание
MAX Hermes Bridge	Python-мост между MAX Bot API и Hermes Agent через CLI. Поддерживает webhook, Docker, systemd.

📢 Пресс-релизы

Готовые тексты для публикации в сообществах и СМИ: