Референсный агент

Как устроен `policy-sync-agent`, единственный существующий внешний агент: что он делает, что объявляет платформе и какие случаи отправляет человеку.

Зачем эта страница

Протокол описывает, как платформа разговаривает с агентом. Эта страница показывает, что получается, когда протокол реализован полностью. Она полезна двумя способами: как пример для тех, кто пишет своего агента, и как справка по тому агенту, который работает сейчас.

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

Забирает из почтового ящика письма страховых компаний со списками застрахованных, читает приложенные списки, определяет, какой программе соответствует каждая строка, находит человека во внешней медицинской системе и отправляет по каждой строке типизированный запрос на прикрепление или открепление. Строки, которые решить не удалось, откладывает человеку.

Конвейер обработки

Шаг	Что происходит
Опрос почты	Опрос ящиков по расписанию агента. При первом опросе запоминается текущая позиция, поэтому старая почта не обрабатывается. Письма и вложения складываются в хранилище, повторы отсеиваются по идентификатору письма и контрольным суммам
Учёт по письму	На каждое письмо ведётся сводка: сколько вложений, сколько заданий, сколько успешных, сколько в разборе, сколько с ошибками
Создание заданий	По одному заданию на вложение
Извлечение содержимого	Способ выбирается по расширению: таблицы читаются напрямую, документы и изображения через разбор разметки с распознаванием текста
Определение типа документа	Языковая модель по отправителю, теме и содержимому определяет вид письма: прикрепление, открепление, изменение, гарантийное письмо, не по адресу или нужен человек
Извлечение полей	Для таблицы с заголовком модель определяет только смысл столбцов, а сами данные читаются детерминированно. Для неструктурированного текста работает отдельный разбор
Нормализация	Приведение имён, определение пола по отчеству, обработка франшизы, проверка того, что один список относится к одному страховщику, договору и программе
Сопоставление программы	Программа определяется по утверждённому соответствию. Ни одного совпадения или несколько означают отправку человеку
Поиск человека	Только точное совпадение. Ноль или несколько результатов означают отправку человеку
Сборка запроса	Одна строка может превратиться в несколько операций
Отправка	Результат либо успех, либо отказ внешней системы, либо неизвестный исход
Реестр и артефакты	Снимок результата, перестройка реестра по людям и трассировка конвейера

Списки на изменение человек обрабатывает всегда

Письмо, все строки которого означают изменение, во внешнюю систему не отправляется никогда: оно сразу уходит в ручной разбор. Это заложено осознанно.

Что агент объявляет платформе

Описание себя

Поле	Значение
Версия протокола	1.0
Тип	policy-sync
Версия расширения интерфейса	1.1

Возможности

Агент реализует протокол практически целиком: настройки и их схема, история событий и поток событий, задания, спорные случаи, исправление полей, выбор кандидата, безопасное возобновление, учёт писем, замена документа, почтовые ящики, реестр операций, получение модели от платформы, свои разделы интерфейса.

Встроенные страницы через iframe агент не объявляет.

Команды

Восемь команд.

Команда	Что делает
enable	Включить работу агента
disable	Выключить работу агента
validate-settings	Проверить текущие настройки
poll-now	Опросить указанный ящик прямо сейчас и обработать всё, что нашлось
retry-job	Повторить конкретное задание
check-omis-connection	Проверить связь с внешней системой
refresh-omis-catalog	Перечитать справочник программ
check-llm-connection	Проверить доступность языковой модели

Команда принимается кодом 202 и возвращает идентификатор операции. Состояния операции: принята, выполняется, успешно, ошибка, отменена. По завершении агент отправляет событие.

Разделы интерфейса

Агент объявляет пять разделов, и платформа рисует их сама.

Порядок	Раздел	Что показывает
20	Почтовые ящики	Источники писем, с полным управлением
30	Настройки	Форма по схеме агента
40	Реестр операций	По строке на человека, с выгрузкой
50	Ручной разбор	Очередь спорных случаев с действиями
60	Письма	Учёт обработки каждого письма

Дополнительно агент расширяет платформенный раздел «Задания»: добавляет свои столбцы, свои подписи состояний, раздел карточки с обменом и действие повтора задания.

Разбор всех разделов с экранами на странице Разделы карточки агента.

Ревизия описания разделов

Ревизия это отпечаток содержимого, а не счётчик. Она стабильна при перезапуске агента и меняется, только когда состав разделов действительно изменился. Описание сверяется с эталонным файлом в тестах, поэтому незамеченное изменение состава разделов невозможно.

Спорные случаи

Как случай попадает в очередь

