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.
A model knows SQL but it does not know that revenue was replaced by revenue_v2 last March, that “active” excludes trialing accounts, or that MRR is computed net of credits. Grounding provides the missing context. The agent retrieves the relevant context for each question before it writes a line of SQL.
from agno.agent import Agent
from agno.knowledge.knowledge import Knowledge
from agno.models.openai import OpenAIResponses
from agno.tools.sql import SQLTools
from agno.vectordb.pgvector import PgVector
knowledge = Knowledge(
vector_db=PgVector(table_name="dash_knowledge", db_url="postgresql+psycopg://ai:ai@localhost:5532/ai"),
)
agent = Agent(
model=OpenAIResponses(id="gpt-5.5"),
tools=[SQLTools(db_url="postgresql+psycopg://readonly@warehouse/analytics")],
knowledge=knowledge,
search_knowledge=True,
instructions="Retrieve relevant query patterns and table notes before writing SQL.",
)
search_knowledge=True lets the agent pull the matching context per question instead of carrying the entire data dictionary in every prompt.
The layers worth curating
A production data agent grounds each answer in several layers. The first set is curated and stored in a vector database. The rest are live.
| Layer | Source | Curated? |
|---|
| Validated queries | Known-good SQL for common questions | Yes, in knowledge |
| Table metadata | What each table and column actually means | Yes, in knowledge |
| Business rules | Definitions: what “active”, “MRR”, “churn” mean here | Yes, in knowledge |
| Institutional knowledge | An MCP server into your wiki or docs | Live |
| Learnings | Fixes the agent captured from past errors | Live, see Self-correcting agents |
| Runtime schema | describe_table at query time | Live |
Validated queries are the highest-leverage layer
One known-good query for “monthly recurring revenue” is worth more than a page of schema notes. When the agent retrieves a validated query for a similar question, it adapts a correct shape instead of inventing one. Seed the store with the queries your analysts already trust.
Grounding vs raw text-to-SQL
| Raw text-to-SQL | Grounded data agent |
|---|
| Guesses column meaning from names | Reads curated table metadata |
| Reinvents each query from scratch | Adapts a validated query |
| ”Active” means whatever the model assumes | ”Active” means what your business rule says |
| Wrong in a way that looks right | Wrong in a way you can trace to a missing rule |
Next steps
| Task | Guide |
|---|
| Capture fixes as durable context | Self-correcting agents |
| Run the SQL safely | Safe data access |
Developer Resources
