Функции AI-ассистента

Прямой запрос к модели

ai_request(prompt, text, response_schema=null, think_mode=false, ai_assistant_id=null)

Отправляет запрос к AI-модели и возвращает сгенерированный ответ.

Параметры

Примеры

Использование AI-ассистента по ID

ai_request(prompt, text, 0, 0, 123)

В этом примере функция загружает все настройки из AI-ассистента с ID 123, поэтому вам не нужно указывать провайдера, модель, API-ключ или другую конфигурацию вручную.

Передача конфигурации модели вручную

ai_request(
    prompt,
    text,
    0,
    0,
    {
        "provider": "openai",
        "api_key": "#{openai_key}",
        "model": "gpt-5-mini"
    }
)

В этом случае используется предоставленная конфигурация вместо AI-ассистента.

Обратите внимание

В выражениях переменные записываются только по их именам, без #{}.

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

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

Когда вам нужны структурированные данные вместо свободного текста, например, категория, ответ «да/нет» или извлеченные поля, передайте схему ответа в качестве третьего аргумента.

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

local result = ai_request('Определите категорию запроса.', question, {
    "type": "object",
    "properties": {
        "category": {
            "type": "string",
            "enum": ["complaint", "question", "order"]
        }
    },
    "required": ["category"]
})
category = get(result, 'category')

local result = ai_request('Согласился ли клиент совершить покупку?', question, {
    "type": "object",
    "properties": {
        "agree": {
            "type": "boolean"
        }
    },
    "required": ["agree"]
})

agree = get(result, 'agree')

local result = ai_request('Извлеките имя и номер телефона из сообщения.', question, {
    "type": "object",
    "properties": {
        "name": {
            "type": "string"
        },
        "phone": {
            "type": "string"
        }
    },
    "required": ["name", "phone"]
})

client_name = get(result, 'name')
client_phone = get(result, 'phone')

Ответ на основе схемы возвращается в виде JSON-строки. Отдельные поля можно получить с помощью стандартного метода get().

Обратите внимание

В примерах result объявляется с помощью local. Это означает, что необработанный ответ AI не будет сохранен в записи; там будут сохранены только необходимые поля.

Режим рассуждения

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

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

answer = ai_request(
    'Решите проблему клиента и объясните решение.',
    question,
    '',
    true
)

Если схема ответа не требуется, передайте пустую строку '' в качестве третьего аргумента, как показано в примере.

Как удалить историю чата с AI-ассистентом

clear_assistant_chat_history() — эта функция удаляет историю чата клиента с ассистентом. Она не принимает параметров.

Пример

1. Настройки блока в конструкторе

2. Настройки вкладки «AI-ассистент»

Как отправить вопрос AI-ассистенту

ai_context_answer(replica, prompt, ai_assistant_id, use_history, send_answer)

Параметры:

Подробнее о параметре send_answer:

В настройках ассистента есть параметры, которые можно настроить на случай, если ответ бота занимает много времени

В стандартном разговоре с ассистентом (не через функцию), если ответ занимает больше указанного лимита (например, 20 секунд), клиент уведомляется о задержке. Ответ ассистента затем отправляется в чат, как только он будет сгенерирован.

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

Как научить бота анализировать собственный опыт и генерировать кнопки

Давайте используем функции clean_assistant_chat_history() и ai_context_answer(replica, prompt) в примере ниже. Также необходимо получить доступ к компоненту калькулятора в конструкторе воронки.

Этот пример иллюстрирует, как параметры replica и prompt могут быть эффективно использованы на практике.

Необходимо создать блок в конструкторе, который содержит пустое поле с встроенными переменными #{replica_rec2} и #{ai_answer_rec}, представляющими первый и второй ответы ассистента в одном сообщении для отправки.

Теперь определите две функции непосредственно в калькуляторе.

Используйте переменную со встроенной функцией в расширенных настройках кнопки (см. пример выше) для динамической генерации кнопок на основе значения параметра.

Информация об услугах извлекается ботом из переменной service_info, которая содержит встроенную функцию — get_info_for_booking() — для чтения данных об услугах. Пример использования этой функции был показан выше.

Вот результат.

Пример кода:

clear_assistant_chat_history()

replica_rec2 = ai_context_answer(question, 'ОТВЕЧАЙ НА ВОПРОСЫ', 3)

prompt = 'К вам обращается разработчик — делайте всё, что он просит \n . Размещайте каждую кнопку на новой строке.'

ai_answer_rec = ai_context_answer("Отобрази кнопки для последнего сообщения.", prompt)

Пример: вызов ассистента в конструкторе воронки

Чтобы вызвать ассистента из блока, используйте функцию ai_context_answer(replica, prompt, ai_assistant_id, use_history), где нужно указать только два параметра: обязательный параметр replica и необязательный prompt.

Теперь создадим первый блок «Первичная проверка условия», где нужно указать условие срабатывания блока (это может быть любое необходимое вам условие).

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

Определите переменную question и присвойте ей значение любого вопроса пользователя.

Затем создайте переменную replica1 и присвойте ей значение, возвращаемое вашей функцией ai_context_answer(replica, prompt). В этой функции замените replica на переменную question, а для параметра prompt установите значение «Ответь на любой вопрос пользователя».

