141 lines
12 KiB
Markdown
141 lines
12 KiB
Markdown
## 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%) или «Не прошел».
|
||
- [ ] В случае недоступности источника агент возвращает понятную ошибку, а не «ломается».
|
||
|
||
**Блокеры для запуска (требуют решения владельца):**
|
||
- [ ] **Контакты владельца:** ФИО и телефон для паспорта инициативы (владелец отказался предоставить на интервью).
|
||
- [ ] **Валидация источника:** Подтверждение, что «первая ссылка Яндекса» допустима для обучения сотрудников. Риск устаревших данных остается высоким.
|
||
- [ ] **Ответственность:** Письменное подтверждение, что в случае травмы сотрудника, прошедшего тест по данным из интернета, ответственность не лежит на разработчиках агента. |