Omni Semantic Layer Architecture: AI Agents and the Future of Analytics

Giving an AI agent access to your database is the easy part. You now need to get it to return answers your team can actually trust, and also write those answers into the tools developers already use. This is the architecture challenge and I will show you how to solve it with the Omni semantic layer architecture.

Database access is not enough

AI analytics implementations tend to start the same way: connect an LLM to a database, write a system prompt describing the schema, generate SQL. This works in demos but struggles in production.

Let’s not rush to blame the compute or model quality, though. First, look into the context.

A database exposes structure, tables, columns, foreign keys. However, it does not expose meaning, so it cannot tell the AI which revenue definition Finance has approved, which cohorts are analytically significant, or which rows a given user role is permitted to see.

Without that context, even a capable model is making inference calls on every query. And inference at scale is how hallucinations get shipped to stakeholders.

The core problem with inference

When given raw database access, an LLM must infer:

• Which tables are authoritative
• What business rules apply
• Which metric definitions are correct
• What a user is allowed to see

Every inference is a failure point. To replace inferences with governed facts, you need a semantic layer as well as explicit context that AI can use.

Common failure modes in AI analytics

When looking to implement AI analytics, most teams hit the same failure patterns within weeks. So, before considering the architecture itself, let’s look at the recurring issues with having AI sit on top of ungoverned data.

Metric ambiguity at query time

A user asks “What was our revenue last year?”

Revenue lives in a bookings table, a recognised revenue table, an ARR model, and a dashboard that blends all three. The model picks one of these as the source.

It may not pick the right one, and it will not tell you which it picked.

A VP of Finance and a VP of Sales getting different “correct” answers from the same AI is a trust-destroying event.

Business logic duplication

Customer lifetime value gets calculated differently in the warehouse, the BI layer, and the AI system prompt. When those diverge, the AI produces answers that are internally consistent but disagree with existing reports. Debugging means tracing logic across three systems.

Permission boundary failures

SQL generation without row-level security awareness is a real governance risk. “Show me all customer contracts” should return only the rows the querying user may see.
Without explicit permission context, generated SQL can bypass those boundaries entirely.

Inconsistent join logic

Multi-table queries need join logic that is not obvious from schema alone.

The AI can produce valid SQL that is semantically wrong, joining on a column that fans out and duplicates rows. The query runs cleanly, so the error is hard to spot.

How to make business metrics legible to AI

The difference between “revenue” and “recognised revenue” is obvious to a Finance analyst; it is not obvious to an LLM unless you tell it.

You need a semantic layer to translate physical structures, tables, columns, joins, into business objects: metrics, dimensions, entities. That has always been valuable for humans. For AI, it is necessary but not sufficient.

The piece that makes the difference is AI context: structured documentation an analytics engineer writes directly into the model, so the AI interprets each metric the way the business intends. This is not a separate doc site or a system prompt; it lives in the model definition, version-controlled alongside the SQL.

The AI context you build this way includes:

• The human-readable label
• A precise description
• Synonyms users actually type
• Explicit “do not confuse with” guidance
• The approval chain
• Example questions

Here, you can see the AI context in the model IDE. The highlighted block is the ai_context for recognised_revenue, label, description, synonyms, do_not_confuse_with, approval chain, and example questions.

This single block is read by Blobby (the Omni Agent), the MCP Server, and Agent Skills.

Where AI context comes from

When we say that analytics engineers write AI context as part of the model, we do not mean they have to do it all manually.

Omni’s Modelling Agent drafts labels, descriptions, and synonyms while you edit YAML in the Model IDE and incorporates existing documentation, so curating context does not feel like a chore.

The governance boundary stays intact: the agent drafts, then a person reviews and publishes.

Enterprise AI grounded in your model

Meet Blobby, the friendly face of the Omni Agent. Blobby is the natural-language surface where any user can ask a question and get an answer grounded in the governed model.

‘Grounded’ is key here. Blobby will not invent a definition of revenue; it reads the ai_context you wrote and queries the governed metric.

Here, we can see Blobby answering a revenue question on the Omni Agent page. The answer is grounded in the governed model, and the provenance row surfaces the metric ID (revenue.recognised_revenue), the Finance-approved badge, and the exact SQL that ran, giving everything a developer needs to verify the result.

When AI is enabled, the Workbook Agent powers in-workbook questions, and the standalone Omni Agent page makes Blobby available across the organisation and embeddable into external applications.

Behind the scenes, “Read result data” lets the model summarise results, detect anomalies, and highlight insights, all under the same data-privacy controls as the rest of Omni’s AI.

That provenance row is the whole point because you do not have to blindly trust the output when you have the metric ID, the approval chain, and the generated SQL.

A developer can read exactly what has run and confirm it matches the governed definition. AI moves from something you double-check to something you can act on.

Key architecture principle

Business logic lives in exactly one place: the semantic model. Not in SQL scattered across workbooks, not in system prompts, not in dashboard calculated fields.

This way Blobby, the MCP Server, Agent Skills, the CLI, and every AI surface are all consumers of that model, and never hosts of their own logic.

MCP Server: Governed Queries from Any AI Tool

The Model Context Protocol (MCP) lets external AI tools query Omni without each one re-implementing data access.

The Omni MCP Server exposes the semantic model, not the raw database, so Cursor, Claude Code, Claude Desktop, ChatGPT, VS Code, Codex, and Microsoft Copilot all query the same governed metrics.

