ii-agent-soglasovanie-otpusk/alem_guide.md

**. Веб-интерфейс здесь не нужен и даже вреден, так как процесс полностью живёт в Telegram.

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

[[GUIDE]]
## 1. Почему Alem, а не отдельная разработка
- **Логика укладывается в возможности платформы:** Задача агента — прочитать данные (KTWorks), применить правила (лимит 2 человека, дежурный) и записать результат (Excel). Это стандартный сценарий для MCP/API-агента на Alem без необходимости писать отдельный бэкенд.
- **Интерфейс уже существует:** Владелец и сотрудники используют Telegram. Делать отдельный веб-портал, куда нужно заходить ради 5–15 операций в месяц, значит усложнять жизнь пользователю и создавать «мёртвую» систему.
- **Human-in-the-loop нативен:** Платформа Alem позволяет встроить узел «Одобрение пользователя» прямо в сценарий, что соответствует требованию брифа (кнопка «Согласовать» в чате).
- **Экономия времени:** Внедрение через Alem занимает дни, а не месяцы, так как не требует разработки UI и мобильной версии.
- **Ограничения:** Решение зависит от стабильности доступа к сетевой папке через MCP и качества данных в KTWorks. Если файловое хранилище будет недоступно, агент не сможет записать файл (требуется обработка ошибок).

## 2. Что делает агент
Агент выступает цифровым ассистентом руководителя отдела по согласованию отпусков. Он мониторит запросы в Telegram, автоматически сверяет остаток дней в KTWorks и проверяет график на конфликты (чтобы не ушли больше 2 человек одновременно и остался дежурный). Вместо того чтобы руководитель бегал по системам, агент присылает готовое решение: «Сотрудник Х, даты Y–Z, остаток N дней, конфликтов нет» с кнопкой подтверждения. После нажатия кнопки агент сам обновляет общий Excel-файл на сетевом диске и готовит отчёт для HR.

## 3. Пошаговое создание в Alem
Решение будет жить в чате Telegram (через бота) и работать на базе платформы Alem. Адрес платформы: https://alem.ai-kt.kz.

**Шаг 1. Создание агента**
В интерфейсе Alem нажмите **«Создать супер-сотрудника»**. Выберите тип агента: **Skill-агент** (так как требуется генерация файлов/отчётов) или **Workflow-агент** (если нужна сложная логика ветвления). Назовите агента, например, «Отпуска-Бот».

**Шаг 2. Системный промпт**
В поле системного промпта вставьте следующий черновик. Он задаёт роль, источники знаний и строгие правила валидации.

```markdown
Ты — ИИ-ассистент руководителя отдела по согласованию отпусков.
Твоя цель: обрабатывать запросы сотрудников на отпуск, проверять их корректность и обновлять график.

ИСТОЧНИКИ ДАННЫХ:
1. KTWorks (через MCP/API): остаток дней отпуска сотрудника.
2. Excel-файл "График отпусков 2026.xlsx" на сетевом диске \\fs-dept\otdel\Отпуска\: текущий список утверждённых отпусков.

ПРАВИЛА ВАЛИДАЦИИ (СТРОГО):
1. Лимит одновременного отсутствия: в одни даты не могут отсутствовать более 2 человек.
2. Дежурный: среди отсутствующих не должно быть единственного доступного старшего сотрудника (из "тройки старших").
3. Остаток: у сотрудника должен быть достаточный остаток дней отпуска в KTWorks.

АЛГОРИТМ РАБОТЫ:
1. Получи запрос от сотрудника (ФИО, даты, тип отпуска).
2. Проверь остаток в KTWorks. Если недостаточно — сообщи об отказе.
3. Проверь даты по Excel-графику на предмет пересечений (лимит 2 чел.) и наличия дежурного.
4. Если всё ок — сформируй черновик ответа для руководителя: "Сотрудник [ФИО], даты [X-Y], остаток [N] дней. Конфликтов нет." и предложи кнопку "Согласовать".
5. Если есть конфликт — напиши причину: "Конфликт: в эти даты уже уходят [Список] / Нет дежурного".
6. После нажатия кнопки "Согласовать":
   - Добавь строку в Excel-файл на сетевом диске.
   - Отправь подтверждение сотруднику.
   - Добавь запись в список для еженедельного отчёта HR.

ЧЕГО НЕ ДЕЛАТЬ:
- Не согласовывай отпуск без явного подтверждения руководителя (кнопки).
- Не изменяй файл, если доступ к сети потерян (сообщи об ошибке).
- Не игнорируй правило дежурного.
```

