text-to-sql-agent Documentation

Technical Documentation: langchain-ai/text-to-sql-agent

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

Text-to-SQL Agent

A natural language to SQL query agent powered by LangChain. Ask questions about your database in plain English and get accurate SQL queries and results.

Features Copy Chapter

• Natural language to SQL query conversion
• Automatic query validation and error correction
• Support for complex queries (JOINs, aggregations, subqueries)
• LangSmith integration for tracing and debugging
• Interactive tutorial notebook included

Demo Database Copy Chapter

Uses the Chinook database - a sample database representing a digital media store with tables for artists, albums, tracks, customers, invoices, and more.

Quick Start Copy Chapter

Prerequisites Copy Section

• Python 3.11 or higher
• Anthropic API key (get one here) (Or you can use a different model provider)
• (Optional) LangSmith API key for tracing (sign up here)

Installation Copy Section

1. Clone the repository:

git clone https://github.com/kevinbfrank/text-to-sql-agent.git
cd text-to-sql-agent

2. Download the Chinook database:

# Download the SQLite database file
curl -L -o chinook.db https://github.com/lerocha/chinook-database/raw/master/ChinookDatabase/DataSources/Chinook_Sqlite.sqlite

3. Create a virtual environment and install dependencies:

# Using uv (recommended)
uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

# Or using standard pip
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e .

4. Set up your environment variables:

cp .env.example .env
# Edit .env and add your API keys

Required in .env:

ANTHROPIC_API_KEY=your_anthropic_api_key_here

Optional for LangSmith tracing:

LANGCHAIN_TRACING_V2=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=your_langsmith_api_key_here
LANGCHAIN_PROJECT=text2sql-agent

Usage Copy Chapter

Command Line Interface Copy Section

Run the agent from the command line with a natural language question:

python agent.py "What are the top 5 best-selling artists?"

python agent.py "Which employee generated the most revenue?"

python agent.py "How many customers are from Canada?"

Interactive Tutorial Copy Section

Explore the agent capabilities with the included Jupyter notebook:

jupyter notebook tutorial.ipynb

The tutorial includes:

• Step-by-step agent construction
• Example queries
• LangSmith tracing setup
• Database schema reference

How It Works Copy Chapter

The agent uses LangChain's create_agent with the following workflow:

1. Discover - Lists available tables in the database
2. Inspect - Retrieves schema for relevant tables (with sample rows)
3. Generate - Creates a SQL query using Claude Sonnet 4.5
4. Validate - Double-checks the query for syntax and safety
5. Execute - Runs the query against the database
6. Retry - If errors occur, automatically rewrites and retries
7. Format - Returns results in a readable format

LangSmith Integration Copy Chapter

When configured, every query is automatically traced in LangSmith. You can view:

• Complete execution trace with all tool calls
• Token usage and costs
• Query execution time
• Generated SQL queries
• Error messages and retry attempts

View traces at: https://smith.langchain.com/

Configuration Copy Chapter

Key configuration options in agent.py:

# Limit sample rows shown in schema
db = SQLDatabase.from_uri(
    "sqlite:///chinook.db",
    sample_rows_in_table_info=3  # Adjust as needed
)

# Default result limit (in system prompt)
system_prompt=SYSTEM_PROMPT.format(
    dialect=db.dialect,
    top_k=5  # Adjust as needed
)

Project Structure Copy Chapter

text2sqlagent/
├── agent.py              # Core agent implementation
├── tutorial.ipynb        # Jupyter tutorial notebook
├── chinook.db           # Sample SQLite database (gitignored)
├── pyproject.toml       # Project configuration and dependencies
├── uv.lock              # Locked dependency versions
├── .env.example         # Environment variable template
├── .gitignore           # Git ignore rules
└── README.md            # This file

Requirements Copy Chapter

All dependencies are specified in pyproject.toml:

• langchain >= 1.2.3
• langchain-anthropic >= 1.3.1
• langchain-community >= 0.3.0
• langgraph >= 1.0.6
• sqlalchemy >= 2.0.0
• python-dotenv >= 1.0.0
• rich >= 13.0.0

License Copy Chapter

MIT

Acknowledgments Copy Chapter

• Built with LangChain
• Uses the Chinook Database
• Tracing via LangSmith

Contributing Copy Chapter

Contributions are welcome! Please feel free to submit a Pull Request.

--- METRICS ---

• Files Extracted: 1
• Estimated Token Budget: ~1194 tokens
• Canonical Reference: https://codewiki.google/github.com/langchain-ai/text-to-sql-agent