Настроить вызов AI-операции в ELMA365

После того как вы создали AI‑операцию и отладили её работу в тестовом чате, настройте её использование в ELMA365. AI‑операции можно вызывать:

в ходе бизнес процесса — с помощью блока AI‑Операция;
в интерфейсах — с помощью виджета Вызов AI‑Операции, который можно разместить на формах, на страницах, в виджетах;
в скриптах — с помощью API.

Блок и виджет для вызова AI‑операций добавляются в систему при установке решения для интеграции с ELMA Cortex.

Вызов AI-операции в бизнес-процессе

AI‑операцию можно автоматически запускать в ходе процесса. Для этого на схему процесса добавляется специальный блок AI-Операция.

Допустим, в компании по каждому новому входящему письму запускается бизнес-процесс, в ходе которого сотруднику ставится задача отправить клиенту ответ. Чтобы сотрудники вели переписку более эффективно, в процесс можно добавить AI‑операцию для анализа содержания писем с помощью искусственного интеллекта до отправки ответа оператором.

AI‑операция получает в качестве входных данных тему и текст письма и формирует на их основе краткое содержание и предполагаемый ответ для клиента. Эти данные можно отобразить в задаче сотрудника.

Для этого нужно:

добавить свойства для передачи входных данных и отображения результата в контекст приложения и процесса;
разместить на схеме процесса блок для вызова AI‑операции и настроить его.

Рассмотрим эти шаги и настройку процесса подробнее.

Шаг 1. Добавить свойства для входных и выходных данных

Убедитесь, что в контексте приложения Входящие письма созданы поля типа Строка (текст) для хранения темы и текста письма — Название и Текст.

Свойства для входных данных должны заполняться значениями до перехода процесса к блоку AI‑Операция. В нашем примере используются данные из элемента приложения, по которому запускается процесс, поэтому нужные свойства заполняются до его начала. В контекст процесса нужно добавить свойства, в которые будет записываться результат выполнения AI‑операции.

Откройте процесс обработки входящих писем в дизайнере бизнес-процессов и перейдите на вкладку Контекст.
Чтобы результат выполнения AI‑операции можно было отобразить в задаче оператора, добавьте в контекст процесса переменные типа Строка (текст) — Краткое содержание и Рекомендации.
Вынесите поля с результатом на форму задачи пользователя, дважды нажав на неё на схеме и добавив их на вкладке Форма.

Шаг 2. Настроить блок вызова AI-операции

Для корректной работы блока задайте исходящие переходы и передачу данных между блоком и процессом. Для этого:

В режиме моделирования процесса выберите на правой панели вкладку Интеграции и добавьте на схему процесса блок AI‑Операция.
Для корректной работы блока нужно предусмотреть обработку возможных ошибок, поэтому добавьте для него два исходящих перехода — для основного течения процесса и в случае ошибки.

В нашем примере оба перехода ведут к задаче пользователя Ответить на письмо, так как она должна назначаться в любом случае. Если результат от AI‑операции не получен, сотрудник выполнит задачу, изучив обращение и написав ответ вручную.

call-ai-action-1

Дважды нажмите на блок AI‑Операция, чтобы открыть его настройки.
Перейдите на вкладку Настройки действия и выберите нужную операцию из списка.
Настройте передачу данных между процессом и AI‑операцией, сопоставив свойства в появившихся колонках. Особенности сопоставления зависят от того, какой формат передачи входных данных и схемы ответа настроен для выбранной на предыдущем шаге AI‑операции в ELMA Cortex:

Текст — для этого формата при сопоставлении доступно одно поле AI‑операции: для входных данных — input_text, для схемы ответа — output_text. Напротив него выберите из контекста процесса переменную типа Строка, в которой содержится текст для обработки или в которую нужно записать результат;
Произвольный JSON — для сопоставления доступно одно поле AI‑операции: для входных данных — input_json, для схемы ответа — output_json. Выберите из контекста процесса переменную типа Строка, в которой содержится JSON‑объект с полями для обработки или в которую нужно записать результат;
Строгая схема JSON — отобразятся поля из JSON‑схемы AI‑операции, которые нужно сопоставить с переменными из контекста процесса. Типы данных должны совпадать.

