Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agno.com/llms.txt

Use this file to discover all available pages before exploring further.

SQLTools connects an agent to a database. Point it at a read-only connection and the agent can introspect the schema and run queries. 
from agno.agent import Agent
from agno.db.postgres import PostgresDb
from agno.models.openai import OpenAIResponses
from agno.tools.sql import SQLTools

agent = Agent(
    model=OpenAIResponses(id="gpt-5.5"),
    db=PostgresDb(db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"),
    tools=[
        SQLTools(db_url="postgresql+psycopg://readonly@warehouse/analytics")
    ],
    instructions=(
        "Introspect the schema before writing SQL. Answer with the numbers "
        "and the exact query you ran. Never guess a column name."
    ),
)

agent.print_response("How many active subscriptions are on the Pro plan?")
The agent’s db and the SQLTools connection are separate. db stores the agent’s own sessions and learnings. SQLTools points at the warehouse you are answering questions about. Keep them distinct.

​
Introspect before generating

A data agent that guesses column names is wrong confidently. SQLTools ships list_tables and describe_table so the agent grounds SQL in the real schema. The instruction to introspect first is what makes it reliable.
ToolUse
list_tablesDiscover what exists before querying
describe_tableGet exact column names and types
run_sql_queryExecute the generated SQL

​
Scope the connection

The cleanest boundary is the connection itself. The readonly Postgres role has no write grant, so the connection physically cannot write, regardless of what the model is prompted to do. For the full read vs write split, see Safe data access.

​
Next steps

TaskGuide
Ground SQL in business rulesGrounding in context
Stop repeating query errorsSelf-correcting agents
Allow controlled writesSafe data access

​
Developer Resources