Hermes Mobile Adapter¶
Мобильное приложение общается с Hermes Agent напрямую по WebSocket — без своего
бэкенда. Сообщения с телефона попадают в те же сессии, историю, инструменты и память
агента, что и Telegram/CLI, а ответы приходят с индикатором «печатает», состояниями аватара
(thinking → speaking → idle), кнопками-карточками и медиа в обе стороны.
┌───────────────────────┐ WebSocket: текст, голос, медиа, карточки ┌──────────────────────────┐
│ ваше приложение │ ⇄ ws(s)://<хост-агента>:8787/ws │ Hermes Agent (шлюз) │
│ Swift / Kotlin / RN │ │ плагин hermes-mobile │
│ / Flutter / Web │ │ → агент, сессии, память │
└───────────────────────┘ └──────────────────────────┘
Для кого это¶
- Разработчики приложений — вы делаете мобильный клиент (нативный, RN, Flutter, web) и хотите, чтобы внутри работал ваш агент, но не хотите строить и содержать серверную часть: LLM-роутинг, историю, инструменты, память, cron. Всё это уже есть у Hermes — приложение лишь говорит с ним по WebSocket.
- Владельцы агента — у вас работает
hermes gateway; вы ставите плагин-адаптер, включаете платформуmobileвconfig.yaml, выдаёте разработчику адрес и токен.
Что это даёт¶
- Нет второго бэкенда. Адаптер — обычная платформа Hermes: он поднимает WebSocket-сервер
внутри шлюза и превращает кадры протокола в
MessageEvent. Нет отдельного API-слоя, второй истории, второго биллинга и второго набора инструментов. - Тот же агент, что в остальных каналах. Сессии и память живут в Hermes, а не в приложении; решения пользователя (одобрение опасных команд, уточнения) применяются родными механизмами Hermes.
- Протокол — это JSON-кадры. Никакой привязки к SDK: подойдёт любой рантайм с WebSocket. SDK (TypeScript/Python) и примеры приложены, но не обязательны.
- Cron умеет доставлять на устройство (
hermes send --to mobile:<device.id>): напоминания и отчёты приходят в приложение, пока оно подключено.
Два сценария использования¶
1. Свой агент (один владелец, одно-несколько своих устройств).
Вы владеете и агентом, и приложением. Ставите адаптер на машину агента, генерируете
MOBILE_TOKEN, вшиваете его в приложение (или выдаёте устройству), подключаетесь. Можно
ограничить доступ белым списком устройств. См. Владельцу агента и
Начало.
2. Приложение для чужих агентов (публичный продукт).
Вы публикуете приложение, а агентами владеют разные люди. Тогда общий токен в сборку вшивать
нельзя: каждому устройству нужен свой токен (MOBILE_EXTRA_TOKENS у владельца или штатный
pairing Hermes), а пользователь в приложении сам вводит адрес и токен своего агента. Подробно —
Безопасность.
Карта документации¶
| Раздел | О чём |
|---|---|
| Начало | от нуля до первого ответа агента: установка, токен, пример, проверка без кода |
| Владельцу агента | установка плагина, включение платформы, токен, wss через прокси, выдача доступа |
| Как всё устроено | адаптер как платформа Hermes, сессии и device.id, токены и белые списки, память/инструменты/cron |
| Протокол v1 | полный справочник: все кадры, поля, лимиты, состояния, коды ошибок, версионирование |
| Интерфейс приложения | что обязательно реализовать в UI и что будет, если этого не делать |
| Безопасность | токен как единственный секрет, свои токены на устройства, только wss, отзыв доступа |
| Диагностика и FAQ | матрица «симптом → причина → решение» и частые вопросы |
| Справочник SDK | TypeScript и Python клиенты протокола |
| Руководства по платформам | React Native, Flutter, iOS, Android, web, рецепты, conformance |
Протокол на уровне спецификации также лежит в репозитории: ../protocol/index.md;
практическое руководство по встраиванию — ../guides/integration.md.