AI Assistant Configuration

The ecos-ai microservice powers the AI assistant in the Citeck platform. It integrates with external Large Language Model (LLM) providers and exposes AI functionality to other microservices via a RESTful API.

This article describes the technical details of the microservice, the procedure for configuring LLM providers, assistant configuration, and proxy connection parameters.

Note

The AI assistant requires an Enterprise license with the ai flag and the user must be a member of the GROUP_ai-feature-allowed group.

Architectural Decisions

  • Spring Boot: Microservice foundation

  • Kotlin: Main development language

  • Spring AI: Integration with AI providers

  • Ecos Records: Integration with Citeck platform

  • RESTful API: Standard HTTP endpoints for integration

Base Technical Platform

Base Tools

  • GetCurrentTimeTool: Getting current time

  • GetRecordAttributesTool: Extracting record attributes

  • GetRecordContentTool: Getting record content

  • GetRecordDisplayNameTool: Getting display names

  • GetRecordContactsTool: Extracting contact information

  • GetRecordContentHistoryTools: Content change history

  • DocumentAnalysisTool: Document analysis

  • DeployDataTypeTool: Deploying data types

  • GetArtifactMetadataTool: Artifact metadata

  • GetActivitiesTool: Working with activities

Security, Access, Authorization

  • License Control: Checking the ai flag in the license

  • Group Rights: Access control through the GROUP_ai-feature-allowed group

  • Access Control: Extended availability checks for AI functions

  • BPMN Authorization: Enhanced BPMN request processing considering user rights

Configuration

  • Proxy Support: HTTP, HTTPS and SOCKS protocols

  • Flexible Settings: Configuration through environment variables and application.yml

  • Monitoring: Logging and error tracking

Spring Profiles

For a quick start, you can use ready-made Spring profiles that contain pre-configured provider and model settings.

Profile

Description

Required env variables

ai-default

Recommended. Yandex Cloud (gpt-oss-120b) as the primary provider + Anthropic (claude-sonnet-4-6) for BPMN generation. A more intelligent model is used for BPMN generation, which ensures better process quality.

CTK_YANDEX_AI_API_KEY, CTK_YANDEX_AI_FOLDER_ID, CTK_ANTHROPIC_API_KEY

ai-yandex-gpt-oss

Yandex Cloud (gpt-oss-120b) for all assistants

CTK_YANDEX_AI_API_KEY, CTK_YANDEX_AI_FOLDER_ID

Connecting in Citeck Launcher

At the moment, to prevent the launcher settings from being overwritten when updating versions in the kit, configuration must be done through a custom application-launcher.yml. A dedicated interface for convenient AI assistant connection setup is planned for future releases.

  1. Find the ai microservice in the microservices list.

  2. Left-click on the microservice settings gear icon and add environment variables:

    • CTK_ANTHROPIC_API_KEY — for using Anthropic

    • CTK_YANDEX_AI_FOLDER_ID, CTK_YANDEX_AI_API_KEY — for Yandex AI Studio

    Note

    For the ai-yandex-gpt-oss profile, also add it to the SPRING_PROFILES_ACTIVE line.

  3. Right-click on the same settings gear and select application-launcher.yml.

  4. Paste the contents of the required profile. For example, for the ai-default configuration:

citeck:
  ai:
    base:
      model: 'gpt://${CTK_YANDEX_AI_FOLDER_ID}/gpt-oss-120b/latest'
    assistants:
      bpmn:
        model: claude-sonnet-4-6
        streaming: true
        provider: anthropic
        temperature: 0.0
        reasoning-effort: none

spring:
  ai:
    anthropic:
      api-key: '${CTK_ANTHROPIC_API_KEY}'
    openai:
      api-key: '${CTK_YANDEX_AI_API_KEY}'
      chat:
        options:
          model: 'gpt://${CTK_YANDEX_AI_FOLDER_ID}/gpt-oss-120b/latest'
        base-url: https://llm.api.cloud.yandex.net