**Шаг 3. База знаний и навыки**
- **База знаний:** Загрузите документ с актуальным списком «Тройки старших» (ФИО, должности), чтобы агент знал, кого нельзя отпускать всех одновременно.
- **Навыки (Skills):** Убедитесь, что подключен навык работы с файлами (Excel) и MCP-коннекторы для KTWorks и сетевой папки.

**Шаг 4. Публикация и интеграция с Telegram**
1. В карточке агента нажмите **«Опубликовать»**.
2. Выберите интерфейс **API**. Платформа создаст API-ключ и покажет эндпоинты.
3. Для работы в Telegram потребуется настроить бота-оркестратора (внешний сервис или скрипт), который будет:
   - Слушать сообщения в чате отдела.
   - Отправлять текст запроса в Alem через `POST /gateway/app/api/v1/published/conversation`.
   - Получать `session_id` и пересылать сообщения через `POST .../published/{session_id}/send`.
   - Отображать кнопки (Inline Keyboard) для подтверждения руководителю.

**Шаг 5. Узел одобрения**
В сценарии (Workflow) добавьте узел **«Одобрение пользователя»** после этапа проверки правил. Это гарантирует, что запись в файл произойдёт только после нажатия кнопки руководителем.

## 4. Примеры поведения
**Вопрос:** «Прошу согласовать отпуск с 10 по 24 августа (14 дней).» (Сотрудник: Иванов А.)
**Ожидаемый ответ (Руководителю):** «Иванов А., 10–24 августа. Остаток в KTWorks: 20 дней. Конфликтов нет (в эти даты уходит только Петров). Предварительное решение: Согласовать. [Кнопка: Согласовать] [Кнопка: Отклонить]»

**Вопрос:** «Можно ли мне в отпуск с 1 по 15 июля?» (Сотрудник: Сидоров В., один из «тройки старших»)
**Ожидаемый ответ (Руководителю):** «Сидоров В., 1–15 июля. Остаток: 15 дней. ВНИМАНИЕ: Конфликт правил. В эти даты уже отсутствуют Иванов и Петров. Если уйдёте вы, не останется дежурного старшего. Рекомендация: Отклонить или сдвинуть даты.»

**Вопрос:** «Согласовать отпуск для Кузнецовой (5 дней).»
**Ожидаемый ответ (Руководителю):** «Кузнецова Е., даты не указаны. Уточните даты начала и конца отпуска для проверки графика.»

## 5. Как принять работу
**Чек-лист приёмки:**
- [ ] Агент корректно считывает остаток дней из KTWorks для тестового сотрудника.
- [ ] Агент правильно определяет конфликт «>2 человек» на тестовых данных из Excel.
- [ ] Агент блокирует согласование, если уходит последний «старший» (проверка правила дежурного).
- [ ] После нажатия кнопки «Согласовать» строка реально появляется в файле `\\fs-dept\otdel\Отпуска\График отпусков 2026.xlsx`.
- [ ] При отсутствии сети агент не падает, а сообщает об ошибке записи.

**Что подтвердить до запуска (Блокеры):**
1. **Доступ к файловой системе:** Подтвердить техническую возможность записи в сетевую папку `\\fs-dept\otdel\Отпуска\` через MCP-коннектор или сервис-аккаунт (нужны учётные данные).
2. **Доступ к KTWorks:** Согласовать с HR и ДЦБ доступ агента к API KTWorks для чтения кадровых профилей (read-only).
3. **Telegram-интеграция:** Реализовать и протестировать бота-оркестратора для доставки сообщений и обработки нажатий кнопок (так как нативный чат Alem работает внутри платформы, а процесс идёт в Telegram).