Настройка Raft

Hermes подключается к Raft в роли внешнего агента — через локальный мост wake-канала. Адаптер поднимает HTTP-эндпоинт на петлевом интерфейсе, принимает от моста подсказки-сигналы (wake hints) без содержимого и прокидывает их в конвейер сессии шлюза Hermes. Сообщения агент читает и отправляет через Raft CLI; самих тел сообщений и курсоров доставки адаптер не касается.

инфо

Разделение труда

Мост отвечает за: приём wake-подсказок, дедупликацию, backoff, переподключение, доставку at-least-once и журнал доказательств.
Адаптер Hermes отвечает за: wake-эндпоинт на localhost и вставку короткого уведомления в контекст агента.
Агент отвечает за: вытягивание сообщений (raft message check), ответы (raft message send) и любое другое взаимодействие с Raft через CLI.

Учётных данных Raft адаптер не хранит — только разовый общий токен сессии для авторизации между мостом и эндпоинтом по localhost.

Требования

Рабочее пространство Raft, где можно завести External Agent
Установленный Raft CLI, под которым выполнен вход в профиль этого внешнего агента
aiohttp — пакет Python (входит в extras [all] Hermes)

В Raft откройте меню Agents, создайте External Agent и пройдите по карточке настройки: поставьте Raft CLI и залогиньтесь под профилем агента. После создания агента Raft покажет руководство по настройке Hermes — там будут переменные окружения и параметры, нужные для запуска шлюза.

Настройка

Добавьте в ~/.hermes/.env:

RAFT_PROFILE=your-agent-profile

Вот и всё — адаптер включается сам, как только задан RAFT_PROFILE. Он генерирует сессионный токен для моста, выбирает свободный порт и при старте шлюза сам поднимает дочерний процесс моста.

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

Raft Server → Bridge (wake-hints SSE) → POST /wake → Hermes Adapter → Agent context
Agent → raft message check → Raft Server (message bodies)
Agent → raft message send → Raft Server (replies)

Сервер Raft шлёт wake-подсказки процессу моста по SSE.
Мост пересылает каждую подсказку как POST /wake на петлевой эндпоинт адаптера.
Адаптер проверяет токен моста, убеждается, что в payload нет содержимого, и вставляет wake-уведомление в сессию Hermes.
Агент видит это уведомление и через Raft CLI читает сообщения и отвечает.

Wake-payload по контракту не несёт содержимого — в нём только метаданные (ID события, ID сообщения, метки времени), но никогда тела сообщений, имена каналов или личности отправителей. Любой payload с полями, похожими на содержимое (text, body, content, messages и т. п.), адаптер отвергает.

Мост

Адаптер сам запускает raft agent bridge дочерним процессом, передавая ему URL эндпоинта и токен. Мост получает очищенное дочернее окружение Hermes плюс RAFT_PROFILE и этот токен, но никогда не получает токены шлюза Hermes и API-ключи провайдеров. Мост подключается к серверу Raft под заданным профилем и начинает пересылать wake-подсказки. При остановке шлюза мост завершается.

Переменные окружения

Переменная	Описание	По умолчанию
`RAFT_PROFILE`	Slug профиля агента Raft — задаёшь его, и адаптер включается сам	(обязательна)