Два пути. Первый: задание переходит в состояние, требующее человека, и случай открывается автоматически. Второй: проблема на уровне письма, когда задания ещё нет, например письмо без вложений или архив вместо таблицы.

Повторы не создают второй случай: при совпадении задания, строки, причины и ревизии контекста случай дополняется, а его версия увеличивается.

Каталог причин

Двадцать одна причина. Название причины это то, что оператор видит в столбце «Случай».

Причина	Название для оператора	Приоритет
classification_ambiguous	Нужно определить тип документа	Высокий
field_extraction_rejected	Нужно исправить распознанные поля	Высокий
normalization_validation_failed	Нужно исправить данные документа	Высокий
change_list_manual	Список на изменение, обрабатывается вручную	Обычный
program_mapping_not_found	Не найдена программа	Высокий
program_mapping_ambiguous	Нужно выбрать программу	Высокий
patient_not_found	Пациент не найден	Высокий
patient_ambiguous	Нужно выбрать пациента	Высокий
attachment_not_found	Прикрепление пациента не найдено	Высокий
attachment_ambiguous	Нужно выбрать прикрепление пациента	Высокий
equivalent_attachment_exists	Похожее прикрепление уже существует	Высокий
omis_write_disabled	Отправка отключена	Высокий
omis_operation_rejected	Внешняя система отклонила операцию	Высокий
omis_submission_recovery_required	Нужно безопасно продолжить отправку	Критический
omis_outcome_unknown	Неизвестен результат операции	Критический
processing_retry_exhausted	Автоматические попытки исчерпаны	Критический
processing_final_failure	Задание завершилось технической ошибкой	Критический
no_attachment	В письме нет вложений для обработки	Обычный
unsupported_package	Архивы не обрабатываются	Высокий
legacy_manual_review	Задание требует внимания	Высокий
tracking_violation	Документ зарегистрирован, но задание отсутствует	Критический

Причина определяет набор действий

У каждой причины свой список разрешённых действий и своя точка возобновления. Например при неоднозначной программе оператор выбирает программу, а при исчерпанных попытках доступен безопасный повтор. Платформа показывает только те действия, которые причина разрешает.

Действия оператора

Действие	Что делает у этого агента
Исправление полей	Правит распознанные значения. Разрешены 17 полей: действие, части имени, дата рождения, пол, номер полиса, даты действия, страховщик, договор, программа, работодатель, франшиза. Исходное извлечение при этом не меняется, правки ложатся отдельным слоем
Выбор программы	Выбор из предложенных вариантов. Дополнительно проверяется, что справочник и соответствие ещё действуют
Выбор пациента	Выбор из предложенных вариантов
Выбор прикрепления	Выбор из предложенных вариантов
Возобновление	Возврат случая агенту. Точку возобновления выбирает сам агент по причине случая. Если задание завершилось ошибкой, создаётся связанное восстановительное задание
Закрытие случая	Закрытие решением оператора. Допустимые виды решения зависят от причины
Загрузка замены документа	Приём исправленного файла вместо исходного. Принимаются только таблицы, размер до 20 МиБ, проверяются и расширение, и первые байты файла

Общие правила для всех изменяющих действий: обязательный ключ идемпотентности, обязательное совпадение ожидаемой версии случая, невозможность действовать на уже закрытом случае.

Подтверждение исхода

Когда результат операции во внешней системе неизвестен, оператор подтверждает исход закрытием случая с соответствующим видом решения. Возобновление такого случая агент не примет: сначала нужно подтвердить, чем всё закончилось.

Долгие действия выполняются в фоне: агент отвечает кодом 202, а состояние операции можно опрашивать отдельно. Незавершённые операции восстанавливаются при перезапуске агента.

Данные, которые уходят в платформу

Перед тем как отдать данные раздела платформе, агент вычищает всё, что похоже на пароли, ключи, токены и учётные данные: названия полей остаются, значения заменяются пометкой. Затем данные помечаются как прошедшие маскирование, потому что без этой пометки платформа их не примет.

Поля с персональными данными агент помечает отдельно, чтобы платформа могла проверить право на их просмотр.

Незаявленные параметры запроса отбрасываются, а размер страницы ограничивается и объявленным пределом раздела, и общим пределом платформы.

Состояние агента

Агент сообщает платформе признак включения, состояние, время запуска, время последней активности, число активных и очередных заданий и список деградированных составляющих.

Состояние	Когда
running	Обычная работа
stopped	Работа выключена настройкой
degraded	Нет доступной языковой модели, либо внешняя система включена, но не настроена

Работа на собственной модели вместо модели платформы деградацией не считается.