# RKDash Adapter for Hermes Agent

Адаптер для [Hermes Agent](https://github.com/NousResearch/hermes-agent), который подключает агента,
живущего на своём сервере, к платформе ресторанной аналитики [RKDash](https://rkdash.com).

После установки агент работает с платформой в обе стороны: видит данные ресторанов, берёт задачи
с доски, оставляет отчёты в карточках; платформа может будить его прогоном по задаче.

## Что даёт адаптер

- **Инструменты платформы** — MCP-сервер `rkdash` с 26 инструментами: заведения, меню и фудкост,
  чеки и продажи, официанты, склад, дашборды, интеграции, доска задач, вопросы к AI-агенту.
  Инструменты — те же операции, что доступны человеку в панели: прав у агента не больше, чем у ключа.
- **Навык платформы** — регламент работы: какой инструмент под какую задачу, формат ответа,
  что запрещено.
- **Работа по задачам с доски** — задача, назначенная агенту, доходит до него прогоном; отчёт
  агент оставляет комментарием в карточке.
- **Забор задач самим агентом** — если платформа не может достучаться до сервера агента
  (агент за NAT), он забирает назначенное сам запросом `GET /api/v1/agent-tasks`.

## Архитектура

```
Hermes-агент (свой сервер)
      │  инструменты / MCP                     агент → RKDash
      ▼
RKDash: /api/mcp  +  /api/v1 (ключ агента, права, идемпотентность, журнал)
      ▲
      │  прогон по задаче с доски              RKDash → агент
      └── POST /v1/runs + поток событий по SSE (служба агента, API_SERVER_ENABLED=true)
```

## Установка

### Быстро: дайте агенту ссылку на этот репозиторий

Агент прочитает `AGENTS.md`, задаст вам два вопроса (ключ платформы и режим работы) и настроит
себя сам. Ключ берётся в панели RKDash: **Цифровые сотрудники → карточка исполнителя → «Комплект
для установки»**.

### Вручную

Требуется [Hermes Agent](https://github.com/NousResearch/hermes-agent) и Python 3.10+.

```bash
git clone https://github.com/geniok1980/hermes-rkdash-adapter.git
RKDASH_KEY=rk_live_… sh hermes-rkdash-adapter/install.sh
```

Либо одной строкой, без клонирования (установщик скачает навык сам):

```bash
curl -fsSL https://raw.githubusercontent.com/geniok1980/hermes-rkdash-adapter/main/install.sh \
  | RKDASH_KEY=rk_live_… sh
```

Установщик:

1. ставит навык платформы в навыки нужного профиля;
2. прописывает MCP-сервер `rkdash` в `config.yaml` этого профиля, не трогая чужие серверы;
3. проверяет связь (`hermes mcp test rkdash`) и показывает, сколько инструментов найдено;
4. добавляет в окружение профиля блок службы, к которой обращается платформа.

После установки перезапустите Hermes: навык и инструменты подхватываются при старте.

### Переменные установщика

| Переменная | По умолчанию | Что делает |
|---|---|---|
| `RKDASH_KEY` | — | Ключ платформы из панели. Обязателен |
| `RKDASH_URL` | `https://rkdash.com` | Адрес панели |
| `RKDASH_PROFILE` | `$HERMES_PROFILE` | Профиль агента; у него свои навыки, конфиг и `.env` |
| `RKDASH_SKILL` | `rkdash` | Имя навыка у агента |
| `RKDASH_CONFIG` | определяется сам | Путь к `config.yaml`, если он нестандартный |
| `RKDASH_SKIP_API_SERVER` | — | Не добавлять блок службы (платформа не будет будить агента) |

## Что остаётся человеку

1. **Включить службу агента**, чтобы платформа могла звать его прогоном:

   ```env
   API_SERVER_ENABLED=true
   API_SERVER_HOST=0.0.0.0
   API_SERVER_PORT=9131
   API_SERVER_KEY=<свой секрет>
   ```

   Адрес снаружи — только по `https`; это отдельная служба со своим ключом, не равная ключу
   платформы.

2. **Завести агента в панели**: «Цифровые сотрудники → Подключить агента», транспорт
   «Внешний агент по API server», адрес агента и его `API_SERVER_KEY`. Кнопка «Проверить» идёт
   тем же транспортом, что и задача.

3. **Включить MCP-сервер** в «Настройки → API». Пока он выключен, агент подключён, но
   инструментов не видит.

## Проверка

```bash
sh verify.sh                 # навык, конфиг, связь, служба агента
hermes mcp test rkdash       # связь с платформой и список инструментов
```

В панели: карточка исполнителя показывает, когда агент отвечал последний раз, сколько прогонов
прошло и сколько из них с ошибкой.

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

- Ключ платформы — это права агента: создавайте его под конкретного исполнителя и давайте только
  нужные области доступа. Инструменты изменения (цены, склад) требуют явного разрешения
  в карточке исполнителя.
- Ключ агента (`API_SERVER_KEY`) на стороне платформы хранится зашифрованным и наружу не отдаётся.
- Навык и установщик секретов не содержат: ключ передаётся при запуске и в репозиторий не попадает.

## Документация

- Живая документация и песочница API: https://rkdash.com/docs/api
- Адаптер со стороны платформы описан в репозитории платформы: `docs/hermes-adapter.md`.

## Лицензия

MIT — см. [LICENSE](LICENSE).