Внешние агенты

Как подключить внешнего агента, как проверить связь, что показывает его карточка и какие права для этого нужны.

Как читать этот раздел

Здесь про подключение и про два раздела, которые есть у любого агента. Разделы, которые объявляет конкретный агент, описаны отдельно: Агент policy-sync-agent.

Что такое внешний агент

Отдельная программа, которая работает вне платформы и делает свою работу сама. EVA выступает для неё пультом управления: регистрирует, следит за состоянием, передаёт настройки, посылает команды, собирает поток её событий.

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

Это не то же самое, что «Агенты» в чате

В платформе два разных понятия со словом «агент». «Агенты» это профили поведения ИИ для переписки, они живут внутри EVA. «Внешние агенты» это самостоятельные программы вне EVA. Общего между ними ничего, кроме слова.

Где находится

Раздел администрирования, вкладка Внешние агенты.

Список внешних агентов

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

Список агентов

Таблица называется Агенты, рядом с заголовком число записей.

Столбец	Что показывает
Название	Имя агента. Если была ошибка, рядом появляется жёлтый значок, при наведении видно её текст
Base URL	Адрес управляющего API. Полный адрес видно при наведении
Статус	Состояние по последней проверке
Включён	Переключатель синхронизации событий
Проверен	Когда платформа последний раз связывалась с агентом
Действия	Проверить соединение, изменить, удалить

Нажатие на строку открывает карточку агента. Если агентов нет, вместо таблицы подсказка о том, что нужно подключить агента.

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

Статус	Что означает
Черновик	Агент зарегистрирован, соединение ещё не проверялось
Готов	Проверка прошла, агент отвечает
Деградация	Агент отвечает, но сообщает о неполной готовности
Отключён	Синхронизация выключена вручную
Ошибка	Связаться не удалось, рядом сохраняется текст ошибки

В карточке статус выглядит иначе

В списке статус подписан по-русски, а в заголовке карточки агента показывается техническое значение латиницей: ready, degraded, failed, disabled, draft. Это одно и то же состояние.

Подключение агента

Кнопка Подключить агента в правом верхнем углу.

Форма подключения внешнего агента

Поле	Что задаёт
Название	Отображаемое имя, например «Research Agent»
Base URL	Адрес управляющего API. Подсказка требует, чтобы адрес оканчивался на `/agent-api/v1`
Service token	Токен, который платформа передаёт агенту при каждом обращении. Подсказка поясняет, что он передаётся заголовком `Authorization: Bearer` и хранится зашифрованным по AES-256-GCM
Включить синхронизацию событий	Начинать ли сразу читать поток событий агента

Кнопки внизу: Отмена и Подключить агента. При изменении существующего агента вторая называется Сохранить.

Токен при изменении можно не вводить

Если оставить поле токена пустым при редактировании, прежний токен сохранится. В подсказке поля так и написано.

Требования к адресу

Только http или https. Нельзя указывать данные для входа в адресе, нельзя добавлять параметры запроса и якорь. Косая черта на конце срезается сама.

Проверка соединения

Кнопка есть и в строке списка, и в заголовке карточки агента. Платформа запрашивает у агента его описание и готовность.

Результат	Что увидите
Успех	Сообщение о том, что соединение установлено и агент готов
Агент ответил отказом	Предупреждение о непройденной проверке с текстом от агента
Связаться не удалось	Ошибка с текстом сбоя

При успешной проверке из карточки платформа заодно перезапрашивает описание разделов агента.

Что можно делать в списке

Действие	Как
Зарегистрировать агента	Кнопка Подключить агента
Изменить	Значок карандаша в строке
Включить или выключить синхронизацию	Переключатель в столбце Включён, применяется сразу, без подтверждения
Проверить связь	Значок в строке
Удалить	Значок корзины, платформа спросит подтверждение с именем агента
Открыть карточку	Нажать на строку

Карточка агента

Карточка агента policy-sync-agent, раздел «Обзор»

В заголовке имя агента, состояние, адрес и кнопка Проверить соединение. Слева меню разделов, справа содержимое выбранного. На снимке карточка агента policy-sync-agent, у другого агента состав разделов будет иным.

