Skip to main content
A self-learning SQL agent that queries Formula 1 data (1950-2020) and improves through accumulated knowledge. Customize and connect it to your own data to build a powerful text-to-SQL agent.

​
What Makes This Different

Most Text-to-SQL tutorials show you how to generate SQL from natural language. This one goes further:
  1. Knowledge-Based Query Generation: The agent searches a knowledge base before writing SQL, ensuring consistent patterns
  2. Data Quality Handling: Instead of cleaning messy data, the agent learns to handle inconsistencies (mixed types, date formats, naming conventions)
  3. Self-Learning Loop: Users can save validated queries, which the agent retrieves for similar future questions

​
What You’ll Learn

ConceptDescription
Semantic ModelDefine table metadata to guide query generation
Knowledge BaseStore and retrieve query patterns and data quality notes
Data Quality HandlingHandle type mismatches and inconsistencies without ETL
Self-LearningSave validated queries to improve future responses
Agentic MemoryRemember user preferences across sessions

​
Prerequisites

  • Python 3.12+
  • Docker (for PostgreSQL with pgvector)
  • OpenAI API key

​
Setup

1

Clone the repository

git clone https://github.com/agno-agi/agno.git
cd agno
2

Create and activate virtual environment

uv venv .venvs/text-to-sql --python 3.12
source .venvs/text-to-sql/bin/activate
3

Install dependencies

uv pip install -r cookbook/01_showcase/01_agents/text_to_sql/requirements.in
4

Set environment variables

export OPENAI_API_KEY=your-openai-key
5

Start PostgreSQL with pgvector

./cookbook/scripts/run_pgvector.sh
This starts a PostgreSQL container with pgvector on port 5532.
6

Check setup

python cookbook/01_showcase/01_agents/text_to_sql/scripts/check_setup.py
7

Load F1 data and knowledge base

python cookbook/01_showcase/01_agents/text_to_sql/scripts/load_f1_data.py
python cookbook/01_showcase/01_agents/text_to_sql/scripts/load_knowledge.py

​
Run the Agent

​
Basic Queries

Run simple aggregation and filtering queries: 
python cookbook/01_showcase/01_agents/text_to_sql/examples/basic_queries.py
Demonstrates:
  • Simple aggregation queries (counts, sums)
  • Filtering by year or driver
  • Using the semantic model to find relevant tables

​
Self-Learning Loop

See how the agent saves validated queries to improve: 
python cookbook/01_showcase/01_agents/text_to_sql/examples/learning_loop.py
Demonstrates:
  • Query execution and validation
  • Saving queries to the knowledge base
  • How saved queries improve future responses

​
Edge Cases

Test complex queries and error handling: 
python cookbook/01_showcase/01_agents/text_to_sql/examples/edge_cases.py

​
Evaluate Accuracy

Run automated accuracy testing: 
python cookbook/01_showcase/01_agents/text_to_sql/examples/evaluate.py

​
Agent Configuration

sql_agent = Agent(
    name="SQL Agent",
    model=OpenAIResponses(id="gpt-5.2"),
    db=sql_agent_db,
    knowledge=sql_agent_knowledge,
    system_message=system_message,
    tools=[
        SQLTools(db_url=DB_URL),
        ReasoningTools(add_instructions=True),
        save_validated_query,
    ],
    add_datetime_to_context=True,
    enable_agentic_memory=True,
    search_knowledge=True,
    add_history_to_context=True,
    num_history_runs=5,
    read_chat_history=True,
    read_tool_call_history=True,
    markdown=True,
)
ParameterPurpose
modelGPT-5.2 for query generation and reasoning
dbPostgreSQL connection for query execution
knowledgeVector database storing query patterns and table metadata
SQLToolsExecute SQL queries against the database
ReasoningToolsThink step-by-step before query construction
save_validated_queryCustom tool to persist successful queries
enable_agentic_memoryRemember user preferences across sessions
search_knowledgeSearch knowledge base before writing SQL
add_history_to_contextInclude recent conversation for context

​
How It Works

​
Query Workflow

1. User asks a question
2. Agent searches knowledge base for similar queries
3. Agent identifies tables from semantic model
4. Agent constructs and executes SQL
5. Agent validates results and presents answer
6. Agent offers to save the query for future use

​
Knowledge Base

The knowledge base stores three types of information:
TypePurpose
Table metadataColumn names, types, and descriptions
Query patternsReusable SQL patterns for common operations
Validated queriesUser-approved queries saved for retrieval

​
Semantic Model

The semantic model provides high-level context about available tables: 
{
    "tables": [
        {
            "table_name": "drivers_championship",
            "table_description": "Driver championship standings (1950 to 2020).",
            "use_cases": [
                "Driver standings by year",
                "Comparing driver points across seasons"
            ]
        }
    ]
}

​
Self-Learning Loop

  1. Agent executes a query and validates results
  2. Agent asks: “Would you like to save this query?”
  3. If confirmed, stores the question, SQL, and explanation
  4. Future similar questions retrieve this pattern automatically

​
Troubleshooting

Ensure PostgreSQL is running:
docker ps | grep pgvector
If not running:
./cookbook/scripts/run_pgvector.sh
The position column in drivers_championship is TEXT, not INT. Use string comparison:
WHERE position = '1'  -- Correct
WHERE position = 1    -- Incorrect
Ensure you’ve loaded the knowledge base:
python cookbook/01_showcase/01_agents/text_to_sql/scripts/load_knowledge.py

​
Source Code