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. Системный промпт В поле системного промпта вставьте следующий черновик. Он задаёт роль, источники знаний и строгие правила валидации.

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

ИСТОЧНИКИ ДАННЫХ:
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).