> ## Documentation Index
> Fetch the complete documentation index at: https://agno-v2-docs-scavio-google-v2.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
uv pip install "agno[openai,pgvector,psycopg,sql]"
```

```python theme={null}
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](/use-cases/data-agents/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](/use-cases/data-agents/self-correcting-agents) |
| Run the SQL safely               | [Safe data access](/use-cases/data-agents/safe-data-access)             |

## Developer Resources

* [Knowledge](/knowledge/overview)
* [Dash: six layers of context](/deploy/templates/dash/overview)