AI-чат и AI-агент

AI-чат — диалоговый SQL-ассистент

POST /api/ai/chat — многошаговый диалог: клиент присылает всю историю сообщений при каждом запросе (состояние держит клиент, обычно в localStorage), сервер остаётся без состояния. Модель видит схему текущей БД и может предлагать DDL и DML, не только SELECT — но ничего не выполняет сама: SQL-блоки возвращаются отдельно от текста, чтобы интерфейс мог показать кнопку «Выполнить» рядом с каждым.

curl -X POST $URL/api/ai/chat -H "X-Token: $TOK" -d '{
  "messages": [{"role": "user", "content": "Покажи 10 самых новых заказов"}],
  "flavor": "postgresql"
}'

Ответ содержит полный текст модели (markdown), схему, которую ей показали (schema, для прозрачности), и разобранные SQL-блоки с классификацией select / dml / ddl / other:

{
  "message": "Вот запрос...",
  "blocks": [{"sql": "SELECT * FROM orders ORDER BY created_at DESC LIMIT 10", "kind": "select"}],
  "schema": "orders(id, customer_id, created_at, ...)",
  "model": "gpt-4o-mini"
}

Есть потоковый вариант — POST /api/ai/chat/stream — та же логика, но ответ отдаётся по мере генерации, без ожидания полного текста.

AI-агент — read-only исследование

POST /api/ai/agent устроен иначе: это не диалог, а один запрос, внутри которого модель сама делает несколько шагов, вызывая инструменты, пока не соберёт достаточно данных для ответа. Годится для вопросов вида «сколько у нас активных пользователей — посмотри сама, в какой таблице» или «сравни выручку за последнюю неделю с предыдущей», где заранее неизвестно, какие таблицы и запросы понадобятся.

curl -X POST $URL/api/ai/agent -H "X-Token: $TOK" -d '{
  "prompt": "Сколько активных пользователей в базе?"
}'

Доступные инструменты — list_tables, describe_table, run_select — и больше ничего: инструментов для INSERT/UPDATE/DELETE/DDL не существует в принципе, так что даже если модель «решит» почистить таблицу, у неё физически нет для этого инструмента. Дополнительные ограничения:

• лимит итераций — по умолчанию 6, настраивается через max_iters в запросе;
• автоматическая подстановка LIMIT, если модель забыла ограничить SELECT (потолок — 50 строк на шаг);
• таймаут на весь запрос — 90 секунд;
• агент выполняется с правами вызывающего (обычное RBAC), отдельной авторизации по инструментам нет.

Ответ — итоговый текстовый ответ плюс полная стенограмма каждого шага (что спросила модель, что вернул инструмент), удобно для аудита:

{
  "answer": "Активных пользователей: 1 842.",
  "iterations": 3,
  "transcript": [
    {"step": 1, "kind": "tool", "tool_name": "list_tables"},
    {"step": 2, "kind": "tool", "tool_name": "run_select", "tool_input": {"sql": "SELECT COUNT(*) FROM users WHERE status='active'"}},
    {"step": 3, "kind": "llm", "role": "assistant", "content": "Активных пользователей: 1 842."}
  ]
}

Каждый вызов /api/ai/agent — это свежая сессия; если нужна многошаговая беседа с памятью между HTTP-запросами, это ответственность клиента (как и в AI-чате).