SQL Agent - Документация

Краткий обзор

SQL Agent — это CLI-приложение для работы с базами данных на естественном языке. Пользователь вводит запрос на обычном языке, а интеллектуальный агент на основе LLM преобразует его в SQL и выполняет против подключённой базы данных.

Основные возможности

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

# Подключение к базе данных
sql_agent connect --url "postgresql://user:pass@localhost/mydb"

# Интерактивная сессия
> покажи всех пользователей, зарегистрированных за последний месяц
SQL: SELECT * FROM users WHERE created_at >= NOW() - INTERVAL '1 month';
[результат в виде таблицы]

> какая средняя сумма заказа по категориям?
SQL: SELECT category, AVG(amount) FROM orders GROUP BY category;
[результат в виде таблицы]

Бизнес-обзор

Модель монетизации

SQL Agent — это micro-SaaS продукт с лицензионной моделью:

Тариф Цена Особенности
Free Бесплатно 50 запросов/день, 1 подключение, только SQLite
Personal $9.99/мес 500 запросов/день, 3 подключения, все СУБД
Professional $29.99/мес 5000 запросов/день, 10 подключений, аналитика производительности
Enterprise По запросу Без ограничений, выделенная поддержка

Архитектура продукта 

┌─────────────────────────────────────────────────────────────────┐
│                         Пользователь                            │
└─────────────────────────────────────────────────────────────────┘
          │                                    │
          │ Покупка лицензии                   │ Использование CLI
          ▼                                    ▼
┌─────────────────────────┐         ┌─────────────────────────────┐
│   Веб-приложение        │         │    SQL Agent CLI            │
│   (sqlagent.io)         │         │                             │
│                         │         │  • Валидация лицензии       │
│  • Регистрация          │ ◄─────► │  • NL → SQL конвертация     │
│  • Оплата (YooKassa)    │  HTTPS  │  • Подключение к БД         │
│  • Генерация ключей     │         │  • Выполнение запросов      │
│  • Скачивание CLI       │         │  • Форматирование           │
└─────────────────────────┘         └─────────────────────────────┘

Путь пользователя

  1. Регистрация: Пользователь создаёт аккаунт на sqlagent.io
  2. Выбор тарифа: Выбирает подходящий план и оплачивает через YooKassa
  3. Получение ключа: Система генерирует уникальный API-ключ (формат: XXXX-XXXX-XXXX-XXXX)
  4. Установка CLI: Скачивает установщик для своей ОС
  5. Активация: Выполняет sql_agent login <api-key>
  6. Работа: Подключается к БД и выполняет запросы на естественном языке

Целевая аудитория

Технический обзор

Стек технологий

Компонент Технология Назначение
CLI Framework Typer + Rich Интерфейс командной строки и форматирование
LLM Agent LangGraph Конечный автомат для обработки запросов
LLM Providers LangChain Абстракция над OpenAI, Anthropic, Ollama и др.
Database ORM SQLAlchemy Подключение к БД и интроспекция схемы
Packaging PyInstaller Сборка исполняемых файлов

Архитектура CLI-приложения 

cli_app/
├── main.py              # Точка входа, команды Typer, REPL-сессия
├── agent.py             # LangGraph-агент с LLM-интеграцией
├── database.py          # SQLAlchemy-менеджер подключений
├── query_executor.py    # Безопасное выполнение запросов
├── config.py            # Конфигурация и профили
└── license_validator.py # HTTP-клиент для валидации лицензии

Обработка запросов (LangGraph Workflow) 

┌─────────────────┐
│  Ввод           │
│  пользователя   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│  analyze_input  │────►│  Это SQL или    │
│                 │     │  естественный   │
└────────┬────────┘     │  язык?          │
         │              └─────────────────┘
         │
    [если NL]
         │
         ▼
┌─────────────────┐
│  generate_sql   │     LLM генерирует SQL
│                 │     на основе схемы БД
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  validate_query │     Проверка безопасности:
│                 │     - Блокировка DROP, TRUNCATE
│                 │     - Добавление LIMIT
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  format_response│     Форматирование
│                 │     результата
└─────────────────┘

Поддерживаемые LLM-провайдеры

Провайдер Модель по умолчанию Переменная окружения
OpenAI gpt-4 OPENAI_API_KEY
Anthropic claude-3-sonnet ANTHROPIC_API_KEY
DeepSeek deepseek-chat DEEPSEEK_API_KEY
Groq mixtral-8x7b GROQ_API_KEY
Ollama llama2 — (локальный)

Конфигурация провайдера 

# Установка провайдера
sql_agent configuration llm.provider --value anthropic
sql_agent configuration llm.model --value claude-3-sonnet

# Использование локального Ollama (без API-ключа)
sql_agent configuration llm.provider --value ollama
sql_agent configuration llm.model --value llama2

Безопасность

Защита запросов

Валидация лицензии

CLI-команды

Команда Описание Требует лицензию
login <api-key> Авторизация с API-ключом Нет
logout Удаление сохранённого ключа Нет
connect --url <url> Подключение к БД Да
use-profile <name> Использование сохранённого профиля Да
profiles Список профилей Нет
delete-profile <name> Удаление профиля Нет
configuration Просмотр/изменение настроек Нет
history История запросов Нет

Интерактивные команды (внутри сессии)

Команда Описание
help Справка по командам
schema Схема базы данных
insights <table> AI-анализ таблицы
history Последние 5 запросов
clear Очистка истории диалога
exit Выход из сессии

Сборка и распространение 

# Сборка исполняемого файла
pip install pyinstaller
pyinstaller packaging/sql_agent.spec

# Результат
./dist/sql_agent --help

Поддерживаемые платформы

Веб-приложение (WebSQLAgent)

Серверная часть на Django для:

API-эндпоинты

Метод URL Описание
POST /api/validate-license/ Валидация API-ключа
GET /api/license-info/ Информация о лицензии
GET /api/downloads/ Список установщиков
GET /download/<platform>/ Скачивание установщика

Зависимости 

typer>=0.9.0          # CLI-фреймворк
rich>=13.0.0          # Форматирование терминала
langgraph>=0.2.0      # Конечный автомат агента
langchain-core>=0.3.0 # Абстракции LLM
sqlalchemy>=2.0.0     # ORM и подключение к БД
cryptography>=41.0.0  # Шифрование Fernet
requests>=2.31.0      # HTTP-клиент
sqlparse>=0.4.0       # Парсинг SQL

# Провайдеры LLM
langchain-openai>=0.1.0
langchain-anthropic>=0.1.0
langchain-ollama>=0.1.0
langchain-groq>=0.1.0

Ограничения

Контакты и поддержка