Интеграция с OpenAI — Responses API

Продолжаем внедрение AI-решений: добавили интеграцию с OpenAI — Responses API.

Интеграция с «OpenAI — Responses API» позволяет решать два типа задач:

1. Обработка отдельных сообщений без контекста обращения. Каждое сообщение пользователя обрабатывается независимо, без учета переписки.

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

2. Работа AI-ассистента с контекстом обращения. Сообщения пользователя обрабатываются последовательно при помощи определенного набора правил с учетом всей переписки в конкретном обращении и использованием File search для поиска информации в материалах, предварительно загруженных в Vector store OpenAI.

Пример использования: сценарий с AI-ассистентом на первой линии.

Нужно ли переходить на Responses API, если вы не используете Assistants API?

Если вы уже используете в правилах действия интеграции OpenAI — ChatGPT, ознакомьтесь с таблицей, чтобы принять решение. Выбор между Responses API без учета контекста и Chat Completions API (ChatGPT) без функционала Assistant зависит от вашей задачи.

Задача	«OpenAI — ChatGPT»	«OpenAI — Responses API»	Что выбрать
Обработать отдельное текстовое сообщение без учета контекста обращения: например, перевести его или подготовить ответ	Подходит, через действие «Отправить текстовый запрос в адрес AI»	Подходит, через действие «Отправить текстовый запрос в адрес AI Assistant»	Уже настроенные правила можно оставить без изменений. При создании новых правил рекомендуем использовать интеграцию «OpenAI — Responses API»
Преобразовать сообщение-изображение в текст или проанализировать изображение	Не подходит	Подходит	«OpenAI — Responses API»
Автоматически определить группу или значение поля типов «Список» и «Чекбокс»	Подходит, есть специальные действия	Не подходит	«OpenAI — ChatGPT»
Отправить кастомный запрос с самостоятельно заданными параметрами	Подходит	Не подходит	«OpenAI — ChatGPT»

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

Подключение интеграции

Для подключения интеграции вам нужно на стороне OpenAI получить API-ключ и при необходимости создать и настроить Vector store. Затем указать полученные данные на стороне Омнидеска.

Шаги на стороне OpenAI

Шаг 1

Авторизуйтесь в своем аккаунте на официальной платформе OpenAI для разработчиков. Если у вас еще нет аккаунта, создайте его.

Шаг 2

Создайте API-ключ в рамках нужного проекта (Project page → API keys → Create new secret key → Create secret key) и скопируйте его для последующего использования при подключении или редактировании интеграции в Омнидеске.

Шаг 3

Опционально — только для сценария «AI-ассистент на первой линии»

Создайте Vector store в рамках нужного проекта в OpenAI, загрузите в него необходимые материалы и скопируйте его ID для последующего использования при подключении или редактировании интеграции в Омнидеске.

Как это работает?

Рассмотрим на примере «Сервиса X», как устроен сценарий «AI-ассистент на первой линии» в рамках интеграции «OpenAI — Responses API».

Внутренние данные, или данные из Vector store: при настройке интеграции в Омнидеске укажите Vector store ID. В это векторное хранилище (Vector store) предварительно загрузите информацию о вашей компании или сервисе — документацию, базу знаний, спецификации и другие материалы.

• Инструмент File search позволяет AI-ассистенту быстро находить нужную информацию в векторном хранилище.
• Содержимое векторного хранилища не меняется в процессе работы с пользователем и обновляется администратором по мере необходимости.

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

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

Пример: пользователь сообщает об ошибке при авторизации. AI-ассистент анализирует внешние данные (сообщение пользователя и скриншот с текстом ошибки), при помощи инструмента File search находит соответствующую инструкцию в векторном хранилище и формирует ответ, комбинируя знания о сервисе и детали конкретной проблемы пользователя.

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

Для использования контекста отметьте чекбокс «Учитывать контекст…» на шаге 5.

Шаги на стороне Омнидеск

В аккаунте администратора в Омнидеске перейдите по пути: раздел «Настройки» → подраздел «Интеграции» → интеграция «OpenAI — Responses API».

Шаг 4 — базовые настройки: название, API-ключ, модель

Задайте название подключаемой интеграции и укажите ранее полученный API-ключ из настроек аккаунта OpenAI. Выберите языковую модель OpenAI, которая будет использоваться для обработки запросов и генерации ответов.

Шаг 5 — данные и контекст для работы сценария «AI-ассистент на первой линии»

Укажите Vector Store ID, полученный на шаге 3, отметьте чекбокс «Учитывать контекст…» и укажите порог сжатия контекста.

Опция «Учитывать контекст…»

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

💰 Активировав настройку «Учитывать контекст…», вы можете повысить точность и релевантность ответов OpenAI, но увеличиваете стоимость запросов, поскольку модель обрабатывает больше токенов.

— Если чекбокс отмечен, то возможны две ситуации:

а) взаимодействие с «OpenAI — Responses API» в рамках обращения еще не осуществлялось → на основе передаваемого сообщения создается новый conversation;

б) взаимодействие с «OpenAI — Responses API» в рамках обращения уже было → передаваемое сообщение добавляется в связанный с обращением conversation, в котором учитывается предыдущий контекст переписки в обращении.

— Если чекбокс не отмечен, на основе передаваемого сообщения conversation не создается. OpenAI обрабатывает только содержимое передаваемой переменной согласно инструкциям.

Conversation OpenAI в Омнидеске

Conversation — это объект, в котором OpenAI хранит переписку в рамках обращения в Омнидеске. Что попадет в него, зависит от настроек на стороне Омнидеска.

