Grounding in context

Ground every query in validated SQL, table metadata, and business rules.

Data agents need your table history and business definitions to write reliable SQL. Add validated queries, table metadata, and business rules to the agent’s knowledge. The agent retrieves the relevant context before writing 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 for each question and retrieves the matching context. Knowledge search is on by default. Set search_knowledge=False to turn it off.

Context to curate

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

Start with validated queries

Validated queries give the agent a trusted starting point for recurring questions such as monthly recurring revenue. For a related request, the agent can retrieve a known-good query and adapt its structure. Store the question, SQL, tables used, and data-quality notes for 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
Generates each query from schema alone	Adapts a validated query when one matches
Infers business meaning	Applies curated business definitions
Depends on implicit assumptions	Uses retrieved rules and query patterns

Next steps

Task	Guide
Capture fixes as durable context	Self-correcting agents
Run the SQL safely	Safe data access

Developer Resources

• Knowledge
• Dash: six layers of context