Grounding in context

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. Ask the agent to retrieve relevant context before writing SQL.

uv pip install "agno[openai,pgvector,psycopg,sql]"

Set OPENAI_API_KEY in the environment before running the Python code. Replace the warehouse URLs with your own PostgreSQL connection strings and create the database roles, schemas, and grants described on this page first. The host warehouse, database analytics, and roles such as readonly and dash_writer are placeholders.

Examples using PostgresDb or PgVector also need a separate writable application database. The sample URL assumes a PostgreSQL service at localhost:5532 with database/user/password ai; knowledge examples need the pgvector extension. See PgVector setup. Keep this application's storage credentials separate from the restricted warehouse role.

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, search_knowledge=True exposes a search tool by default. The model chooses whether to call it. Instructions can request retrieval before SQL; if retrieval must happen for every request, perform it in application code before the run and supply its results. Set search_knowledge=False to remove the search tool.

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.

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

Next steps

Developer Resources

• Knowledge
• Dash: six layers of context