An agentic semantic layer is a metadata layer between AI agents and a data warehouse that defines business metrics, enforces access control, and exposes governed query interfaces. Instead of writing raw SQL, agents query metric definitions through protocols like MCP (Model Context Protocol) or REST APIs. Every agent gets the same answer because the business logic is defined once, not interpreted per query.
The "agentic" distinction matters. Traditional semantic layers were built for BI dashboards and human analysts. An agentic semantic layer is built for programmatic consumers: LLMs, AI agents, SDKs, and applications. The interface, security model, and deployment patterns are different.
AI agents are becoming a primary interface to data. Executives ask Claude for quarterly numbers. Product managers ask Cursor for usage metrics. Customer success teams ask chatbots for account health scores. The agent is the new dashboard.
But most data infrastructure wasn't built for this. Two problems dominate.
The default approach: give an agent access to your warehouse and let it write SQL. It works in demos. In production, three failure modes show up every time.
Inconsistent answers. Ask Claude "What was Q1 revenue?" It writes a query summing amount
from orders
where created_at
falls in Q1. Reasonable. Ask GPT the same question. It filters on status = 'completed'
first, then sums. Different number. Also reasonable. Neither agent knows that your finance team excludes refunds and trial conversions. That logic lives in a Notion doc that got updated six months ago. The agents don't have access to it. They generate plausible SQL from column names and return plausible numbers that don't match anything your team reports.
This isn't a model quality problem. It's a context problem. The agent sees schema, not semantics. Better models produce better-looking SQL that's still wrong in the same ways.
No access control. You're building a B2B product. Customer A asks your agent a question. The agent writes SQL against the warehouse. Nothing in the text-to-SQL pipeline enforces that Customer A only sees Customer A's data. You can patch this: add tenant filters to prompts, write middleware that rewrites queries, build a validation layer. Each patch is a new surface for bugs. One missed filter is a data leak in production.
No audit trail. When your CFO asks "where did this number come from?", the answer is "an LLM generated some SQL." You can't trace which metric definition was used because there wasn't one. You can't reproduce the result because the prompt context has changed. You can't prove the number was correct because correctness wasn't defined.
Traditional semantic layers solve the consistency problem for dashboards. Looker's LookML, Tableau's semantic model, Power BI's DAX measures. They define metrics once and serve them to BI consumers. That's genuinely useful.
But they were designed for a world where a human browses a catalog, selects metrics, and views a dashboard. That interaction model doesn't translate to AI agents.
Agents don't browse catalogs. They call tools at runtime. They need programmatic discovery (what metrics exist?), programmatic querying (give me revenue by region for Q1), and programmatic access control (this agent represents Tenant X and can only see Tenant X's data). They need this over a standardized protocol, not a proprietary query language embedded in a BI tool.
A BI-embedded semantic layer can't serve an MCP client. It can't issue publishable keys per tenant. It can't serve a React SDK, a TypeScript SDK, and a markdown dashboard from the same definitions. The interface is wrong.
That's what an agentic semantic layer changes.
| Traditional semantic layer | Agentic semantic layer | |
|---|---|---|
| Primary consumer | ||
| BI dashboards, analysts | AI agents, LLMs, applications | |
| Interface | ||
| SQL, proprietary query language (LookML, DAX) | MCP, REST API, SDK | |
| Discovery | ||
| Human browses a catalog in a GUI | Agent calls explore_schema at runtime |
|
| Multi-tenancy | ||
| Often manual or absent | Per-query enforcement, publishable keys per tenant | |
| Access control | ||
| Dashboard-level or role-based | Row-level, per-consumer, structural | |
| Query volume | ||
| Dozens of dashboard refreshes per hour | Hundreds of agent queries per minute | |
| Caching | ||
| Dashboard-level refresh | ||
The core shift: an agentic semantic layer treats programmatic access as the primary use case, not an afterthought. MCP support, multi-tenant keys, and row-level security aren't add-ons. They're the foundation.
An agentic semantic layer needs five capabilities to work in production. Missing any one of them and you'll end up rebuilding it later.
Metrics defined in YAML or a similar declarative format that both humans and machines can read. Not trapped in a GUI. Not embedded in a proprietary tool.
cubes:
- name: orders
sql_table: public.orders
measures:
- name: total_revenue
sql: "CASE WHEN status != 'refunded' AND type != 'trial' THEN amount ELSE 0 END"
type: sum
description: "Total revenue excluding refunds and trials"
- name: order_count
type: count
dimensions:
- name: status
sql: status
type: string
- name: category
sql: category
type: string
- name: created_at
sql: created_at
type: time
total_revenue
is now a governed definition with a description the agent can read. Deploy this schema and any MCP-compatible agent (Claude, Cursor, or any client supporting the protocol) can discover and query these metrics at runtime.
The description
field matters more than it looks. When an agent calls explore_schema
, descriptions are what it uses to decide which metric answers the user's question. Good descriptions are the difference between an agent that picks the right metric and one that guesses.
Agents need a standardized way to find out what metrics exist and query them. This is what MCP (Model Context Protocol) provides.
The agent calls explore_schema
to see available cubes, measures, and dimensions. It reads descriptions to understand what each metric represents. Then it calls query
with the right measures, dimensions, and filters. It never writes SQL. The semantic layer handles query generation, execution, caching, and access control.
Agent: explore_schema → "orders cube has total_revenue, order_count, status, category, created_at"
Agent: query(measures: [total_revenue], dimensions: [status], filters: [{created_at: last 90 days}])
Semantic layer: generates SQL, executes against warehouse, returns structured result
This is fundamentally different from text-to-SQL. The agent isn't interpreting column names. It's selecting from governed definitions. The query isn't generated by the LLM. It's generated by the semantic layer's query engine, which knows how to write correct SQL for your specific warehouse dialect.
Five tools make this work:
explore_schema
query
sql_query
describe_field
visualize
If you're building a B2B product, every agent query needs to be scoped to a specific tenant. This can't be a prompt-level instruction ("only show data for customer X"). It needs to be structural: impossible to bypass regardless of what the agent does.
security_context:
- name: tenant_filter
sql: "{SECURITY_CONTEXT.tenant_id} = customer_id"
Every query for a given tenant automatically includes this filter. The consumer can't skip it. The agent can't override it. Generate a publishable key per tenant, and that key carries the security context. The agent authenticates with the key and every query is automatically scoped.
This is how you ship AI-powered analytics to B2B customers without building a custom access control layer. The semantic layer handles isolation. You handle the product.
AI agents make more queries than humans. A human refreshes a dashboard once. An agent might make 10 queries to answer one question: exploring the schema, trying different dimensions, following up on anomalies.
Pre-aggregation handles this. Define which metric combinations to pre-compute:
pre_aggregations:
- name: daily_revenue
measures:
- total_revenue
- order_count
dimensions:
- status
- category
time_dimension: created_at
granularity: day
refresh_key:
every: 1 hour
The semantic layer builds and maintains these rollups. Hot queries hit the cache (single-digit milliseconds). Cold queries fall through to the warehouse. Without this, agent workloads can overwhelm your warehouse, especially when multiple customers' agents are querying simultaneously.
Pre-aggregation isn't a performance optimization. At agent scale, it's a requirement.
Metric definitions should live in Git. Changes should go through pull requests. Rollbacks should be git revert
.
This isn't just good engineering practice. It's how you maintain trust in an agentic system. When someone asks "why did the revenue number change?", the answer is a Git commit, not "someone clicked something in the admin UI." When a definition is wrong, you revert it and every consumer immediately gets the corrected version. No agent retrained. No dashboard patched. One diff in your schema repo.
git diff HEAD~1 schema/orders.yml # see what changed
git revert abc123 # undo a bad metric definition
Different teams interact with the agentic semantic layer differently. The common thread: everyone benefits from one source of truth for metric definitions.
Data engineers and analytics engineers define the metrics. They write the YAML, review changes in PRs, and manage pre-aggregation strategies. The agentic semantic layer gives them a single place to define business logic instead of maintaining it across dashboards, notebooks, and custom API endpoints.
Engineering leads and product teams consume the metrics. They connect AI agents via MCP, build features on the REST API, and let agents chart query results in the conversation. The semantic layer means they don't need the data team to build a custom endpoint for every new feature.
Data leaders govern the metrics. They ensure definitions are correct, access controls are appropriate, and audit trails are maintained. The semantic layer centralizes governance instead of distributing it across tools.
Customers (in B2B products) query their own data. Through embedded dashboards in your product, through AI agents connected via publishable keys, or through APIs. The semantic layer ensures they see only their data, with the same metric definitions your internal teams use.
An agentic semantic layer doesn't replace your existing infrastructure. It sits on top of it.
[Data Sources] → [Ingestion (Fivetran, Airbyte)] → [Warehouse (Snowflake, BigQuery)]
↓
[dbt transformations]
↓
[Agentic Semantic Layer]
↙ ↓ ↘
[MCP Agents] [React SDK] [REST API]
[Dashboards] [TypeScript SDK]
Your ingestion pipeline feeds raw data into the warehouse. dbt transforms it into clean tables. The agentic semantic layer defines business metrics on those tables and serves them to every consumer through the appropriate interface.
The semantic layer connects to your warehouse (Snowflake, BigQuery, Databricks, PostgreSQL (including Supabase, Neon, and RDS), Redshift, DuckDB (including MotherDuck)) and generates the appropriate SQL dialect. Swap warehouses without changing your metric definitions or consumer integrations.
This is the key architectural property: the semantic layer decouples metric definitions from both the warehouse and the consumer. Change your warehouse and consumers don't notice. Add a new consumer and the warehouse doesn't change. The semantic layer is the stable interface between infrastructure and applications.
| Tool | Agent support | Multi-tenancy | Pre-aggregation | Open source | Primary use case |
|---|---|---|---|---|---|
| REST API (no MCP) | Manual | Yes (battle-tested) | Yes | Headless BI, API-first analytics | |
| dbt MetricFlow | |||||
| None | None | None | Yes | Metric documentation in dbt | |
| Looker (LookML) | |||||
| None | Manual | Limited | No | Enterprise dashboard BI | |
| AtScale | |||||
| Partial | Enterprise | Virtual caching | No | Enterprise BI compatibility | |
| ThoughtSpot | |||||
| Proprietary ("Spotter") | Enterprise | Proprietary | No | AI-powered BI platform | |
MCP visualize tool |
|||||
Via your runSql |
|||||
| Via your warehouse | Yes | Charts agent query results in Claude/ChatGPT |
The right choice depends on whether AI agents are your primary consumer or a secondary integration. If agents are an afterthought, most semantic layers can be retrofitted with API access. If agents are the primary interface, you need a layer designed for programmatic consumers from the ground up.
An agentic semantic layer gives the agent governed metrics to query. The last mile is what the agent shows the user: not a wall of numbers, a chart in the conversation. That's what @bonnard/mcp-charts adds, a
visualize
tool you register on your MCP server in a few lines.
npm install @bonnard/mcp-charts
js
import { addCharts } from "@bonnard/mcp-charts";
// your data, your connection. Bonnard never touches the database
addCharts(server, { runSql });
The agent calls visualize
with a query, your runSql
returns the rows, and Bonnard infers the chart from the typed result, then renders an interactive widget in Claude or ChatGPT. Native adapters ship for Postgres, BigQuery, Snowflake, Databricks, and DuckDB, or pass your own runSql
. It renders line, bar, area, pie, scatter, funnel, waterfall, and table.
For the full walkthrough, see MCP Charts. For the design behind an agent-friendly chart tool, see How Bonnard Builds Agent-Friendly MCPs. For a broader look at semantic layers beyond the agentic use case, see What Is a Semantic Layer?.
Repo: github.com/bonnard-data/mcp-charts.
A semantic layer is a translation layer between raw data and the people or tools that query it. It defines what business terms like "revenue" or "active user" mean in terms of actual database columns and calculations. Instead of every consumer writing its own SQL, they all reference the same definition. See What Is a Semantic Layer? for the full guide.
Three things: programmatic discovery (agents find metrics via API, not a GUI catalog), programmatic querying (agents call tools, not SQL), and structural multi-tenancy (access control enforced per query, not per dashboard). A traditional semantic layer might have an API, but an agentic one is designed for agents as the primary consumer.
RAG (Retrieval-Augmented Generation) feeds unstructured documents to an LLM for context. An agentic semantic layer provides structured metric definitions for data queries. RAG answers "What does our refund policy say?" A semantic layer answers "What was Q1 revenue?" They solve different problems and are often used together: RAG for knowledge, semantic layer for data.
Text-to-SQL lets an agent generate arbitrary SQL from natural language. The agent interprets column names and guesses business logic. An agentic semantic layer defines metrics once and lets agents query those definitions. The difference: text-to-SQL produces plausible answers. A semantic layer produces correct, governed, auditable answers. See text-to-SQL for more on why the raw approach breaks in production.
dbt defines transformations: how raw data becomes clean tables. An agentic semantic layer defines metrics: what "revenue" means on top of those tables, and serves them to agents with caching and access control. They're complementary. dbt gets data into shape. The semantic layer defines the business logic on top and serves it. Most agentic semantic layers can import dbt models directly.
MCP (Model Context Protocol) is a standard protocol for connecting AI agents to external tools and data sources. It defines how agents discover available tools, call them, and receive results. For an agentic semantic layer, MCP is the interface that lets any compatible agent (Claude, Cursor, Claude Code, and others) discover and query your metrics without custom integration code.
Yes. A semantic layer with MCP support works with any MCP-compatible client. For other agents, REST APIs and SDKs provide model-agnostic access. The semantic layer sits between the agent and the warehouse, not inside the model. It doesn't matter whether the agent runs Claude, GPT, Gemini, or an open-source model.
With pre-aggregation, queries get faster, not slower. The semantic layer caches rollups so agents query pre-computed results instead of running full aggregations on every request. Hot queries resolve in single-digit milliseconds. Without pre-aggregation, agent-scale query volumes (hundreds of queries per minute across multiple tenants) will overwhelm most warehouses.
It eliminates the primary source of data hallucinations: ad-hoc SQL generation. The agent never writes SQL. It selects from governed metric definitions and the semantic layer generates correct SQL. The agent can still hallucinate its interpretation of the results (that's a model problem), but the underlying data is always correct and traceable to a versioned definition.