Откуда берутся разделы

Это главная особенность, и её важно понять правильно.

Общих разделов всего два

Всегда и у любого агента есть только «Обзор» и «Задания». Все остальные разделы появляются, только если агент сообщил о себе соответствующие сведения, поэтому карточка у каждого агента своя. Универсального описания карточки не существует.

Раздел	Когда появляется
Обзор	Всегда
Задания	Всегда. Агент может добавить свои столбцы, свои подписи состояний, свои разделы карточки задания и свои действия над строкой
Разделы, объявленные агентом	Столько, сколько он объявил, в заданном им порядке
Настройки	Если агент отдаёт схему своих настроек и при этом не объявил своей формы настроек
Реестр операций	Если агент объявил такую возможность и не объявил своего раздела с этим именем
Ручной разбор	То же правило
Журнал	Если агент ведёт историю событий

Правило вытеснения

Раздел, объявленный агентом, всегда вытесняет платформенный вариант с тем же именем. Платформенные «Настройки», «Реестр операций» и «Ручной разбор» это упрощённая замена на случай, если агент своего раздела не дал.

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

Пример живой карточки

У агента policy-sync-agent получается восемь разделов: два общих, «Журнал», потому что агент ведёт историю событий, и пять своих. Полный разбор с экранами на странице Карточка агента policy-sync-agent.

Основные разделы

Их два, и они есть у любого внешнего агента, что бы он о себе ни сообщил.

Обзор

Раздел «Обзор»

Четыре плитки сверху:

Плитка	Что показывает
Состояние	Техническое состояние агента: `starting`, `running`, `degraded`, `stopped`
Активные задания	Сколько работ выполняется сейчас
В очереди	Сколько ждёт
Последняя активность	Когда агент последний раз что-то делал

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

Затем карточка Модель для агента, см. следующий раздел страницы, и карточка Паспорт интеграции:

Строка	Что показывает
Тип	Тип агента из его описания
Instance ID	Идентификатор экземпляра
EACP	Версия протокола
UI-расширение	Версия расширения интерфейса либо пометка, что оно не объявлено
Версия	Версия самого агента
Последняя проверка	Дата и время
Service token	Настроен или не используется

Если в описании разделов агента нашлись замечания, ниже появится карточка Замечания к описанию разделов со списком: степень серьёзности, место и текст.

Задания

Все запуски работы агента. Подпись на экране объясняет устройство: базовые поля одинаковы для любого агента, а остальные столбцы агент описывает сам.

Базовые столбцы, которые есть всегда:

Столбец	Что показывает
Задание	Начало идентификатора задания
Тип	Вид задания
Статус	Состояние задания
Этап	На каком шаге находится
Создано	Дата и время
Длительность	Сколько заняло, платформа считает сама
Прогресс	Сделано из общего, с единицей измерения
Ошибка	Текст ошибки, полный виден при наведении

Управление: выбор статуса, кнопка обновления, подгрузка по 100 записей кнопкой Показать ещё. Нажатие на строку раскрывает карточку задания с разделом Базовые поля: тип, статус, этап, время создания и обновления.

Что агент может добавить в этот раздел

Свои столбцы, свои подписи состояний, свои фильтры, свои разделы карточки задания и свои действия над строкой. Поэтому у конкретного агента столбцов будет больше, чем в таблице выше. Пример на странице Агент policy-sync-agent.

Действие над строкой платформа скрывает, если у оператора нет права, которое агент указал для этого действия.

Модель для агента

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

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

Что показывается	Пример
Модель EVA	Какая модель выдана
Ключ	Начало служебного ключа
Ревизия	Номер версии привязки
Изменено	Когда и кем
Служебный аккаунт	Идентификатор служебной учётной записи агента

Ниже форма параметров: модель, режим структурированного вывода, максимум токенов, температура, top_p, таймаут в секундах, число повторов.

Три кнопки: Сохранить и отправить, Ротация ключа, Отозвать.

Что происходит с ключом

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

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

Права

Для внешних агентов в правах два объекта.