call-ai-action-2

На вкладке Обработка ошибок включите опцию Прервать и выберите переход, добавленный для обработки ошибок.
Нажмите Сохранить.
Сохраните и опубликуйте процесс.

Теперь при каждом запуске процесса AI‑операция будет автоматически выполняться на основе данных, переданных из письма клиента, а её результат отобразится в задаче сотрудника для отправки ответа.

Вызов AI-операции вручную из интерфейса ELMA365

Чтобы пользователь смог применить AI‑операцию, нажав кнопку на форме, странице и т. д., в дизайнере интерфейсов размещается специальный виджет Вызов AI‑Операции.

Допустим, в карточке обращения оператор читает запрос клиента и указывает требования к формату ответа. Затем нажимает кнопку, чтобы вызвать настроенную AI-операцию и получить текст с анализом обращения. Например, он может запросить данные в виде списка или готовый ответ для клиента. Если сотрудник не добавляет требования, по умолчанию формируется краткое содержание.

Чтобы настроить вызов этой AI‑операции с карточки обращения, нужно:

добавить свойства для передачи входных данных и отображения результата в контекст приложения и в дизайнере интерфейсов при настройке формы;
разместить на форме виджет для вызова AI‑операции и настроить его.

Рассмотрим шаги подробнее.

Шаг 1. Добавить свойства для входных и выходных данных

Перейдите в настройки форм приложения Обращения и убедитесь, что в его контекст добавлены свойства для хранения данных обращения — Название и Текст.
Перейдите в расширенный режим настройки форм и откройте форму просмотра приложения в дизайнере интерфейсов.
Добавьте на вкладке Контекст свойства типа Строка (текст), необходимые для работы AI‑операции — Дополнительные требования для анализа и Результат анализа.
На вкладке Шаблон разместите добавленные свойства на форме.
Настройте поле Результат анализа так, чтобы пользователь мог только просматривать его значение после выполнения AI‑операции. Для этого выберите его в шаблоне формы и нажмите значок шестерёнки, затем включите опции Только для чтения и Скрывать, если не заполнено.

Шаг 2. Настроить виджет для вызова AI-операции

Разместите на форме виджет Вызов AI‑Операции.
В открывшемся окне настройки виджета выберите из списка нужную AI‑операцию.
Настройте передачу входных и выходных данных AI‑операции, сопоставив свойства операции и виджета в появившихся колонках.

Особенности сопоставления зависят от того, какой формат передачи входных данных и схемы ответа настроен для выбранной на предыдущем шаге AI‑операции в ELMA Cortex:

Текст — для этого формата при сопоставлении доступно одно поле AI‑операции: для входных данных — input_text, для схемы ответа — output_text. Напротив него выберите из контекста виджета переменную типа Строка, в которой содержится текст для обработки или в которую нужно записать результат;
Произвольный JSON — для сопоставления доступно одно поле AI‑операции: для входных данных — input_json, для схемы ответа — output_json. Выберите из контекста виджета переменную типа Строка, в которой содержится JSON‑объект с полями для обработки или в которую нужно записать результат;
Строгая схема JSON — отобразятся поля из JSON‑схемы AI‑операции, которые нужно сопоставить с переменными из контекста виджета. Типы данных должны совпадать.

call-ai-action-3

Нажмите Сохранить.

call-ai-action-4

Нажмите на верхней панели дизайнера интерфейсов Сохранить и Опубликовать.

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

Вызов AI-операции из скрипта в ELMA365

AI‑операцию можно запустить из скрипта, настроенного на уровне любого компонента ELMA365.

Допустим, на форме обращения пользователь должен получать его краткое содержание при нажатии кнопки, но вам не подходит вид стандартного виджета для вызова AI‑операции. Вы можете настроить на форме приложения Обращения пользовательскую кнопку с нужным названием и иконкой. При её нажатии запускается скрипт выполнения AI‑операции.

Для этого нужно:

добавить свойства для передачи входных данных и отображения результата на форме;
написать серверный скрипт для вызова AI-операции из ELMA Cortex;
задать клиентский скрипт, который передаёт входные данные, запускает серверный скрипт и отображает результат на форме;
привязать клиентский скрипт к кнопке.

