Пользовательские AI-агенты 

Агент — конфигурируемая сущность в Citeck с системным промптом, LLM-провайдером и набором инструментов. Хранится как Citeck-запись типа emodel/ai-agent.

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

Модель данных 

Модель данных определена в AgentDefinition.kt:

Поле	Тип	Обязательное	Описание
`name`	TEXT	да	Отображаемое имя агента
`instruction`	TEXT	да	Системный промпт
`aiProvider`	TEXT	да	Идентификатор LLM-провайдера
`aiModel`	TEXT	да	Идентификатор модели
`temperature`	NUMBER	нет	Степень случайности генерации: `0.0` — детерминированный вывод (модель всегда выбирает наиболее вероятный токен), `1.0` — высокая вариативность ответов. Значения выше `1.0` допускаются, но увеличивают риск несвязного текста. Рекомендуемый диапазон: `0.0`–`0.3` для фактических задач (резюме, извлечение данных), `0.6`–`0.9` для диалоговых агентов. По умолчанию `0.7`.
`tools`	TEXT[]	нет	Список подключённых инструментов
`enabled`	BOOLEAN	нет	Включён ли агент (по умолчанию `false`)

Режимы выполнения 

Stateless 

Один запрос — один ответ, без памяти о предыдущих сообщениях. Используется в BPMN-процессах через POST /api/ai-agent/execute.

Вызывается через AgentExecutionService.execute.

Предупреждение

На stateless-пути нет HITL-подтверждения. Tool-вызовы выполняются под техническим пользователем Camunda, что фактически обходит Citeck record-level permissions. Не добавляйте деструктивные инструменты (mutateRecord, deleteRecords) агентам без отдельного дизайна авторизации.

Stateful / Interactive 

Многоходовой диалог с ChatMemory, требует conversationId. Используется в AI Assistant UI.

Вызывается через AgentExecutionService.executeInteractive.

REST API 

Метод	URL	Описание
`GET`	`/api/ai-agent/available-providers`	Список подключённых LLM-провайдеров
`GET`	`/api/ai-agent/available-tools`	Инструменты, доступные агентам
`POST`	`/api/ai-agent/execute`	Stateless вызов: `{agentId, message, context}` → `{response}`
`GET`	`/api/ai-agent/list`	Список включённых агентов

Доступные инструменты 

По умолчанию isAvailableForAgents() = true. Недоступны для агентов (переопределяют в false) внутренние служебные инструменты — SaveFormDraftTool, SaveDataTypeDraftTool, SaveEscalationTool и аналогичные.

Инструмент	Описание
`GetRecordAttributesTool`	Атрибуты записи
`GetRecordContentTool`	Содержимое документа
`GetRecordContentHistoryTools`	История версий
`GetRecordDisplayNameTool`	Отображаемое имя
`GetRecordTypeMetadataTool`	Метаданные типа
`GetRecordContactsTool`	Контакты записи
`QueryRecordsTool`	Поиск записей
`MutateRecordTool`	Изменение записи
`DeleteRecordsTool`	Удаление записей
`GetActivitiesTool`	Активности
`GetEcosAppContentTool`	Содержимое ECOS-приложения
`GetArtifactMetadataTool`	Метаданные артефакта
`SearchDocumentationTool`	Поиск в документации
`RagSearchTool` / `RagGetDocumentTool`	RAG-поиск (если включён)
`DocumentAnalysisTool`	Анализ документов
`GetCurrentTimeTool`	Текущее время

Создание агента 

Через UI 

В рабочем пространстве администратора в разделе AI перейдите в журнал AI Агенты:

Заполните Название, Системный промпт, выберите Провайдер LLM и Модель.
Опционально: добавьте инструменты, установите Температуру.
Установите чекбокс Включён и сохраните.

Citeck-артефакты 

Артефакты агента расположены в следующих файлах:

Артефакт	Путь
Тип	`src/main/resources/eapps/artifacts/model/type/ai-agent.yml`
Журнал	`src/main/resources/eapps/artifacts/ui/journal/ai-agents-journal.yml`
Форма	`src/main/resources/eapps/artifacts/ui/form/ai-agent-form.json`

Создание собственного инструмента 

Реализуйте интерфейс CiteckAiTool и пометьте класс как Spring-компонент:

@Component
class MyCustomTool(
    private val someService: SomeService
) : CiteckAiTool {
    companion object {
        const val NAME = "my_custom_tool"
    }

    override fun getName(): String = NAME
    override fun getDescription(): String = "Описание для LLM"

    @Tool(name = NAME, description = "Описание для LLM")
    fun myAction(param: String): String {
        return someService.doSomething(param)
    }
}

Spring DI автоматически обнаружит инструмент через List<CiteckAiTool> и добавит в список доступных.

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

override fun isAvailableForAgents(): Boolean = false

Маршрутизация в оркестраторе 

AgentOrchestratorService.processRequest() — первый приоритет маршрутизации: если к разговору привязан агент (resolveAgentRef), вся обработка делегируется AgentExecutionService.executeInteractive(), минуя Intent Detection и Plan-and-Execute.

Ключевые файлы 

Компонент	Файл
Модель данных	`src/main/java/ru/citeck/ecos/ai/domain/agent/AgentDefinition.kt`
Реестр агентов	`src/main/java/ru/citeck/ecos/ai/domain/agent/AgentRegistry.kt`
Сервис выполнения	`src/main/java/ru/citeck/ecos/ai/domain/agent/AgentExecutionService.kt`
REST-контроллер	`src/main/java/ru/citeck/ecos/ai/domain/agent/AgentController.kt`
Интерфейс инструментов	`src/main/java/ru/citeck/ecos/ai/domain/assistant/tools/CiteckAiTool.kt`
ECOS-тип	`src/main/resources/eapps/artifacts/model/type/ai-agent.yml`
ECOS-журнал	`src/main/resources/eapps/artifacts/ui/journal/ai-agents-journal.yml`
ECOS-форма	`src/main/resources/eapps/artifacts/ui/form/ai-agent-form.json`