SQL | Agno

SQLTools enable an Agent to run SQL queries and interact with databases.

Prerequisites

The following example requires the sqlalchemy and openai libraries and a database URL.

uv pip install agno -U sqlalchemy openai

You will also need to install the appropriate Python adapter for the specific database you intend to use.

PostgreSQL

For PostgreSQL, you can install the psycopg adapter:

uv pip install -U "psycopg[binary]"

MySQL

For MySQL, you can install the mysqlclient adapter:

uv pip install -U mysqlclient

The mysqlclient adapter may have additional system-level dependencies. Please consult the official installation guide for more details.

You will also need a database. The following example uses a Postgres database running in a Docker container.

 docker run -d \
  -e POSTGRES_DB=ai \
  -e POSTGRES_USER=ai \
  -e POSTGRES_PASSWORD=ai \
  -e PGDATA=/var/lib/postgresql \
  -v pgvolume:/var/lib/postgresql \
  -p 5532:5432 \
  --name pgvector \
  agnohq/pgvector:18

The Agent model uses an OpenAI key, separately from any toolkit provider credentials.

Set OpenAI Key

Set your OPENAI_API_KEY as an environment variable. You can get one from OpenAI.

export OPENAI_API_KEY=sk-***

Once the local container is ready, seed a small demonstration table:

docker exec pgvector psql -U ai -d ai -c "CREATE SCHEMA IF NOT EXISTS public; CREATE TABLE IF NOT EXISTS public.tool_demo_sales (id integer PRIMARY KEY, product text, revenue numeric); INSERT INTO public.tool_demo_sales VALUES (1, 'Notebook', 120), (2, 'Pen', 45) ON CONFLICT (id) DO NOTHING;"

The sample data is for the local tutorial. To use your own database, replace the connection settings and choose an accessible populated schema.

Example

The following agent will run a SQL query to list all tables in the database and describe the contents of one of the tables.

cookbook/91_tools/sql_tools.py

from agno.agent import Agent
from agno.tools.sql import SQLTools

db_url = "postgresql+psycopg://ai:ai@localhost:5532/ai"

agent = Agent(tools=[SQLTools(db_url=db_url)])
agent.print_response("List the tables in the database. Tell me about contents of one of the tables", markdown=True)

Toolkit Params

Parameter	Type	Default	Description
`db_url`	`Optional[str]`	`None`	The URL for connecting to the database.
`db_engine`	`Optional[Engine]`	`None`	The database engine used for connections and operations.
`user`	`Optional[str]`	`None`	The username for database authentication.
`password`	`Optional[str]`	`None`	The password for database authentication.
`host`	`Optional[str]`	`None`	The hostname or IP address of the database server.
`port`	`Optional[int]`	`None`	The port number on which the database server is listening.
`schema`	`Optional[str]`	`None`	The specific schema within the database to use.
`dialect`	`Optional[str]`	`None`	The SQL dialect used by the database.
`tables`	`Optional[Dict[str, Any]]`	`None`	A dictionary mapping table names to their respective metadata or structure.
`enable_list_tables`	`bool`	`True`	Enables the functionality to list all tables in the database.
`enable_describe_table`	`bool`	`True`	Enables the functionality to describe the schema of a specific table.
`enable_run_sql_query`	`bool`	`True`	Enables the functionality to execute SQL queries directly.
`all`	`bool`	`False`	Enables all functionality when set to True.

Toolkit Functions

Function	Description
`list_tables`	Lists all tables in the database.
`describe_table`	Describes the schema of a specific table.
`run_sql_query`	Executes SQL queries directly.

Developer Resources

Tools

On this page