Источники агентов

Источник агентов создаёт подключения внешних агентов по сущностям каталога. Каждая сущность привязанного ресурса становится внешним агентом: идентификатор агента берётся из идентификатора сущности, а URL карточки — из параметра сущности.

Источник не обращается к внешним системам сам: он читает сущности, которые уже есть в каталоге. Сущности агентов можно создать вручную, через API или источником данных, например синхронизацией объектов агентов kagent из Kubernetes.

Как работает источник

Портал синхронизирует каждый включённый источник при запуске backend и затем раз в минуту. Синхронизацию можно запустить вручную кнопкой «Синхронизировать сейчас».

Для каждой привязки ресурса портал выполняет шаги:

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

Название и описание агента портал берёт из его карточки, а пока карточка не прочитана — из названия и описания сущности. Карточку агента портал перечитывает, если агент новый, если изменился URL карточки или если с последнего чтения прошло больше 15 минут.

Владельцем агента и его командой-владельцем становятся владелец и команда-владелец сущности. Если у сущности они не заданы, используются владелец и команда-владелец источника.

Синхронизация отражает текущее состояние каталога целиком:

• агент, сущность которого исчезла из выборки, выключается, но не удаляется;
• если выборка пуста, выключаются все агенты источника, и это не считается ошибкой;
• если сущность снова попадает в выборку, агент включается.

Быстрый старт

Чтобы подключать агентов из каталога:

1. Создайте ресурс, сущности которого будут описывать агентов. Добавьте в ресурс параметр типа String для URL карточки агента, например agent_card_url.
2. Создайте сущности ресурса и заполните в них URL карточки. Идентификатор сущности станет идентификатором агента.
3. Перейдите в раздел «AI» → «AI-агенты» → «Источники агентов» и нажмите «Создать источник агентов». Кнопка доступна с разрешением edit:ai-agents.
4. На вкладке «Основная информация» включите «Включить источник», заполните «Название» и «Идентификатор».
5. На вкладке «Ресурсы каталога» нажмите «Добавить ресурс», выберите ресурс и в поле «Параметр с URL Agent Card» выберите параметр с URL карточки.
6. На вкладке «Подключение» укажите «API-ключ», общий для всех агентов источника.
7. Нажмите «Сохранить», затем в меню карточки источника выберите «Синхронизировать сейчас».

После синхронизации портал покажет уведомление «Синхронизировано: создано {created}, обновлено {updated}, пропущено {skipped}», а агенты появятся в разделе «Каталог» с отметками «Внешний» и «Из источника».

Параметры источника

Форма источника состоит из вкладок «Основная информация», «Ресурсы каталога» и «Подключение».

Основная информация

На вкладке «Основная информация» задаются поля:

Ресурсы каталога

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

Для каждой привязки задаются поля:

Портал проверяет при сохранении, что ресурс существует и указанные параметры объявлены в ресурсе.

Параметр включения

Если параметр включения задан, сущность пропускается, когда параметр не заполнен или его значение — false, 0, no или off в любом регистре. Любое другое значение считается включённым.

Правила фильтрации

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

Каждое правило состоит из полей:

• «Действие» — «Оставить только совпадения» или «Убрать совпадения»;
• «Источник» — путь к полю сущности в формате Go-шаблона;
• «Условие» — регулярное выражение, по которому проверяется значение поля.

В поле «Источник» сущность доступна через корень .entity:

{{ .entity.slug }}
{{ .entity.name }}
{{ .entity.description }}
{{ .entity.properties.environment }}

Например, чтобы синхронизировать только агентов production-окружения, добавьте правило с действием «Оставить только совпадения», источником {{ .entity.properties.environment }} и условием ^production$.

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

Подключение

Параметры вкладки «Подключение» применяются ко всем агентам источника:

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

Агенты из источника

У агента из источника портал при каждой синхронизации задаёт адрес карточки, API-ключ, «Вызывать адрес из карточки агента» и «MCP-инструменты» по настройкам источника. В подключении такого агента вручную меняются только переключатель «Включить агента» и «Разрешить прокси моделей DDP».

Если агенту нужен прокси моделей DDP, включите «Разрешить прокси моделей DDP» в подключении агента после первой синхронизации: источник этот переключатель не меняет.

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

Результаты синхронизации

Кнопка «Синхронизировать сейчас» возвращает результат по каждому агенту. Уведомление показывает число созданных, обновлённых и пропущенных агентов; к пропущенным относятся все результаты, кроме создания и обновления.

Причины, по которым агент пропущен или требует проверки:

Выключение и удаление источника

Выключенный источник не синхронизируется. Созданные им агенты остаются в текущем состоянии.

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