Tip

Instead of claude-sonnet-4-6, you can specify claude-opus-4-6 for higher BPMN generation quality.

for the ai-yandex-gpt-oss profile:

citeck:
  ai:
    base:
      model: 'gpt://${CTK_YANDEX_AI_FOLDER_ID}/gpt-oss-120b/latest'
    assistants:
      bpmn:
        streaming: false

spring:
  ai:
    openai:
      api-key: '${CTK_YANDEX_AI_API_KEY}'
      chat:
        options:
          model: 'gpt://${CTK_YANDEX_AI_FOLDER_ID}/gpt-oss-120b/latest'
        base-url: https://llm.api.cloud.yandex.net

If a proxy server is required to access the AI API, add the proxy block to the configuration:

citeck:
  ai:
    proxy:
      enabled: true
      host: proxy.company.com
      port: 8080
      username: proxy-user
      password: proxy-pass
      protocol: HTTP

  1. Replace the variables ${CTK_YANDEX_AI_API_KEY}, ${CTK_YANDEX_AI_FOLDER_ID}, ${CTK_ANTHROPIC_API_KEY} with real values.

  2. Save the setting — the microservice will restart automatically.

Tip

The ai-default profile is the recommended minimum for stable assistant operation. The combination of Yandex Cloud for general tasks and Anthropic Claude for BPMN generation provides the required quality, since BPMN process generation requires a more intelligent model.

Important

When using Anthropic as a provider (e.g., for BPMN generation in the ai-default profile), network access to the Anthropic API must be available. Configure an HTTP proxy (see the Proxy Configuration section) or use a VPN.

LLM Providers

Citeck AI Assistant supports working with various Large Language Model (LLM) providers.

Supported Providers

  • openai - GPT models (gpt-5.1, etc.)

  • anthropic - Claude models (claude-opus-4-5, etc.)

  • deepseek - DeepSeek models (deepseek-chat, deepseek-coder)

  • ollama - local models (granite3.3, llama3, mistral)

Selecting the Default Provider

The default provider is specified in citeck.ai.default.provider. This provider is used for all assistants unless a specific one is specified:

citeck:
    ai:
        default:
            provider: openai  # openai, anthropic, deepseek, ollama

Important

For each assistant type, a specific provider can be set via the provider parameter. If not specified, citeck.ai.default.provider is used.

Base Model Configuration

For the system to work, a base model must be specified in citeck.ai.base.model. This model is used by default for all assistants unless a specific model is specified:

citeck:
    ai:
        base:
            model: gpt-5.1  # Базовая модель для всех ассистентов

Configuring Models for Different Assistants

Within the selected provider, each assistant type can use its own model and additional parameters:

citeck:
    ai:
        assistants:
            bpmn:
                model: gpt-5.1
                temperature: 0.1
                reasoning-effort: medium     # Уровень рассуждений: none, low, medium, high
                streaming: true              # Потоковый вывод
            universal:
                model: gpt-5.1
                temperature: 0.7
                reasoning-effort: medium
            intent-detection:
                model: gpt-5.1
                temperature: 0.1
                reasoning-effort: low
                use-native-structured-output: true  # Использовать нативный structured output
            required-content-version-selection:
                model: gpt-5.1
                temperature: 0.1
                reasoning-effort: low
            business-app-generation:       # Генерация бизнес-приложений
                model: gpt-5.1
                temperature: 0.5
                reasoning-effort: medium
                context-analyzer:          # Анализатор контекста
                    model: gpt-5.1
                    temperature: 0.1
                    use-native-structured-output: true
                description-formatter:     # Форматирование описаний
                    model: gpt-5.1
                    temperature: 0.1
                requirements-generator:    # Генератор требований
                    model: gpt-5.1
                    temperature: 0.1
                    use-native-structured-output: true

