Connect AI Agents to Your Data Warehouse With Read Scopes and Lineage
How data teams connect AI agents to a warehouse with read-only scopes, table allowlists, lineage notes and a clear owner for every query path.

To connect an AI agent to a data warehouse safely, give it a dedicated service identity with read-only access to a named set of curated views, expose those views through a few narrow tools with defined inputs and outputs, and attach a lineage note to every answer so people can see where a figure came from. Start with one question your team already answers by hand, and widen access only after the agent's answers match what the warehouse returns on a known test set. This builds the tool layer that more capable systems will later depend on, so the controls you set now stay useful as the agent takes on more work.
Key takeaways
- Give the agent its own warehouse role with read access to named schemas, never an admin role or a person's credentials.
- Expose data through a small set of narrow tools with typed parameters, row caps and timeouts, not open-ended SQL.
- Attach a lineage note to every answer that names the objects read, their refresh time, the filters applied and the identity used.
- Keep writes out of the first phase. Any future write goes through a reviewed path with a named owner.
- Judge the agent by whether its answers match direct, reviewed queries on a fixed set of questions with known answers.
Why the warehouse is the right first tool layer
Most data teams already keep the definitions the business trusts in the warehouse: modeled tables, curated views and the logic behind the dashboards leaders read every week. An agent that reads those objects inherits that work instead of rebuilding metric logic inside a prompt. The questions are concrete, the data is structured, and the results can be checked against numbers the team already believes, which makes the warehouse a sensible starting point.
It also keeps risk contained. Warehouses have mature permission models, with roles, schemas and grants that data engineers already maintain and audit. The agent becomes one more governed identity inside a system you control, rather than a new channel into operational source systems.
The warehouse is not the right home for everything. Facts that change minute to minute, or records that exist only inside a vendor application, may need their own integration. Decide that boundary before you build, so nobody later assumes the agent sees data it cannot.
Set up a read-only identity before you write a single tool
Start with the identity, because every later control depends on it. The steps below work as a plan you can hand to your data engineer.
- Create a dedicated service identity for the agent, separate from any employee account and from any admin role.
- Grant read access only to the curated schemas or views needed for the first question, and nothing else.
- Exclude raw customer contact fields, payment details and any schema that holds credentials or internal secrets.
- Set a statement timeout and a cost or scan ceiling for that identity so a runaway query stops on its own.
- Store the credential in your secrets manager, rotate it on a schedule, and confirm that every query is logged under that identity.
- Review the grants whenever a schema is renamed, split or retired.
The principle behind these steps is least privilege: the agent receives the smallest access that still answers its question. The reasoning is covered in least privilege for AI agents, and the database version of the same pattern is in connecting an AI agent to your database with read-only access.
Design tools, not a raw SQL door
Free-form SQL access is tempting because it can answer almost anything. It is also hard to bound. A safer pattern is a small set of named tools, each with one clear purpose, validated parameters and a fixed output shape. A tool that returns weekly order counts by region might accept a region code from a short list, a start date and an end date, cap the number of rows, and return field names with their units. The agent chooses the tool and fills in the parameters; it does not write the query.
Good tool definitions also help the model choose correctly. Anthropic's engineering guidance on writing tools for agents argues for fewer, clearly scoped tools over broad ones, and the same logic applies to warehouse access. For a fuller treatment of inputs and outputs, see AI tool contracts: designing inputs and outputs that work.
Keep raw SQL out of the first release. If a team later needs it for a specific role, add it as a separate tool with its own grant, its own review and its own lineage entry.
Illustrative scenario: a sales operations lead wants to know which regions fell short of renewal targets last month. The team creates one tool that reads a curated renewals view, accepts a region and a month, returns at most a fixed number of rows, and attaches the view name and its last refresh time to the response. The agent cannot see the raw contract table and cannot change the view.
Write lineage notes the business can read
A lineage note is a short, structured record attached to each answer that explains where the answer came from. It differs from a log. A log helps an engineer debug a failure. A lineage note helps a manager decide whether to trust a number. A useful note contains:
- The warehouse objects read, such as the curated view names, not only the raw source tables behind them.
- The last refresh time of those objects, so a stale figure is visible to the reader.
- The filters and parameters applied, written in plain language.
- The identity that ran the query and the version of the tool that produced the result.
- The number of rows returned and whether the row cap truncated the result.
Use the same block format every time, so reviewers learn to read it quickly. Behind the scenes, each tool call should also carry a correlation identifier, which lets an engineer trace a complaint back to the exact request. The OpenTelemetry observability primer explains the traces, spans and signals that many teams use for this kind of tracing.
Test answers against the warehouse before anyone relies on them
Before the agent answers real questions, build a small test set whose correct answers you already know, usually because someone on the team has checked them. Run the agent against that set after every change to tools, schemas or the underlying model. A pass means the agent returns the same figures as a direct, reviewed query and names the correct view in its lineage note.
Include questions the agent should refuse or escalate, such as a request for one customer's contact details or a question about a table it cannot read. A well-behaved agent says it cannot answer and names the owner to contact. Also treat any free text returned from a warehouse row as data, never as an instruction, because a comment field can contain sentences that look like commands.
Decide what the agent may never do alone
In the first phase, the agent reads and explains. Its boundaries should be written down before launch:
- Answering from curated views with lineage notes attached: the agent may respond directly.
- Drafting a suggested change to a query, a view or a data quality ticket: the agent drafts, and a data owner reviews before anything moves.
- Writing to any reporting or warehouse table: not in the first phase. Later, it requires a named owner, an approval step and a write path designed so a retry cannot duplicate a record.
- Changing grants, schemas or tool definitions: never performed by the agent. Only people change these, through the normal change process.
These boundaries matter more as the agent improves, because capability and authority should grow in separate steps.
Keep the tool layer under review as the warehouse changes
Warehouses change. Columns get renamed, models are rebuilt and teams reorganize. Each change can quietly break a tool or widen access that nobody intended. Put the grant review, the test set and the lineage notes on a recurring calendar, and name an owner who receives alerts when a tool fails or a view is retired.
Be Human designs this layer as part of one defined role. The first engagement establishes the useful question, the views and tools the agent needs, the approval boundaries and an observable success check. In managed operations, Be Human can monitor tool failures and lineage notes, run recurring evaluations against the test set, review the agent's permissions, maintain integrations when schemas change, respond to incidents, and make controlled improvements through the same approval path. The work is remote and available in English or Portuguese.
If you are not yet sure which warehouse question should go to an agent first, the free Be Human AI diagnostic will help you find the first task worth handing over.
Frequently asked questions
Should the agent query raw warehouse tables or curated views? Curated views are the better starting point because they already encode the business definitions your team agreed on, and they can be reviewed and refreshed in one place. Raw tables can be added later for specific roles, but each one needs its own grant, its own exclusions for personal data and its own lineage entry.
Is a read-only database account enough to make an agent safe? Read-only access is necessary but not sufficient. It blocks writes at the database level, yet it does not stop an agent from reading data a person should not see, returning too many rows or repeating sensitive content in a reply. Pair the grant with narrow tools, row caps, field exclusions and a test set that includes refusals.
How are lineage notes different from application logs? Logs record events so engineers can debug, and they are often written in formats managers cannot easily read. Lineage notes are short records attached to a specific answer that state the objects read, their refresh time, the filters applied and the identity used. Keep both: logs support incident response, and lineage notes support trust in each answer.
When should a team consider letting the agent write to the warehouse? Consider it only after read use is stable, the test set passes consistently and a named owner accepts the write path. Writes should go through a defined tool with validation, an approval step and an idempotent design so a retry cannot create a duplicate. Until then, the agent drafts the change and a person applies it.
Your next step
See where an AI agent fits in your company first.
Take the free Be Human AI diagnostic. A few questions about your work show which task to hand to an agent first, what it needs to know and where a person approves.
Be Human editorial guidance. Examples are illustrative unless explicitly attributed. Sources provide background; implementation choices depend on your workflow.


