ii-agent-ekspress-testirovan/alem_guide.md at main

yerzhan_assanov/ii-agent-ekspress-testirovan

Fork 0

yerzhan_assanov e5b1b13e79 v1: прототип экспресс‑теста ОТ с Alem

2026-07-22 12:35:21 +00:00

12 KiB

Raw Permalink Blame History

1. Почему Alem, а не отдельная разработка

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

2. Что делает агент

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

3. Пошаговое создание в Alem

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

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

# ИСТОЧНИКИ ДАННЫХ
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.
- Не сохраняй данные пользователя. Работай в режиме "здесь и сейчас".

База знаний (опционально):
- Если владелец решит снизить риск «плохих ссылок», загрузите в раздел Базы знаний актуальный PDF «Правила по охране труда при эксплуатации линейно-кабельных сооружений» и в промпте укажите: «Используй в первую очередь базу знаний, если там нет ответа — ищи в Яндекс».
Публикация и канал 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-ответом агента.
Узел «Одобрение» (не требуется):
- В данном сценарии решение автоматическое (вердикт выдает агент). Узел «Одобрение пользователя» в workflow не нужен, так как результат показывается сразу сотруднику.

4. Примеры поведения

Вопрос 1: Генерация теста Вопрос: «Сгенерируй тест по технике безопасности монтера» Ожидаемый ответ:

{
  "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]» (где цифры — индексы выбранных вариантов) Ожидаемый ответ:

{
  "score": 90,
  "verdict": "Прошел",
  "details": "Отличный результат. Ошибка допущена только в вопросе №3 про допуск в охранные зоны."
}

Вопрос 3: Обработка ошибки (нет данных) Вопрос: «Сгенерируй тест» (при недоступности Яндекса или пустой выдаче) Ожидаемый ответ:

{
  "error": "Нет данных",
  "message": "Не удалось найти актуальные инструкции в открытых источниках. Попробуйте позже."
}

5. Как принять работу

Чек-лист приемки агентной части:

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

Блокеры для запуска (требуют решения владельца):

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