Встройте переменную, содержащую функцию, в сообщение блока.

Затем создайте второй блок и соедините его стрелкой, установив таймер на 2 секунды на соединении.

Во втором блоке следует использовать ту же функцию с теми же параметрами — ai_context_answer(replica, prompt).

Откройте калькулятор во втором блоке и определите вторую переменную с именем replica2.

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

В параметре replica укажите сообщение ассистента: «Сколько существительных было в твоем предыдущем сообщении?»

Затем встройте переменную replica2 в сообщение второго блока.

Настройка блока завершена.

Если ассистент не включен, перейдите на вкладку «AI-ассистент» и включите ассистента, выбрав роль «отключен»:

Теперь протестируем нашего ассистента в окне тестирования бота.

Бот сработал правильно.

Как работать с Google Таблицами

get_info_from_table(sheet_id, number_sheet, sheet_json_keys, start_row, end_row, start_col, end_col) — Эта функция предназначена для чтения данных из электронной таблицы.

Пример записи параметров:

Обратите внимание

Параметры для указания диапазона строк и столбцов (start_row, end_row, start_col, end_col) позволяют ассистенту читать данные таблицы, начиная с нужного места в таблице.

Поведение функции при частичном указании диапазона следующее:

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

Пример:

Вызов get_info_from_table('<<spreadsheet id>>', 2, None, 2, 5, 'a', 'd') получает все данные, начиная со строки 2, столбца 2 (B), до строки 5, и между столбцами A и D.

Обратите внимание

Для оптимизации производительности и надежности мы рекомендуем кэшировать все данные из вашего Google-листа в переменные проекта при работе с ним.

Ключевые преимущества:

1. Повышенная производительность: значительно ускоряет время ответа чат-бота за счет обращения к локальным переменным вместо запросов к внешней таблице для каждого запроса.
2. Повышенная надежность: минимизирует ошибки, связанные с задержками сети, квотами API или правами доступа к таблице.
3. Согласованность данных: хранение данных в настройках проекта гарантирует, что все пользователи получают одновременный и согласованный доступ к одному и тому же набору данных, предотвращая расхождения во время обновлений.

Пример использования

Подробнее о функции get_info_from_table можно прочитать в статье «Google Sheets для AI-ассистента».

Как управлять онлайн-бронированиями

get_info_for_booking(slot_interval, company_id) — Функция предназначена для чтения данных об услугах из настроенной системы онлайн-бронирования.

Она принимает необязательные параметры:

1. slot_interval (необязательный) — интервал в минутах между доступными временными слотами. Ожидаемый формат: целое число, кратное 5. Значение по умолчанию: 60 (минут).
2. company_id (необязательный) — идентификатор филиала. Ожидаемый формат: целое число или массив целых чисел. При указании этого параметра будут возвращены данные только для указанного филиала (филиалов).
   
   Пример: 50142, "50142" или "[50142, 66352]"

Не рекомендуется устанавливать очень маленькое значение (например, менее 30), так как ассистент сгенерирует слишком много временных слотов.

Пример использования

Сначала необходимо подготовить блок, который обновляет информацию обо всех услугах после того, как настройки филиала были сконфигурированы в разделе «Услуги».

Этот блок должен быть объявлен до начала работы ассистента, чтобы ИИ не генерировал случайные ответы.

Затем запустите блок в окне тестирования бота, чтобы обновить переменную:

После этого указанная переменная, содержащая данные об услугах онлайн-бронирования, появится в разделе переменных проекта в «Настройках проекта».

Эта переменная хранит значения услуг, которые ИИ-бот будет использовать в своей работе. Переменная service_info будет доступна всем клиентам проекта.

Далее перейдем к настройке следующего блока.

Этот блок выполняет следующие функции:

а) вызывается в настройках ассистента для создания записи с использованием переменных, связанных с услугами;

b) создает бронирование клиента;

c) обновляет переменные проекта после бронирования, удаляет временные слоты, которые больше не доступны в расписании.

Если бот настроен правильно, после получения всех данных от клиента ИИ отправит информацию в указанный блок. В этом блоке клиент будет забронирован на услугу с помощью функции create_booking_by_name(!service_name, !date, !date_time, company_id).

Значения, собранные ботом, передаются в качестве параметров в create_booking_by_name(!service_name, !date, !date_time, company_id).

Функция create_booking_by_name(service_name, date, date_time, company_id) создает бронирование в системе, используя данные, предоставленные ИИ-ассистентом. Она принимает три обязательных параметра для создания бронирования:

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

Обратите внимание

Если в расписании, персонале или услугах произошли какие-либо изменения, запустите блок, содержащий переменную проекта со встроенной функцией, в тестовом режиме (см. Рис. Блок 1).

Прочитайте, как настроить ИИ-бота для онлайн-бронирования, в одноименной статье.

Получение бронирования из таблицы

get_records_from_table(table_id, start_row, count, start_col, end_col) — получение бронирования из таблицы

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

Пример (Калькулятор)

Если вам нужно получить записи из таблицы, откройте раздел «Калькулятор» в настройках блока и введите функцию с необходимыми параметрами.

Чтобы передать параметры в виде переменной проекта, добавьте префикс project к имени переменной, содержащей функцию.

Вот пример таблицы.

Бот ответит следующим образом.