Агент AI з доступом до бази SQL: text-to-SQL безпечно

Фінансовий контролер у дистрибуційній компанії щотижня потребував зведення: продажі за регіоном, маржа за категорією продуктів, порівняння з попереднім кварталом. Писав цей запит самостійно або чекав на аналітика. Після впровадження агента text-to-SQL цей час скоротився до кількох десятків секунд. Не тому, що модель «знає» базу. Тому, що хтось раніше виконав належну роботу: описав схему, визначив бізнес-словник і налаштував guardrails, які гарантують, що агент не зможе зробити нічого деструктивного.

Це реальна обіцянка text-to-SQL. І все. Нічого більше.

Агент text-to-SQL — це агент з доступом до інструменту бази даних. Його робота виглядає так: користувач ставить запитання природною мовою, агент формує контекст (схему бази, бізнес-словник, приклади значень у стовпцях), генерує SQL-запит, валідує його перед виконанням, надсилає до бази, отримує результат і формулює відповідь разом із показаним запитом.

Ключовий елемент — schema-aware prompting. При кожному запитанні до контексту моделі потрапляє опис схеми: назви таблиць, стовпці, типи даних, зовнішні ключі та мапінг стовпців на бізнес-терміни. Без цього мапінгу модель не знає, що стовпець net_rev_adj — це «виручка» і що значення подано в тисячах злотих. Помилкова інтерпретація одиниць або назв виглядає як помилка моделі, але є помилкою конфігурації.

Агент використовує tool-use: замість генерувати запит і одразу його виконувати, викликає інструмент sql_query(statement, limit). Цей інструмент має жорсткий ліміт рядків (зазвичай 500-2000 залежно від контексту), працює виключно на з’єднанні read-only і логує кожен виклик із повним текстом запиту та timestamp.

Для складних багатоетапних запитань агент розбиває завдання на послідовність запитів: спочатку отримує агреговані дані, потім фільтрує або об’єднує їх. Це той самий цикл ReAct, що й у багатоетапному агенті, тільки інструментом є база SQL замість API.

Сама архітектура text-to-SQL без guardrails — це інструмент, який може завдати шкоди. Нижче описано чотири шари захисту, які ми застосовуємо в Cashcrown при кожному впровадженні.

Шар 1: роль read-only на рівні бази. З’єднання агента з базою використовує роль без прав INSERT, UPDATE, DELETE або DROP. Навіть якщо модель згенерує запит, що модифікує дані (наприклад, через prompt injection), база відхилить його з помилкою прав доступу. Це єдина лінія оборони, яка працює незалежно від усіх інших.

Шар 2: allowlist таблиць і стовпців. Агент бачить лише ті таблиці та стовпці, які були явно дозволені. Таблиці з персональними даними (імена, електронні адреси, номери клієнтів), кадровими або фінансово чутливими даними за замовчуванням виключені зі схеми, що надається моделі. Доступ до них вимагає рішення людини, а не зміни конфігурації користувачем.

Шар 3: валідація запиту перед виконанням. Перед кожним виконанням guardrail парсить згенерований SQL-запит і перевіряє: чи містить лише інструкції SELECT, чи не посилається на таблиці поза allowlist, чи ліміт рядків нижче порогу. Запит, який не пройде валідацію, потрапляє до логу та ескалації, а не до бази.

Шар 4: human-gate для низької впевненості та чутливих таблиць. Коли модель оцінює впевненість відповіді як низьку (складні JOIN, незрозуміле запитання, невідомі терміни), агент замість відповіді сигналізує: «потребує перевірки». Те саме стосується будь-якого запиту, що зачіпає таблиці, позначені як чутливі. Human-oversight не є опцією для цих двох класів.

Точність систем text-to-SQL у виробничих середовищах коливається від 70 до 85% на чистих, добре документованих схемах. На незрозумілих схемах (скорочення в назвах стовпців, відсутність зовнішніх ключів, неоднозначні типи) точність падає до 40-60%. Ми в Cashcrown вимірюємо це на golden set з 50-100 запитань перед кожним виробничим впровадженням.

Найчастіше виникають три категорії помилок.

Галюциновані стовпці та таблиці. Модель може згенерувати запит, що посилається на стовпець, якого не існує в схемі, особливо якщо схема велика або неповністю описана. Guardrail, що парсить SQL перед виконанням, виявляє цю помилку до того, як запит потрапить до бази. Без цього валідатора запит викликає помилку бази, яку модель може некоректно обробити.

Помилкові JOIN на складних зв’язках. Запитання, що вимагає об’єднання п’яти таблиць через частково описані ключі, часто призводить до запиту, який є синтаксично правильним, але семантично помилковим. Агрегує на неправильному рівні деталізації або пропускає умову фільтра. Результат виглядає правдоподібно, але є некоректним. Захистом є вимога, щоб агент завжди показував згенерований запит користувачеві перед наданням відповіді.