Рассмотрим эти шаги подробнее. В нашем примере используется AI‑операция, которая получает во входных данных текст обращения и возвращает краткое содержание также в формате текста.

Шаг 1. Добавить свойства для входных данных и отображения результата

Откройте настройки формы приложения Обращения и убедитесь, что в его контексте есть свойство для хранения текста обращения. В нашем примере это поле типа Строка (текст) с названием Текст обращения (request_text).
В расширенном режиме настройки форм откройте форму просмотра приложения в дизайнере интерфейсов.
Перейдите на вкладку Контекст и добавьте свойство типа Строка (текст) для отображения результата выполнения AI‑операции — Результат анализа (analysis_result).
На вкладке Шаблон вынесите поле для отображения результата на форму.
Откройте настройки поля, выбрав его в шаблоне формы и нажав значок шестерёнки.
Включите опции Только для чтения и Скрывать, если не заполнено.

Шаг 2. Написать серверный скрипт для вызова AI-операции

Перейдите на вкладку Скрипты и в правом верхнем углу выберите опцию Сервер.
Напишите скрипт:

Скрипт для вызова AI-операции

// Статусы выполнения AI-операции
type ActionStatus = 'Pending' | 'Success' | 'Failure' | 'Running';

// Поддерживаемые типы данных
type DataType = 'JSON' | 'Text';

// Контейнер для входных и выходных данных
interface DataContent<T = any> {
    type: DataType;
    data: T;
}

// Структура информации о запуске
interface ActionRun {
    run_id: string;
    thread_id: string;
    input: DataContent[];
    output: DataContent[];
    status: ActionStatus;
    problem: string | null;
    tracing?: {
        execution: {
            trace_id: string | null;
        };
    };
}

// Интерфейсы для API (Request/Response)

// Структура для запроса запуска AI-операции
interface StartActionRequest {
    input: DataContent[];
}

// Структура для ответа запуска AI-операции
interface StartActionResponse {
    model: ActionRun;
}

// Проверка результата — ответ от GET-запроса
interface GetActionStatusResponse extends ActionRun { }

// Константы для хранения настроек подключения к ELMA Cortex и параметров для запросов
const CONSTANTS = {
    BASE_URL: "https://<домен_ELMA_Cortex>",             // URL вашего сервера ELMA Cortex
    TOKEN: "2xd2szkub9nf2iu8fk85le7h2e9r0c99",           // Ключ из раздела API-ключи в ELMA Cortex
    AGENT_CODE: "agn-000000",                            // Ключ нужной AI-операции из её настроек с вкладки API-ключи
    API_PATHS: {
        GENERAL_FILES: "/api/pub/v1/general/files/json", // Путь для генерации файла в ELMA Cortex
        AGENT_RUNS: "/api/pub/v1/agent/runs",            // Путь запуска AI-операции
    },
    HEADERS: {                                           // Данные заголовков
        X_TOKEN: "x-token",
        CONTENT_TYPE: "Content-Type",
        APPLICATION_JSON: "application/json",
        AUTHORIZATION: "Authorization"
    },
    AGENT_RUN_STATUS: {                                  // Статусы запуска AI-операции
        SUCCESS: "SUCCESS",
        PENDING: "PENDING",
        FAILURE: "FAILURE",
        RUNNING: "RUNNING",
    },
    HTTP_METHOD: {                                       // Используемые HTTP-методы
        POST: "POST",
        GET: "GET"
    }
};

// Запуск AI-операции и передача входных данных
// Возвращается ID запуска
async function cortexCall(userData: string): Promise<string> {
    const inputs: DataContent[] = await buildAgentInputs(userData);
    const requestBody: StartActionRequest = { input: inputs };

    const url = `${CONSTANTS.BASE_URL}${CONSTANTS.API_PATHS.AGENT_RUNS}?f_agent_external_id=${CONSTANTS.AGENT_CODE}`;
    const response = await fetch(url, {
        method: CONSTANTS.HTTP_METHOD.POST,
        headers: {
            [CONSTANTS.HEADERS.X_TOKEN]: CONSTANTS.TOKEN,
            [CONSTANTS.HEADERS.CONTENT_TYPE]: CONSTANTS.HEADERS.APPLICATION_JSON
        },
        body: JSON.stringify(requestBody)
    });

    if (!response.ok) {
        throw new Error(`[Ошибка:callAiAction:Ошибка запроса]: ${response.status} ${response.statusText}`);
    }

    const dataResponse = await response.json() as StartActionResponse;
    if (dataResponse.model.problem) {
        throw new Error(`[Ошибка:callAiAction]: ошибка при запросе агентов: ${JSON.stringify(dataResponse.model.problem)}`);
    }

    return dataResponse.model.run_id;
}