Assistant Parameters

  • provider - provider for this assistant (if not specified, citeck.ai.default.provider is used)

  • model - the model to use (must be available with the selected provider)

  • temperature - generation temperature (0.0–1.0)

  • reasoning-effort - reasoning level: none, low, medium, high

  • streaming - enable streaming output

  • use-native-structured-output - use the provider’s native structured output

  • enable-bpmn-generation - enable BPMN process generation (only for business-app-generation)

Example of Using Different Providers

citeck:
    ai:
        default:
            provider: openai           # Провайдер по умолчанию
        assistants:
            bpmn:
                provider: anthropic      # Claude для генерации BPMN
                model: claude-opus-4-5
            universal:
                # provider не указан - используется openai
                model: gpt-5.1
            intent-detection:
                provider: deepseek       # DeepSeek для быстрой классификации
                model: deepseek-chat

Note

All specified models must be available within the selected provider.

Structured Output Configuration

Retry mechanism configuration for structured output:

citeck:
    ai:
        structured-output:
            max-attempts: 3              # Максимум попыток при ошибках парсинга
            delay-ms: 500                # Начальная задержка между попытками (мс)
            use-exponential-backoff: true # Экспоненциальное увеличение задержки
            backoff-multiplier: 2.0      # Множитель увеличения задержки
            max-delay-ms: 5000           # Максимальная задержка (мс)

Configuration Examples for Main Providers

OpenAI

spring:
    ai:
        openai:
            api-key: ${OPENAI_API_KEY}

citeck:
    ai:
        default:
            provider: openai
        base:
            model: gpt-5.1
        assistants:
            bpmn:
                reasoning-effort: medium
                streaming: true
            intent-detection:
                use-native-structured-output: true

Ollama (local models)

citeck:
    ai:
        default:
            provider: ollama
        base:
            model: granite3.3
        assistants:
            bpmn:
                model: llama3

DeepSeek

spring:
    ai:
        deepseek:
            api-key: ${DEEPSEEK_API_KEY}

citeck:
    ai:
        default:
            provider: deepseek
        base:
            model: deepseek-chat
        assistants:
            bpmn:
                model: deepseek-coder

Yandex Cloud (via OpenAI-compatible API)

Tip

For Yandex Cloud it is recommended to use the ready-made profiles ``ai-default`` or ``ai-yandex-gpt-oss`` — see the Spring Profiles section above. Manual configuration is shown below.

spring:
    ai:
        openai:
            api-key: ${YANDEX_API_KEY}
            chat:
                base-url: https://llm.api.cloud.yandex.net

citeck:
    ai:
        default:
            provider: openai  # Используем OpenAI-совместимый API
        base:
            model: 'gpt://{folder_id}/gpt-oss-120b/latest'

Important

  • Replace {folder_id} with the real Yandex Cloud folder identifier

  • Yandex Cloud support via the OpenAI-compatible API is partial

  • Model format: gpt://{folder_id}/model-name/latest

  • Available models: gpt-oss-120b, and other Yandex Cloud models

  • In all citeck.ai.*.model settings, the model must be specified in Yandex Cloud format

Proxy Configuration

Citeck AI Assistant supports working through a proxy server to access external AI services.

Supported Proxy Protocols

  • HTTP - standard HTTP proxy

  • HTTPS - secure HTTPS proxy

Environment Variables

# Включение прокси
CITECK_AI_PROXY_ENABLED=true

# Настройки подключения
CITECK_AI_PROXY_HOST=your-proxy-host.com
CITECK_AI_PROXY_PORT=8080
CITECK_AI_PROXY_PROTOCOL=HTTP  # HTTP или HTTPS

# Аутентификация (опционально)
CITECK_AI_PROXY_USERNAME=your-username
CITECK_AI_PROXY_PASSWORD=your-password

Configuration Example in application.yml

citeck:
    ai:
        proxy:
            enabled: true
            host: proxy.company.com
            port: 8080
            protocol: HTTP
            username: proxy-user
            password: proxy-pass