## 1. Почему Alem, а не отдельная разработка
- **Скорость создания ядра:** Задача агента (поиск в Яндекс + чтение HTML + генерация JSON-теста) полностью закрывается стандартными навыками Alem (Web Search, Fetch, LLM) за 1-2 часа настройки, без написания бэкенда с нуля.
- **Гибкость логики:** Если владелец решит сменить источник («не первая ссылка, а только enbek.kz») или формат вопросов, это правится в промпте агента за минуту, а не в коде приложения.
- **Безопасный контур:** Агент работает внутри периметра КТ (on-prem), что позволяет легально парсить внешние ресурсы и обрабатывать данные сотрудников без вывода их в публичные облака.
- **Ограничение пилота:** Так как история не сохраняется и тест разовый, создание полноценной базы данных и админки избыточно. Alem берет на себя только «мозги» (генерацию), а веб-панель остается легкой оболочкой.

## 2. Что делает агент
Агент выступает в роли методиста по охране труда: он принимает от веб-панели запрос на тестирование, самостоятельно ищет актуальные инструкции монтера в интернете (Яндекс), анализирует содержимое первой релевантной ссылки, извлекает ключевые правила безопасности и формирует структурированный тест из 10 вопросов с вариантами ответов и ключами. После получения ответов от пользователя агент сверяет их с ключами, считает процент правильных ответов и выдает вердикт «Прошел/Не прошел».

## 3. Пошаговое создание в Alem
1.  **Создание агента:**
    *   Зайдите на платформу https://alem.ai-kt.kz.
    *   Нажмите **«Создать супер-сотрудника»**.
    *   Выберите тип: **Prompt-агент** (или KB-агент, если решите загрузить эталонные инструкции вручную, но для задачи «поиск в Яндекс» лучше Prompt + Tools).
    *   Название: `Экспресс-ОТ: Генератор тестов`.

2.  **Настройка системного промпта:**
    *   В поле «Системный промпт» вставьте следующий черновик. Он жестко регламентирует роль, источник и формат ответа (JSON), чтобы веб-панель могла его отобразить.

```markdown
# РОЛЬ
Ты — эксперт по охране труда и технике безопасности (ОТ и ТБ) для монтеров связи в Казахстане.
Твоя задача: провести экспресс-проверку знаний сотрудника.

# ИСТОЧНИКИ ДАННЫХ
1. Используй инструмент поиска (Web Search / Яндекс) по запросу: "техника безопасности монтер связи Казахстан инструкция".
2. Перейди по ПЕРВОЙ релевантной ссылке (приоритет: официальные порталы enbek.kz, zakon.kz, сайты операторов).
3. Прочитай содержимое страницы. Если ссылка битая или ведет на форум — попробуй вторую. Если данных нет — верни ошибку.

# ПРАВИЛА ГЕНЕРАЦИИ ТЕСТА
1. На основе прочитанного текста составь ровно 10 вопросов.
2. Вопросы должны быть практическими (про работу в колодцах, с электричеством, на высоте).
3. К каждому вопросу дай 3 варианта ответа (A, B, C), где только один верный.
4. Верный ответ должен строго соответствовать тексту инструкции.

# ФОРМАТ ОТВЕТА (СТРОГО JSON)
Ты должен вернуть только JSON объект, без лишнего текста.
Структура для этапа ГЕНЕРАЦИИ (когда пользователь еще не отвечал):
{
  "source_url": "ссылка на документ",
  "source_title": "название документа",
  "questions": [
    {
      "id": 1,
      "text": "Текст вопроса?",
      "options": ["Вариант А", "Вариант Б", "Вариант В"],
      "correct_index": 0 (индекс правильного ответа в массиве options: 0, 1 или 2)
    }
    ... (всего 10 вопросов)
  ]
}

Структура для этапа ПРОВЕРКИ (когда пользователь прислал ответы):
Входные данные от пользователя будут содержать массив его ответов.
Ты сравниваешь их с correct_index и возвращаешь:
{
  "score": 80, (процент правильных)
  "verdict": "Прошел", (или "Не прошел", если < 80%)
  "details": "Вы допустили ошибки в вопросах № 2, 5. Изучите раздел..."
}

# ОГРАНИЧЕНИЯ
- Не выдумывай правила, если их нет в источнике.
- Если источник ненадежный (форум, блог), предупреди в поле source_title.
- Не сохраняй данные пользователя. Работай в режиме "здесь и сейчас".
```

