A semantic layer for AI agents defines each business term once, with an owner and a version. Every agent then reaches your data through one MCP entry point that applies those definitions and runs each call as the user. The entry point enforces the same policies whichever client asked, returns citations with every figure, and logs every call.
Key facts
Definition
A semantic layer for AI agents defines each business term once, with an owner and a version, and serves it to every agent through one MCP entry point that runs each call as the user.
How Bigcircle does it
- On DocVerse, Bigcircle records the framework-mapping version on each extracted fact, so a later comparison can tell a company change from a restatement or a change in how the filing was read.
- On a current telecom engagement, Bigcircle's analytics agent returns every answer with the query it ran, the tables, the filters and its assumptions, and the queries are captured so a result can be reproduced.
- Bigcircle recommends running a fixed list of disputed questions through every client before it moves onto the layer, because the cross-client check catches the failures that matter most.
Comparison
Agents that each keep their own definitions give three numbers for one question, while one entry point with owned, versioned definitions makes them answer from the same term and name the version they used.
Key number
Databricks' earlier beta endpoint for its Genie One MCP server is deprecated and sunsets on 31 October 2026, per Microsoft's documentation.
Sprawl is hard to prevent because each agent arrives with its own copy of the business. A coding agent reads a metric definition from a comment in the codebase. A chat assistant was set up with a system prompt that someone wrote during a pilot. A custom agent uses a retrieval index built last quarter, and a BI tool has its own semantic model, the metric definitions its dashboards use. Each one is correct by its own setup, and in the same meeting they produce three numbers for one question.
This guide covers why sprawl produces conflicting numbers, what the semantic layer holds, why tables and documents belong behind one entry point, and what every answer must carry. It then covers identity and audit under the 28 July 2026 MCP specification, how to test that agents agree, and how to move existing agents across. The tool shape and the access model have their own guides, on MCP tools and AI agent permissions.
Why does agent sprawl produce conflicting numbers?
The definition of a business term usually lives in the client, and every client has its own. When a team adds an AI agent, it configures that agent's context for the task in front of it: a few metric definitions in the prompt, a connection to the tables it needs, and an index over the documents the pilot used. That setup works, and it is invisible to the next team, who configure their own.
Staleness is the part teams notice last. A definition pasted into a prompt at setup does not change when finance changes the metric, so the agent goes on answering with the old formula and nothing flags it. Nobody is wrong in a way a single team can fix, so the reconciliation falls to people, every time.
The three definitions of "active customer" in the figure are examples of the kind of divergence we mean. They do not come from any client or survey, and each one is defensible, which is why the numbers disagree without anyone being at fault.
We met the same problem in document work before agents made it common. On DocVerse, our ESG filings pipeline, retrieving the right phrase from the wrong reporting year looks exactly like success. Two disclosures against different versions of one reporting framework have not reported the same number, and comparing them without tracking the version produces a trend that does not exist.
The pipeline records the framework-mapping version on each extracted fact rather than holding it globally. A later comparison can then say whether a number moved because the company changed, because a filing was restated, or because the mapping changed. Around that sits a governed store with role-based access, audit logs and lineage back to the source page, which is the same shape this guide gives to business definitions.
What goes in a semantic layer for AI agents?
The layer holds meaning, not data. Data stays in the warehouse, the document stores and the operational systems. The layer holds what the words mean, which records the words refer to, and who may see what. Some platforms call this an ontology, and the name matters less than the contents.
| Element | What it holds | Example | Who owns it |
|---|---|---|---|
| Metric definitions | Formula, level of detail, filters, time basis | Net revenue retention, by account, trailing twelve months | The team accountable for the number, often finance |
| Entities and keys | What a customer, account or region is, and how IDs map across systems | One account ID across the CRM, billing and support | Data platform, with the system owners |
| Synonyms | Which words map to which definition | "NRR" and "net retention" resolve to one metric | Whoever owns the metric |
| Authoritative documents | Which collections answer which questions, and how fresh they must be | The current pricing policy, not last year's draft | The function that publishes the documents |
| Access policies | Who may see which rows, columns and documents | Regional managers see their own regions | Security, with each data owner |
| Versions | When each definition changed, and what it was before | Retention excludes one-off services from a stated date | Each owner, through review |
Give every definition an owner and a version before any agent uses it. Without an owner, a disputed number has nowhere to go, and the agent that reported it gets blamed for a disagreement it inherited. Without a version, you cannot reproduce last quarter's answer after the formula changes. Store the version with each answer, as DocVerse stores it with each fact, and not as one global setting that silently moves every past answer when it changes.
Synonyms need more care than they look like they need. People ask for "revenue" and mean one of several things, and a layer that resolves an ambiguous word silently has made a business decision nobody reviewed. When a term maps to more than one definition, the layer should ask, or state which definition it used in the answer.
Why put structured and unstructured retrieval behind one entry point?
Put them behind one entry point. Real business questions cross the line between tables and documents. "Why did EU retention drop last quarter?" needs the number from governed tables and the explanation from account notes, support tickets and a pricing change memo.
If those are two separate tools, the agent joins them itself. It may resolve "EU" one way for the query and another way for the document search, and the answer mixes two definitions without saying so. One entry point resolves the terms once, and every retrieval path behind it, query or document search, uses that resolution.
The pattern does not depend on the vendor. Where your data sits decides the build. Databricks' Genie One MCP server, announced on 22 September 2026, puts structured and unstructured retrieval behind one interface grounded in its governed ontology, so on Databricks the layer and the entry point come together. If your data already sits there, note that the server's earlier beta endpoint is deprecated and, per Microsoft's documentation, sunsets on 31 October 2026.
If your data spans more than one platform, a layer bundled with one vendor resolves terms only for the data on that platform, and agents on the second platform keep their own definitions. In that case build term resolution as its own service in front of both, on your own warehouse and document stores, so agents on every platform answer from the same definitions.
The five layers are a design we recommend for any build, whether a managed service provides some of them or not. The audit log spans the full height because a refused call at the entry point matters as much as a completed query at the bottom.
Behind the entry point, the two retrieval paths still work differently. Structured questions become queries over governed tables, and the query text is part of the answer. Unstructured questions go through retrieval over the authoritative collections, and the guide to RAG in production covers what breaks there. Document retrieval stays as hard as it was. The layer adds one thing to it, which is that the document search and the query agree on what the question meant.
What must every answer carry?
An answer from the layer is a record, not a sentence. The agent can phrase it however the client needs, but the layer should return enough for anyone to check it later. If the layer returns only prose, the agent passes along a number nobody can trace, and a second agent with a different number starts the same argument.
| Field | Why it is there |
|---|---|
| The answer | The value or the passage that answers the question |
| Definition and version | Which meaning of each term was used, so two answers can be compared |
| Query or passages | The query that ran, with its tables and filters, or the passages that were read |
| Citations | Links back to the tables and documents, precise enough to open |
| As of | When the data was last updated, so a stale figure is visible |
| Policy applied | What the caller's access filtered out, stated plainly |
| Status | answered, ambiguous, not_permitted or no_data, never an empty answer that means one of them |
On a current engagement building agents for a telecom marketing platform, the analytics agent returns every answer with the query it ran, the tables, the filters and the assumptions it made. The queries are captured, so a result can be reproduced later. The agents are being built for production, and in this phase every agent action is proposed by the agent and approved by a person. With the query, tables and filters attached, someone can settle a disputed number by reading the record instead of rerunning the conversation.
The status field guards against hallucination in a way a prompt instruction cannot. An agent that receives an empty result will often fill the gap. An agent that receives not_permitted with a reason can tell the user they lack access, and one that receives ambiguous with the candidate definitions can ask. A groundedness check needs the citations too, because a claim can only be checked against a source the answer names.
The example question is illustrative. Each step's stop condition is the behavior to require of the layer, not a description of a specific product.
The Prospex build applies the same rule at generation time, with an evidence lock: a claim without a supporting retrieved passage does not appear in the output. A semantic layer for agents applies it one step earlier, at retrieval, so that every client starts from evidence that already carries its definition and source.
How should the layer handle identity, policy, and audit?
Run every call as the user who asked, not as a service account. A shared credential means every agent sees what the most privileged integration sees, and the audit trail records the integration, not the person. As of the 28 July 2026 MCP specification there are no protocol sessions, so the client sends the user's token on every request and the entry point validates it each time.
The same specification forbids the entry point from passing the user's token through to the systems behind it. Keep the data credentials inside the layer, where the model never sees them, and apply the user's entitlements in the layer's own policy before any query runs.
On the telecom engagement above, the analytics agent reads through a data layer that shows it only the tables, columns and rows the asking user is entitled to. Personal data is masked or dropped by the client's policy rather than by an instruction in the prompt, so the masking holds even when a prompt is ignored or rewritten.
Enforce policy at the entry point, once, for every client. Row filters, column masks and document permissions should give the same result whether the question came from an IDE, a chat assistant or a scheduled agent. When the policy lives in each client instead, the clients drift apart on access the same way they drifted apart on definitions.
Log every call, allowed or refused, with the user, the client, the resolved definitions and their versions, the sources read, and the status returned. That record lets you answer who saw which number, under which definition, and when.
An AI audit trail needs more in the record when an answer feeds a decision someone has to defend. The same log shows which definitions are asked about most and which come back ambiguous, which tells the owners where to spend their review time.
How do you test that every agent gets the same answer?
Test the layer the way a skeptical analyst would, by asking the same thing from different places and comparing. These checks go into the eval set, and they run before any client moves onto the layer and again after every definition change.
| Check | Pass | Fail |
|---|---|---|
| Same question from three clients | The same value, definition version and citations | Different values, or the same value with different definitions |
| An ambiguous term | The layer asks, or names the definition it chose | A silent choice |
| A user without access | not_permitted, stated to the user | An empty result the agent reports as "none" |
| A definition change | Every client reflects it after publication, and the old version still reproduces | One client lags, or last quarter's answer cannot be rebuilt |
| A document answer | Each citation opens the passage that supports the claim | A citation that resolves to the right file and the wrong section |
| Stale data | The as-of date appears with the answer | A number with no date |
The cross-client check catches the failures that matter most, and it is easy to automate. Keep a fixed list of questions that people have argued about, run each through every client you support, and fail the build if the answers disagree. The guide to LLM evaluation covers how to turn those arguments into test cases, and the reconciliation meetings you already hold are the best source of questions.
How do you move existing agents onto the layer?
Most organizations already have several agents in use, each with its own embedded definitions. A migration that stops all of them at once will not get approved, and it does not need to. Move one client at a time, and remove local definitions as each one moves.
- Inventory where definitions live today: system prompts, repository comments, BI semantic models and retrieval indexes. The list is usually longer than anyone expects, and it is the scope of the work.
- Start with the terms that already cause arguments. Assign each an owner, write the definition, and give it a version.
- Stand up the entry point with read-only tools, running as the user, with the response record and the audit log from the first release.
- Move the client with the most visible disagreements first. Delete its local definitions when it moves, or it will keep using them.
- Add documents and write actions only after the read path has held up, and give write actions their own permission review.
A single agent over a single source does not need this layer. It needs good tools, which the guide to MCP tools covers, and good workflows, which the guide to MCP prompts covers. The semantic layer is worth building when a second client starts answering questions about the same business. Bigcircle's MCP servers and RAG systems work covers this layer.
Common questions
What is a semantic layer for AI?#
A semantic layer for AI is one service that holds what your business terms mean, which records they refer to, and who may see what. Every AI agent reaches it through a single MCP entry point. Each definition has an owner and a version. The entry point runs each call as the user, applies the same policies for every client, returns citations and the definition used with every answer, and logs every call.
Why do different AI agents give different numbers for the same question?#
Each agent was configured with its own definitions: a formula in a system prompt, a semantic model in a BI tool, or an index built for a pilot. Each setup is correct on its own terms, so the agents disagree without any of them being broken. Definitions pasted in at setup also go stale when the business changes the metric, and nothing warns anyone.
How is a semantic layer for AI agents different from a BI semantic layer?#
They overlap. A BI semantic layer defines metrics over tables for dashboards. A semantic layer for AI agents, sometimes called a context layer, also covers documents, synonyms, entity mapping across systems, access policies and versions. It is reached through MCP, so any agent can use it. If you already have a BI semantic layer, it is a good source for the metric definitions, and the layer for agents should read from it rather than copy it.
Do we need to buy a platform to build one?#
No. The pattern is one entry point, governed definitions with owners and versions, retrieval that uses them, per-user identity, policy at the entry point, citations and an audit log. Managed MCP services from data platform vendors, such as the Databricks server announced in September 2026, package much of it for data already on their platform. If your data spans more than one platform, build term resolution as its own service in front of all of them, on your own warehouse and document stores.
How does the layer handle permissions?#
It runs every call as the user who asked and validates the user's token on every request, as the 28 July 2026 MCP specification requires. It keeps the data credentials inside the layer where the model never sees them, because the specification forbids passing the user's token through. Row filters, column masks and document permissions are enforced at the entry point, and a user without access gets a not permitted status rather than an empty answer.
How do we test that our agents agree?#
Keep a fixed list of questions people have argued about and run each one through every client you support. The value, the definition version and the citations should match. Add checks for ambiguous terms, users without access, stale data and definition changes, and run them before each client moves onto the layer and after every definition change.
Further reading
- MCP tools. How to shape the tools behind the entry point.
- MCP prompts as agent playbooks. How agents find and run your workflows once they share definitions.
- AI agent permissions. The access model for any action the layer allows.
- AI agent memory isolation. Keying memory and credentials to the person each call runs as.
- Text to SQL analytics agents. The metric layer and SQL gates inside one analytics agent, where this guide covers many agents sharing definitions.
- RAG in production. What breaks on the unstructured retrieval path.
- LLM evaluation. Turning disputed questions into a cross-client test set.
- AI audit trails. What the call record needs when an answer feeds a decision.
- Per-field confidence and the claim-to-evidence path. How we built DocVerse, with versioned framework mappings.
- Databricks, The Genie One MCP is now Generally Available, 22 September 2026. A managed MCP entry point grounded in a governed ontology, with policies and audit logging.
- Microsoft Learn, Genie One MCP server, updated 16 October 2026, for the beta endpoint's sunset date.
- Model Context Protocol, Authorization, revision of 28 July 2026. Per-request token validation and the ban on token passthrough.