What you’ll build: An agent that can query a SQL database and answer business questionsTime: ~15 minutesPrerequisites:
- Completed the Hello World tutorial
- Basic SQL knowledge
- SQLite installed (included with Python)
What you’ll learn
This tutorial demonstrates:- Using built-in SQL query tools
- Creating and populating sample databases
- Enabling agents to analyze data
- Best practices for database security
- Query result visualization
Use case: Coffee shop analytics
We’ll create a coffee shop database and an agent that can answer business questions like:- “What are our top-selling products?”
- “Which customer has spent the most?”
- “What’s our total revenue this month?”
Step-by-step guide
Create a sample database
Create a Python script to set up your database:Run the script:This creates
create_coffee_db.py
coffee_shop.db with sample data.Configure database connection
Add database configuration to your
.env file:.env
For PostgreSQL:
postgresql://user:password@localhost/dbnameFor MySQL: mysql://user:password@localhost/dbnameRun and test the database agent
Start the agent:Open the Web UI and try these queries:Test 1: Top productsExpected behavior:
The agent will:Test 3: Customer insightsTest 4: Product categories
- Write a SQL query to count orders by product
- Execute the query
- Present results in a formatted table
Understanding built-in data analysis tools
SAM includes several built-in tools for data analysis:SQL Query Tool
- sql_query: Execute SQL queries on configured databases
- jq_query: Process JSON data with jq syntax
- create_chart: Generate visualizations from data
SQL Query Tool Usage
The agent can call it like this:Security best practices
Read-only database user
For production, create a read-only database user:PostgreSQL example
Query validation
Add instruction guardrails:Query timeouts
Configure timeouts to prevent expensive queries:Advanced data analysis
Create visualizations
Create visualizations
The agent can create charts from query results:The agent will generate charts and save them as artifacts.
Multi-database queries
Multi-database queries
Configure access to multiple databases:
Join with external data
Join with external data
Combine database queries with API data:
Scheduled reports
Scheduled reports
Create a workflow that runs periodic reports:
Example queries and use cases
Sales analytics
Customer analytics
Testing database queries
Create a test suite:test_database_agent.py
Next steps
MCP Servers
Integrate Model Context Protocol servers
RAG Implementation
Build retrieval-augmented generation systems
Complex Workflows
Create advanced multi-step workflows
Production Deployment
Deploy your agents to production
Troubleshooting
Database not found error
Database not found error
Problem: “Database file not found”Solution:
- Verify the database file exists:
ls -la coffee_shop.db - Check the path in
DATABASE_URLis correct - Use absolute paths if needed:
sqlite:////full/path/to/coffee_shop.db
Permission denied
Permission denied
Problem: “Permission denied accessing database”Solution:
Query timeout
Query timeout
Problem: “Query execution timeout”Solution:
- Add indexes to frequently queried columns
- Increase timeout in configuration:
- Optimize the query (use EXPLAIN to analyze)
Connection pool errors
Connection pool errors
Problem: “Too many database connections”Solution:
For production databases, configure connection pooling:
Key concepts learned
- Using built-in SQL query tools
- Creating and populating databases
- Configuring database connections
- Security best practices for database access
- Building data analysis agents
- Testing database integrations