// Формирование тела запроса для запуска AI-операции на основе входных данных
async function buildAgentInputs(inputData: any): Promise<DataContent[]> {
    const inputs: DataContent[] = [];
    const jsonData: any = {};

    // Обработка входных данных для использования в ELMA Cortex
    jsonData.request_text = processPrimitiveField(inputData);

    if (Object.keys(jsonData).length > 0) {
        inputs.push({
            type: "JSON",
            data: jsonData
        });
    }

    return inputs;
}

// Обработка примитивных типов данных
function processPrimitiveField(bindData: any): any {
    switch (typeof bindData) {
        case "number": return Number(bindData);
        case "boolean": return Boolean(bindData);
        case "undefined": return null;
        case "string":
        default: return bindData;
    }
}

// Проверка статуса запуска AI-операции
async function checkStatusAiAction(RunId: string): Promise<GetActionStatusResponse> {
    const url = `${CONSTANTS.BASE_URL}${CONSTANTS.API_PATHS.AGENT_RUNS}/${RunId}`;
    const response = await fetch(url, {
        method: CONSTANTS.HTTP_METHOD.GET,
        headers: { [CONSTANTS.HEADERS.X_TOKEN]: CONSTANTS.TOKEN }
    });

    if (!response.ok) {
        throw new Error(`${response.status} ${response.statusText} ${await response.text()}`);
    }

    const checkResult = await response.json() as GetActionStatusResponse;

    return checkResult;
}

// Запуск проверки статуса AI-операции и ожидание результата её выполнения
async function waitForResult(RunId: string, maxAttempts = 60, interval = 2000): Promise<DataContent[]> {
    for (let i = 0; i < maxAttempts; i++) {
        const res = await checkStatusAiAction(RunId);

        if (res.problem) {
            throw new Error(`[Ошибка:waitForResult:Ошибка при проверке статуса]: ${JSON.stringify(res.problem)}`);
        }
        if (res.status.toUpperCase() === CONSTANTS.AGENT_RUN_STATUS.SUCCESS) {
            return res.output;
        }
        await new Promise(resolve => setTimeout(resolve, interval));
    }
    throw new Error("[Ошибка:waitForResult]: Превышено время ожидания");
}

// Основная функция для запуска AI-операции
async function runAiAction(): Promise<string> {
   const id = await cortexCall(Context.data.request_text); // Запуск AI-операции
   const output = await waitForResult(id); // Запись ответа AI-операции
      ViewContext.data.analysis_result = output;
}

Шаг 3. Написать клиентский скрипт для запуска серверного скрипта

На вкладке Скрипты выберите в правом верхнем углу опцию Клиент.
Напишите функцию, в которой вызывается серверный скрипт для запуска AI‑операции:

async function runRequestAnalysis(): Promise<void> {
await Server.rpc.runAiAction();
}

Шаг 4. Настроить запуск AI-операции при нажатии кнопки

На вкладке Шаблон разместите на форме виджет Кнопка.
В открывшемся окне настроек укажите название и иконку, в поле Тип действия выберите Скрипт и укажите функцию, созданную на шаге 3.
Сохраните настройки виджета.
На верхней панели дизайнера интерфейсов нажмите Сохранить и Опубликовать.

Теперь, если обращение объёмное, сотрудник может нажать кнопку для формирования краткого содержания. После обработки текста обращения он увидит поле Результат анализа (analysis_result), в котором отобразится ответ AI‑операции.

ai-action-calibration.html cortex-work-with-agents.html

Была ли статья полезной?