Grounding in context

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.

uv pip install "agno[openai,pgvector,psycopg,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"),
)
knowledge.insert(
    name="Active subscriptions",
    text_content=(
        "Business rule: a subscription is active when ended_at IS NULL. "
        "Validated query pattern: SELECT plan, count(*) FROM subscriptions "
        "WHERE ended_at IS NULL GROUP BY plan."
    ),
)

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.",
)

agent.print_response("How many active subscriptions are on the Pro plan?")

With knowledge attached, the agent searches it per question and pulls only the matching context, instead of carrying the entire data dictionary in every prompt. Knowledge search is on by default. Set search_knowledge=False to turn it off.

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: the question, the SQL, the tables used, and any data-quality notes.

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

Welcome

Get Started

Features

Use Cases

Grounding in context

The layers worth curating

Validated queries are the highest-leverage layer

Grounding vs raw text-to-SQL

Next steps

Developer Resources

​The layers worth curating

​Validated queries are the highest-leverage layer

​Grounding vs raw text-to-SQL

​Next steps

​Developer Resources

The layers worth curating

Validated queries are the highest-leverage layer

Grounding vs raw text-to-SQL

Next steps

Developer Resources