Багатозначність бізнес-термінів. «Виручка», «маржа», «клієнт» можуть мати різні визначення в різних відділах однієї компанії. Бізнес-словник у семантичному шарі повинен однозначно мапити ці терміни на конкретні стовпці та формули. Відсутність цього мапінгу — джерело помилок, які важко виявити, бо цифри виглядають логічно. Деталі підготовки даних для AI описує стаття AI для аналізу даних і BI.

Це не питання конфігурації для подальшого послаблення. Це архітектурна межа.

Агент text-to-SQL ніколи не виконує автономно запити INSERT, UPDATE, DELETE або DDL. Навіть якщо користувач просить змінити дані через діалог. Навіть якщо prompt виглядає невинно. Роль read-only на рівні бази — єдина лінія оборони, незалежна від моделі.

Агент ніколи не торкається таблиць, що містять PII (персональні дані клієнтів, працівників, контрагентів) без явного рішення людини. Ці таблиці виключені зі схеми, що надається моделі. Доступ до них можливий виключно через шлях з human-gate, де оператор бачить, які дані будуть отримані, і підтверджує або відхиляє запит. Інтеграцією агента з корпоративними системами, такими як ERP, займається окрема стаття інтеграція AI з ERP та системами.

Запити з низькою впевненістю моделі (незрозуміле запитання, відсутність відповідності схемі, порожній результат при очікуваному непорожньому) потрапляють до людини з контекстом: показаним запитом, причиною ескалації та пропозицією спростити запитання. Питання безпеки агентів ширше описує стаття безпека агентів AI.

Observability агента text-to-SQL — це не логування заради логування. Це фундамент довіри до результатів та вимога за AI Act для систем, що впливають на бізнес-рішення.

Кожен виклик інструменту бази даних генерує запис, що містить: запитання користувача, згенерований SQL-запит, кількість повернутих рядків, час виконання та результат валідації guardrails. Ці записи служать трьом цілям.

Перша — моніторинг якості: який відсоток запитів завершується успіхом, який ескалацією, який помилкою guardrails. Зростання частки ескалацій — сигнал дрейфу (зміна схеми бази, нові терміни в запитаннях користувачів без оновлення словника).

Друга — golden set test: набір з 50-100 запитань з очікуваними результатами, що запускається циклічно (раз на тиждень або при кожній зміні схеми). Падіння точності нижче порогу попереджає про це до того, як користувачі повідомлять про помилки.

Третя — аудиторський слід, необхідний за AI Act та RODO для систем, що впливають на фінансові або кадрові рішення. Кожна відповідь має бути відтворюваною: відомо, який запит згенерував результат, з яких даних і в який момент. Валідацію виходів моделі детально описує стаття валідація виходів LLM.

Опишіть схему вашої бази та аналітичне запитання, яке хочете ставити, а модель спроектує архітектуру агента text-to-SQL: schema prompting, guardrails та місця human-gate для вашого діапазону (playground: PII масковані, zero retention):

На чистій, добре документованій схемі з описаним бізнес-словником точність становить від 70 до 85% без додаткового fine-tuning. На схемі з неоднозначними назвами стовпців, відсутністю зовнішніх ключів або змішаними одиницями точність падає до 40-60% і вимагає спочатку робіт з упорядкування. Ми в Cashcrown вимірюємо точність на golden set з 50-100 запитань перед кожним виробничим впровадженням. Без цього baseline незрозуміло, з чого починати і як вимірювати покращення.

Ні, якщо архітектура побудована правильно. З’єднання агента використовує роль бази даних без прав INSERT, UPDATE, DELETE або DDL. Цей шар працює незалежно від моделі: навіть якщо модель згенерує запит, що модифікує дані через prompt injection або помилку, база відхилить його з помилкою прав доступу. До цього додається guardrail, що парсить SQL перед відправкою до бази, який блокує будь-який запит, що містить інструкції, відмінні від SELECT.

Агент сигналізує про ескалацію замість відповіді: показує згенерований запит, вказує причину сумнівів (наприклад, невідомий термін, відсутність відповідності схемі, порожній результат) і просить оператора перевірити або спростити запитання. Це запланована поведінка, а не аварійна. Система, яка впевнено відповідає на запитання поза своїм діапазоном, небезпечніша за систему, яка визнає брак знань. Патерн structured output з полями confidence та requires_review дозволяє агенту формально сигналізувати це рішення.

Практичний ліміт — 30-50 таблиць у контексті схеми при типових розмірах вікна контексту сучасних моделей. Для більших баз застосовують шаровування: агент працює з представленнями (views), підготовленими інженером даних, а не з сирою схемою. Альтернативно схему фільтрують динамічно на основі запитання, що обмежує контекст до таблиць, важливих для конкретного запиту. Обидві техніки потребують додаткової конфігурації.

Починаємо з аудиту схеми та бізнес-словника (від 1 до 2 тижнів залежно від кількості таблиць та стану документації). Потім налаштовуємо guardrails, allowlist таблиць та роль read-only. Далі golden set: 50-100 запитань з очікуваними результатами, вимірювання baseline точності. Пілот з користувачами протягом 2-4 тижнів з повним моніторингом ескалацій. Повна автономія лише після валідації точності та рівня ескалацій нижче узгоджених порогів. Вхід через оцінку готовності або контакт.