При активной опции «Учитывать контекст…» и использовании одной из переменных — [case_description] или [last_message] — в conversation попадают:

• сообщения пользователя;
• ответы используемой интеграции;
• ответы сотрудников.

В conversation не попадают — а значит, не учитываются:

• автоответы, отправленные правилами из Омнидеска, — в том числе ответы других AI-интеграций, добавленные через поддействие «Полученный ответ — отправить пользователю», если они есть в обращении;
• заметки, добавленные сотрудником, от имени интеграции или правилом, в том числе с использованием переменной [note_text].

Порог сжатия контекста

Настройка доступна только при активной опции «Учитывать контекст…» и определяет, когда OpenAI запускает сжатие контекста. Подробнее

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

Оптимальное значение для вашего сценария рекомендуем подбирать, тестируя разные настройки.

Шаг 6 — поведение модели: уровень рассуждений, детализация, инструкция

Настройте параметры, которые определяют, как модель анализирует запрос и формирует ответ.

Уровень рассуждений

Уровень рассуждений (Reasoning effort) определяет, насколько глубоко модель анализирует запрос перед формированием ответа. При низком уровне модель отвечает быстрее и расходует меньше токенов. Более высокий уровень позволяет тщательнее прорабатывать сложные задачи, но увеличивает время генерации и расход токенов.

Уровень детализации ответов

Уровень детализации ответов (Verbosity) определяет баланс между краткостью и полнотой ответа ассистента. Низкие значения подходят для быстрых и компактных ответов: модель генерирует меньше текста, поэтому сокращаются время ответа и расход токенов. Высокие значения позволяют получать более развернутые ответы с дополнительными пояснениями, контекстом и более четкой структурой.

Инструкция

С помощью инструкции можно:

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

💰 Чем подробнее инструкция, тем больше токенов тратится при подготовке ответов.

В материалах по настройке правил для взаимодействия с «OpenAI — Responses API» мы даем примеры таких инструкций.

Взаимодействие с OpenAI — Responses API

Отправка запросов в адрес OpenAI в рамках интеграции настраивается через правила автоматизации. За саму отправку отвечает действие «Отправить текстовый запрос в адрес AI Assistant» из категории «— интеграция с AI».

Пример таких правил тут.

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

Действие может использоваться во всех типах правил и позволяет отправить сообщение пользователя или сотрудника либо заметку на обработку интеграции «OpenAI — Responses API», указанной в действии.

Вы можете указать нужное сообщение или заметку с помощью переменных:

• [case_description] — первое сообщение в обращении;
• [last_message] — последнее сообщение в обращении;
• [note_text] — последняя заметка в обращении.

• Переменная передает сообщение или заметку целиком: текст, подпись, цитату и вложения.
• Переменную [note_text] нельзя использовать при активной опции «Учитывать контекст…» Подробнее

Ответ OpenAI сохраняется на время выполнения правила в переменную [ai_response_by_text_request]. Ее можно использовать в поддействиях этого же правила, например для:

• отправки пользователю;
• добавления в заметку;
• записи в поле обращения типа «текстовое поле» или «текстовая область».

Особенности записи истории действий в обращении

Правило с действием «Отправить текстовый запрос в адрес AI Assistant» выполняется не мгновенно. Время выполнения зависит от объема данных, скорости ответа OpenAI — Responses API и числа обращений, в которых одновременно срабатывает правило.

Операции — отправка запросов в адрес OpenAI, получение ответов от OpenAI, выполнение поддействий из правила в соответствующих обращениях — выполняются в фоновом режиме. Поэтому история выполнения действия «Отправить текстовый запрос в адрес AI Assistant», включая информацию о затраченных токенах, фиксируется в обращении поэтапно, по мере выполнения поддействий правила.

Ошибки при работе интеграции

Проблема на стороне OpenAI

Иногда OpenAI не возвращает ответ на запрос, при этом все остальные действия правил выполняются — в том числе и выставление в обращении статуса «в ожидании» в сценарии «AI-ассистент на первой линии». В таких ситуациях Омнидеск добавляет в обращение системную заметку и неудаляемую метку ai_error_in_rule_action:

Чтобы пользователь не остался без ответа, а сотрудники были своевременно уведомлены об ошибке, такие ситуации можно отслеживать с помощью правил для измененных обращений, используя следующие условия:

Ответы OpenAI в статистике

В Омнидеске автоответы, настроенные через правила, не учитываются при расчете показателей статистики. Таким образом, для обращений, полностью обработанных в рамках сценария «AI-ассистент на первой линии» при помощи интеграции «OpenAI — Responses API», показатели скорости не рассчитываются.

Настройки SLA зависят от группы. Мы рекомендуем не указывать параметры уровня услуг для групп, в которых с обращениями работает AI-ассистент.

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

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

1) добавлять при переводе на человека специальные метки: «AI-ассистент не справился», «клиент позвал человека», «ошибка AI» и т. д. С помощью меток при анализе статистики вы сможете отфильтровывать такие обращения и рассматривать их отдельно от основного потока, который сотрудники обрабатывают самостоятельно;

2) активировать опцию «Учитывать только время, когда клиент ждет ответа от сотрудника», чтобы в статистику не попадало время, которое обращение проводит в статусе «в ожидании».

Отключение и удаление интеграции

Если в аккаунте администратора более одной активной интеграции типа «OpenAI — Responses API», при отключении или удалении интеграции администратору мы предложим выбрать:

а) заменить отключаемую интеграцию в правилах на одну из оставшихся активных интеграций того же типа («OpenAI — Responses API»):

б) удалить все связанные с отключаемой интеграцией «OpenAI — Responses API» действия правил: