Платформенный агент

Платформенный агент — AI-агент с идентификатором ddp-agent, который разворачивается вместе с порталом. По умолчанию именно он отвечает в AI-ассистенте и в виджете «AI-чат», его же можно выбрать в элементе процесса «AI-агент».

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

Как разворачивается агент

Модуль development-platform разворачивает агента в неймспейсе d8-development-platform как Deployment agent. Агент доступен только внутри кластера по адресу http://agent:8080, Ingress для него не создаётся.

Агент не настраивается в ModuleConfig:

• модуль один раз генерирует API-ключ агента и сохраняет его в Secret agent-secret-envs; при обновлении модуля ключ не меняется;
• при запуске backend и затем раз в минуту портал проверяет подключение ddp-agent и, если его нет, создаёт; если адрес карточки, ключ или базовый набор инструментов изменились, портал восстанавливает их.

Агент не хранит доступов к языковой модели: на каждый запуск портал передаёт ему доступ к прокси моделей DDP и AI-провайдера пользователя, который запустил задачу. Подробнее — в разделе «Языковая модель агента».

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

Чтобы пользователи могли работать с платформенным агентом:

1. Убедитесь, что агент работает. Выполните запрос к эндпоинту состояния портала:

   curl -s https://<DOMAIN>/healthz

   где <DOMAIN> — домен портала. В ответе поле agents должно иметь значение ok.

2. Выдайте пользователям роль с глобальным разрешением run:ai-agents. Для доступа к разделу «AI» добавьте в роль view:ai-page. Подробнее о ролях — в разделе «Ролевая модель».

3. Подготовьте AI-провайдера, совместимого с OpenAI Chat Completions. Создайте шаблон AI-провайдера с общим токеном или попросите пользователей подключить провайдера в профиле, как описано в разделе «Подключение AI-провайдера».

4. Откройте AI-ассистент: агент выбран в поле «Агент», провайдер — в поле рядом с полем ввода.

Значения поля agents

Поле agents в ответе эндпоинта /healthz показывает состояние платформенного агента и не влияет на общий статус портала:

Чтобы проверить состояние пода агента, выполните команду:

d8 k -n d8-development-platform get pods -l app=agent

Инструменты агента

Платформенному агенту всегда доступны встроенные инструменты портала, которые только читают данные:

• get_resources;
• get_resource_entities;
• get_entity;
• get_entity_relations;
• get_actions;
• get_datasources;
• get_processes;
• get_external_services;
• get_process_instances;
• get_process_instance.

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

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

Добавление инструментов

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

Чтобы добавить инструменты платформенному агенту:

1. Войдите в портал как супер-администратор.
2. Перейдите в раздел «AI» → «AI-агенты» → «Каталог».
3. В меню карточки агента с отметкой «Платформенный» выберите «Редактировать».
4. На вкладке «Подключение» добавьте инструменты в поле «MCP-инструменты».
5. Нажмите «Сохранить».

Добавленные инструменты сохраняются при проверках подключения.

Изменяемые параметры

В подключении платформенного агента изменяются только «Название», «Описание», «Включить агента» и «MCP-инструменты». Идентификатор, адрес карточки и API-ключ задаёт модуль, их нельзя изменить. Подключение нельзя удалить.

Если выключить переключатель «Включить агента», агент перестаёт отображаться в AI-ассистенте, виджетах и шагах процессов. Портал не включает агента обратно при проверке подключения.

Устранение неполадок

Агент недоступен

Если в AI-ассистенте отображается ошибка «Не удалось получить Agent Card внешнего агента. Проверьте URL карточки и доступность агента.» или «Внешний агент недоступен (ошибка сети или таймаут). Попробуйте позже.»:

1. Проверьте поле agents в ответе /healthz.

2. Проверьте, что под agent запущен и находится в состоянии Running.

3. Если под перезапускается, посмотрите его логи:

   d8 k -n d8-development-platform logs deploy/agent

Не настроен AI-провайдер

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

Если провайдер есть, но агент не может ответить, проверьте провайдера:

• в провайдере заданы модель и токен;
• URL провайдера указывает на API, совместимый с OpenAI Chat Completions, и оканчивается на /v1 или /v1/chat/completions.

Текст ошибки запуска отображается в истории запусков.

Недостаточно прав

Ошибка «Недостаточно прав для запуска этого AI-агента» означает, что у пользователя нет разрешения run:ai-agents. Добавьте разрешение в роль пользователя.