The server works through three tools. pickModel returns the available models; pickTopic returns the topics within the chosen model (the client picks the most relevant one); getData runs the query against that model and topic and returns the result.

Provide a model ID in the config and you can skip the first step. Enable query-all-views and the AI can query any view directly, not just topics.

Let’s see it in action:

The MCP Server tool flow goes like this: A request from Cursor walks pickModel → pickTopic → getData. Omni returns the value plus full governance metadata, metric ID, ai_context, approver, permissions_applied, and the generated SQL.

Queries are scoped to the configured model and run with the authenticated user’s permissions.

Two properties make this safe by default:

• Access is scoped: interactions are limited to the model (and topic, if provided) passed to the MCP, preventing unauthorised data access.
• Permissions pass through: every MCP query runs with the authenticated user’s permissions, inherited straight from Omni’s semantic layer. Authentication is OAuth 2.1 (recommended) or an API key for centralised, automated workflows.

There is also the searchOmniDocs tool. Ask “How do I create a calculated field?” and the client searches Omni’s documentation, synthesises an answer, and cites the source pages, using the same AI search pipeline that powers the Omni Agent.

Agent Skills, the CLI, and AI Evals

Blobby and the MCP Server cover querying. The rest of a developer’s analytics workflow, building models, running queries, shipping dashboards, measuring quality, is covered by Agent Skills, the CLI, and AI Evals.

Agent Skills: Omni inside your IDE

Agent Skills are open-source skills that bring Omni’s capabilities into your coding assistant, Claude Code, Cursor, Codex, Copilot, Gemini CLI, Cortex Code.

Built on the Omni CLI, they activate automatically from natural language and let you explore models, run queries, edit YAML, and manage content without leaving the editor.

Route directly with @omni-analyst for data questions, @omni-modeler for model edits, and @omni-admin-agent for administration.

@omni-analyst runs a governed query and returns results in the terminal; @omni-modeler drafts a new customer_lifetime_value measure.

Unlike the MCP Server, which focuses on natural-language querying, Agent Skills provide the broader surface: model building, content management, administration, and optimisation, all from the command line and scriptable into CI/CD via the CLI.

AI Evals: making model quality measurable

Curating AI context raises an obvious question: how do you know a change helped? AI Evals answers it. Run prompt test sets against a model branch and score how accurately the AI maps each question to the right metric. Every YAML edit becomes measurable, and you see the score move before you publish.

Here is what it looks like when AI Evals scores a prompt set against a model branch.

This closes the loop on AI context and trust. A failing eval does not just report a number, but also points at the specific ai_context gap that caused the miss. Draft the fix on a branch, re-run the evals, watch the score climb, then publish. This is the same review-and-merge discipline analytics engineers already use for transformations.

The evolution of analytics teams

The analytics engineering role has expanded steadily since dbt moved transformation logic into version-controlled code. The next expansion is underway, namely from transformation engineers to context engineers.

Transformation engineering makes data correct, clean, neatly modelled, and documented. Context engineering makes data understandable to business users, to embedded apps, and increasingly to AI agents that will query the model thousands of times a day.

The engineer defining an Omni metric today is practically shipping context infrastructure for every AI surface in the stack.

The core discipline stays the same:

• Define clearly;
• Version everything;
• Review before shipping;
• Document for the next person.

What changes is who the next person is. It now includes AI agents that read your descriptions literally and answer questions for people who never see the SQL. That is a much higher bar for naming, description, and disambiguation because the semantic model is a public API for an AI system and it should be designed like one.

Best practices

• Write metrics as if an AI will read them literally. Blobby, the MCP Server, and Agent Skills all do.
• Add synonyms users actually type.
• Add explicit do_not_confuse_with guidance.
• Add example questions.
• Prove it all with AI Evals.
• Treat ai_context as tested, version-controlled documentation, not an afterthought.

Where to start with the Omni semantic layer architecture

Teams making real progress with AI analytics invest in the model and its context before the AI layer.

Here is the sequencing we recommend from real-world project experience:

• Audit where business definitions live today, SQL files, BI tools, spreadsheets, system prompts. Map the fragmentation before consolidating.
• Start with your highest-value, highest-ambiguity metrics: revenue, churn, engagement. Where definitions vary most across teams, governance pays off most.
• Write ai_context as you go. Add label, description, synonyms, do_not_confuse_with, example questions. Then let the Modelling Agent draft the first pass.
• Wire up the surfaces your developers use: Blobby for natural-language analytics, the MCP Server for IDE and chat tools, Agent Skills for in-editor model work.
• Use AI Evals to make sure the quality is measurable. Treat the model as infrastructure, branches, review, version control, CI/CD.

The foundation determines the ceiling

Sophisticated models and generous budgets will only take you so far. What actually determines the quality of every AI-generated answer your organisation produces is the foundation beneath it: governed metrics, curated AI context, and every AI surface reading from the same model.

For developers and analytics engineers, this is the mandate. The semantic model is no longer just analytics infrastructure; it is the foundation for the entire AI stack. Its quality sets the ceiling.

Omni was built on this conviction. The governed definitions an analytics engineer maintains are the same definitions Blobby answers from, the MCP Server queries, and Agent Skills build on. Not a copy, not a sync, the same model. That is what makes the difference between AI you have to verify and AI your organisation can actually rely on.

This is the second article in the mini-series on AI analytics and Semantic Layers. If you have not read Part 1 yet, start there for the full picture on why you need a semantic layer.