3.  **База знаний (опционально):**
    *   Если владелец решит снизить риск «плохих ссылок», загрузите в раздел **Базы знаний** актуальный PDF «Правила по охране труда при эксплуатации линейно-кабельных сооружений» и в промпте укажите: «Используй в первую очередь базу знаний, если там нет ответа — ищи в Яндекс».

4.  **Публикация и канал API:**
    *   В карточке агента нажмите кнопку **«Опубликовать»**.
    *   Выберите интерфейс **API**.
    *   Платформа сгенерирует **API-ключ** и покажет эндпоинты.
    *   **Контракт для разработчика веб-панели:**
        *   Шаг 1: Создать сессию.
            `POST /gateway/app/api/v1/published/conversation`
            Headers: `Authorization: Bearer <API_KEY>`
            Response: `{ "session_id": "..." }`
        *   Шаг 2: Отправить запрос (генерация или проверка).
            `POST /gateway/app/api/v1/published/{session_id}/send`
            Body (для генерации): `{ "message": "Сгенерируй тест по технике безопасности монтера" }`
            Body (для проверки): `{ "message": "Проверь ответы: [1, 0, 2...]" }` (формат ответов уточняется при верстке).
            Response: SSE-поток с JSON-ответом агента.

5.  **Узел «Одобрение» (не требуется):**
    *   В данном сценарии решение автоматическое (вердикт выдает агент). Узел «Одобрение пользователя» в workflow не нужен, так как результат показывается сразу сотруднику.

## 4. Примеры поведения
**Вопрос 1: Генерация теста**
*Вопрос:* «Сгенерируй тест по технике безопасности монтера»
*Ожидаемый ответ:*
```json
{
  "source_url": "https://enbek.kz/...",
  "source_title": "Типовая инструкция №45",
  "questions": [
    {
      "id": 1,
      "text": "Какое напряжение безопасно для светильников в колодце?",
      "options": ["220 В", "12 В", "380 В"],
      "correct_index": 1
    },
    ... (еще 9 вопросов)
  ]
}
```

**Вопрос 2: Проверка знаний**
*Вопрос:* «Проверь ответы: [1, 0, 2, 1, 1, 0, 2, 0, 1, 1]» (где цифры — индексы выбранных вариантов)
*Ожидаемый ответ:*
```json
{
  "score": 90,
  "verdict": "Прошел",
  "details": "Отличный результат. Ошибка допущена только в вопросе №3 про допуск в охранные зоны."
}
```

**Вопрос 3: Обработка ошибки (нет данных)**
*Вопрос:* «Сгенерируй тест» (при недоступности Яндекса или пустой выдаче)
*Ожидаемый ответ:*
```json
{
  "error": "Нет данных",
  "message": "Не удалось найти актуальные инструкции в открытых источниках. Попробуйте позже."
}
```

## 5. Как принять работу
**Чек-лист приемки агентной части:**
- [ ] Агент успешно подключается к поиску (Яндекс) и находит документы по запросу «ТБ монтер Казахстан».
- [ ] Генерируется ровно 10 вопросов с тремя вариантами ответов.
- [ ] Формат ответа — валидный JSON, который может распарсить веб-панель.
- [ ] При проверке ответов агент корректно считает процент и выдает вердикт «Прошел» (≥80%) или «Не прошел».
- [ ] В случае недоступности источника агент возвращает понятную ошибку, а не «ломается».

**Блокеры для запуска (требуют решения владельца):**
- [ ] **Контакты владельца:** ФИО и телефон для паспорта инициативы (владелец отказался предоставить на интервью).
- [ ] **Валидация источника:** Подтверждение, что «первая ссылка Яндекса» допустима для обучения сотрудников. Риск устаревших данных остается высоким.
- [ ] **Ответственность:** Письменное подтверждение, что в случае травмы сотрудника, прошедшего тест по данным из интернета, ответственность не лежит на разработчиках агента.