Функції 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-асистент" та ввімкніть асистента, вибравши роль "disabled":

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

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

Як працювати з 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 Таблиці для 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) створює запис у системі, використовуючи дані, надані AI-асистентом. Вона приймає три обов'язкові параметри для створення запису:

Оскільки інформація про доступні слоти більше не буде актуальною, для оновлення доступних дат і часу для запису використовується та сама змінна з вбудованою функцією.

Зверніть увагу

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

Про те, як налаштувати AI-бота для онлайн-запису, розповідається в однойменній статті.

Отримання запису з таблиці

get_records_from_table(table_id, start_row, count, start_col, end_col) - отримання запису з таблиці

Якщо вказано лише початок діапазону рядків або стовпців, всі дані від цієї точки далі будуть отримані без верхньої межі діапазону. Аналогічно, можна опустити початок і вказати лише кінець діапазону.

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

Якщо вам потрібно отримати записи з таблиці, відкрийте розділ "Калькулятор" у налаштуваннях блоку та введіть функцію з необхідними параметрами.

Щоб передати параметри як змінну проєкту, додайте префікс project до назви змінної, яка містить функцію.

Ось приклад таблиці.

Бот відповість наступним чином.