🎯 Featured at SciPy Conference 2025:
Building an AI Agent for Natural Language to SQL Query Execution on Live Databases
📅 July 8, 2025 | 📍 Tacoma, WA | ⏱️ 4-hour hands-on tutorial
This project implements a session-based, RAG-powered AI agent that translates natural language into SQL queries for live querying of PostgreSQL databases. It leverages LangChain, LangGraph, PGVector, and modern agentic patterns with production-quality tooling.
By the end of the tutorial, you'll have a fully working solution you can adapt to your own datasets:
✅ LangGraph Orchestration: Using the latest API references for robust agent workflows
✅ Smart Routing: Intelligent switching between SQL and ReAct-style chat agents
✅ RAG with PGVector: Retrieve few-shot SQL examples based on user queries
✅ Comprehensive Guardrails: Validation and human-in-the-loop approval
✅ Session Memory: Token/cost tracking with LangSmith integration
✅ End-to-End Flow: From schema ingestion to query execution on live databases
✅ Production Ready: Built with modern Python tooling and real-world considerations
The system intelligently routes user queries through specialized agents:
- SQL Agent: Handles database queries with RAG context retrieval
- Chat ReAct Agent: Manages conversational interactions with custom tools
| Layer | Tools & Libraries |
|---|---|
| AI / Agents | LangGraph, LangChain, OpenAI |
| Retrieval | PGVector, SQL context + query embeddings |
| Database | PostgreSQL, SQLAlchemy, psycopg |
| Dev Tooling | uv, Ruff, Python 3.12+ |
| Monitoring | LangSmith |
| Deployment | FastAPI, Docker |
Before getting started, you'll need to install the required tools and dependencies.
See the prerequisites for detailed installation instructions.
Required:
- Git for cloning the repository and switching between branches
- UV for Python project management
- PostgreSQL client libraries to query the database
- Docker (optional) for containerized deployment
- A Python IDE of your choice (e.g., VS Code)
# Clone the repository
git clone https://github.com/cmcouto-silva/nl2sql-agent.git
cd nl2sql-agent
# Install dependencies with UV
uv sync
# Set up environment variables
cp .env.example .env
# Edit .env with your API keys and database credentialsFurther instructions to be provided.
- Setup Guide - Coming soon
- Tutorial Guide - Coming soon
- Deployment Guide - Coming soon
This project is licensed under the MIT License - see the LICENSE file for details.
- SciPy 2025 Conference
- Olist Brazilian E-Commerce dataset contributors
- Global Land Use and Environmental Lab (GLUE) at UW-Madison