Semantic layer for AI agents: architecture, tools and how to build one

A semantic layer built for dashboards has a different caller

Our guide on what a semantic layer is covers the definition. This post assumes you know the concept and want to know what changes when the caller is a model.

A dashboard author is a person who knows the business, picks a metric on purpose and notices when a chart looks odd. An agent arrives with a loosely worded question, chooses from whatever the layer exposes, and will write something plausible if it finds nothing suitable. So the layer’s job grows. Beyond calculating correctly, it now has to be found by a search, explain itself to a reader that takes descriptions literally, and behave predictably at its own edges.

The published evidence supports investing here, within limits. A 2023 benchmark on an insurance schema found GPT-4 reached 16 percent accuracy asking directly over SQL, and 54 percent over a knowledge graph representation of the same database. That’s one domain, one older model, and a knowledge graph instead of a metrics layer. Take the direction from it, and test any vendor multiple on your own questions.

Stable meaning is the goal

Tooling discussions can obscure what you are trying to achieve: the same word means the same thing across interfaces, teams and model changes, or the difference is visible and has an owner. Revenue, customer and growth are familiar words with organization-specific meanings. When an executive asks about growth, the word might refer to revenue, customers, margin or volume. A system that chooses one immediately appears efficient while possibly moving the discussion away from the decision at hand.

Two reports can disagree because each uses a legitimate definition. The system should expose that as a business fact. Treating every mismatch as a data defect or a model error sends people hunting for a bug that does not exist. I’d run one experiment before any vendor comparison, and it takes an hour: give two teams a familiar metric name, and ask each to write the definition independently. Compare the results, including exclusions, currency, date basis and treatment of returns. The differences are your backlog, and they show where a glossary alone will not be enough and the definition has to appear beside the number.

One set of definitions, many callers

The diagram shows the target shape, and the idea behind the phrase universal semantic layer: one governed definition serving several kinds of consumer. Nothing about this requires a single product. It requires that an agent, a dashboard and a scheduled report resolve a metric name to the same logic, and that you can prove it. If your BI tool and your agent hold separate definitions of net revenue, you have two semantic layers and a reconciliation problem. MCP has become a common way to expose this to agents: the layer lists its measures, dimensions and descriptions, and the agent requests what it needs.

Where the definitions can live

Semantic layer tools fall into a few patterns, and the choice matters more than feature lists suggest. The main axis is where definitions and enforcement sit. These notes come from each vendor’s documentation at the time of writing. All of this moves quickly, so verify anything you plan to depend on.

Portability is improving without being solved. The Open Semantic Interchange work, now hosted as Apache Ossie in incubation, aims at a shared standard for moving definitions between tools, with working groups covering metrics, converters and catalog alignment. The Apache project page notes that incubation does not necessarily indicate completeness or stability. I’d track it, since it may lower the cost of a later move, and I wouldn’t treat it as a reason to skip choosing today.

Three traps agents walk into

The first is the coverage cliff. Your layer holds perhaps a few dozen metrics, and people ask about everything. A closed design refuses the rest: truthful, and frustrating. An open design lets the model write SQL using the layer as context: useful, and less certain. Choose deliberately, and either way make the answer say which path it took. A system that falls back to generated SQL without saying so, while appearing governed, is worse than one that refuses.

The second is the permission model of the layer itself. Snowflake’s documentation for querying semantic views states that you do not need SELECT on the tables used in the view, only on the view. A delegated privilege model is a legitimate design. But teams who assumed that table grants still governed everything may have just widened access. The querying page we read did not say how row access and masking policies apply, so test that with two identities on your own account. The same test fits any other product: grant the layer, remove table access, and see what comes back.

The third is fan-out at the edge of what is allowed. Layers worth using refuse combinations that would give wrong numbers. Snowflake’s rule is that a dimension can combine with a metric only if its table is related and at an equal or lower level of granularity, and its docs show a per-customer metric rejected when split by order date. MetricFlow uses entity types to avoid fan-out and chasm joins. An agent will hit these refusals constantly, so the error has to be readable by a model. Expose the allowed dimensions for each metric, since a tool that lists them before the call saves a failed round trip.

Writing for a model as reader

Existing definitions are usually written for people who already know the context. For an agent, add the following, and keep it versioned with the definition. Descriptions are effectively prompts, so a careless edit can change behavior as surely as a formula change can. That means they deserve review and a place in your regression suite.

metric: net_revenue
label: Net revenue
description: >
  Invoiced amount after discounts and returns, before tax.
  Use for revenue questions unless the person asks for bookings.
synonyms: [revenue, sales, invoiced revenue]
not_to_be_confused_with:
  gross_bookings: Signed contract value; includes unbilled amounts
formula: sum(fct_invoices.net_amount)
filters: [dim_accounts.is_internal = false]
time_basis: invoice_date
currency: reporting currency; do not sum transaction currency
group_by_allowed: [region, product_line, customer_segment, month]
owner: finance-data@example.com
status: approved
reviewed: 2026-09-30
example_questions:
  - What was revenue in EMEA last quarter?

Build it without boiling the warehouse

Most programs fail by attempting a complete model before anyone gets value. Work outward from conflict. This order assumes a small team with an existing warehouse.

• Collect the disputesRun the two-team exercise on five metrics that leadership argues about. Pick the ones with an identifiable owner willing to decide.
• Write down the decisionRecord the meaning, the exclusions, the owner, and which legitimate alternatives exist. Name alternatives as separate metrics, so nobody has to pretend they do not exist.
• Encode only thosePick the pattern from the table that fits where your people already work. Five metrics that are right beat two hundred imported from dashboards nobody has checked.
• Write the evaluation firstFor each metric, create questions with known answers, including synonyms, a question that should prompt a choice, and one that should decline. Grade on returned results.
• Run the permission testTwo identities, same question, complete response compared, before anyone outside the team connects.
• Expose through one consumerConnect an agent, watch which terms fail to resolve, and let that list set your next five metrics.
• Assign review datesA definition without an owner and review date is a guess that has aged. Our guide on who owns what a number means covers the operating model.

Definitions change, and answers have to remember

An approved definition will change: finance reclassifies a product line, or an acquisition alters what counts as a customer. Dashboards tend to restate history without telling anyone when that happens. An agent adds a new problem, because last month’s answer lives on in a shared conversation or a pasted slide. Version every definition, record the version on each answer, and decide whether a change applies to past periods. Then when someone asks why a figure moved between two reports, the system can distinguish a change in the data from a change in the meaning.

A usability check for meaning

Accuracy tests miss whether people can use a definition. Ask someone to find the definition behind a number, change one scope condition, and explain why the result differs from a report they know. Watch where they get stuck. Try it again with a new user, a different interface and a changed reporting period, because a definition that holds only in one prepared demo has little organizational value. Include a disputed metric in any vendor demonstration you attend. A flawless example with a preselected definition proves much less than a controlled look at how the workflow handles disagreement.

How we treat definitions

Nexatron labels where each answer’s definition came from: Approved, Team-defined, Standard, Learned or Interpreted, the last being a reading nobody has confirmed. A measure with several meanings that give different answers gets one question naming them, and a lone approved meaning gets an answer with no question. Over MCP, query_metric runs approved definitions only. Shared, scheduled and embedded answers stand only on approved, customer or standard definitions and catalog relationships, and decline otherwise, while interactive answers may interpret and say so. Those behaviors line up with the coverage matrix, and you should check us: try a contested metric and see which cell you land in.