How to build a semantic layer for AI agents

A semantic layer for AI agents is a governed, machine-readable contract between business language and data. It defines which entities exist, how they relate, how metrics are calculated, which dimensions can be used, what access rules apply, and which evidence should accompany an answer.

Without that contract, an agent may have database access but still need to guess whether “customer” means an account, a billing entity, or an active workspace. It may choose a plausible join that duplicates revenue or compare a monthly snapshot with an event table as if they had the same grain.

Start with one recurring decision. Expose the smallest semantic surface needed for that job, then test whether different phrasings produce the same defensible result. The rest of the company can wait.

Turn business terms into executable logic

A glossary explains terms to people. A semantic layer connects those terms to executable data logic.

If a glossary says qualified pipeline means “open opportunities likely to close,” an agent still needs to know:

• which opportunity stages qualify;
• whether to use the current amount or a historical snapshot;
• which date determines the forecast period;
• how opportunity, account, owner, and activity records join;
• which regions the requesting manager may see;
• what to do when the CRM stage and forecast category disagree.

The layer should answer those questions in a form the agent can query through an approved view, API, metric service, or tool. It should also remain understandable to the data and business owners who approve changes.

This is the implementation step behind the broader observation that business data needs context. Context becomes operational when definitions, relationships, and boundaries travel with the query instead of living in an analyst’s memory.

Start with a semantic contract for one job

Do not begin by cataloging every table. Write the agent’s job first.

For example:

Every Monday, identify late-stage opportunities expected to close this quarter, compare qualified pipeline with the prior weekly snapshot, and show the accounts and recent customer activity that explain material movement for the regional revenue manager.

That sentence reveals the first semantic model. It needs opportunities, accounts, owners, activities, a weekly snapshot, a qualified-pipeline metric, a fiscal quarter, and a regional access boundary. It does not need every CRM object or every company KPI.

Create a short contract for each item the job uses:

If two teams use different definitions, do not hide the disagreement behind one friendly label. Give each approved definition a distinct name and owner, or make the agent ask which one the user intends.

Model six things the agent must not guess

Semantic-layer products use different terminology, but a useful implementation needs six kinds of information.

1. Entities and grain

Entities are the business nouns in the workflow: account, opportunity, subscription, ticket, order, product, or employee. For each one, identify its stable key and grain.

Grain deserves explicit attention. “Customer activity” could mean one event, one user-day, or one account-week. An agent that joins an account-level metric to raw events can multiply values while returning valid SQL.

dbt’s guidance describes semantic models through entities, measures, and dimensions, with entities connecting data models and dimensions providing ways to group results. It also recommends starting with a small number of metrics rather than attempting a broad rollout. See dbt Labs’ guide to building a semantic layer.

2. Relationships and allowed join paths

Document cardinality and direction for every permitted relationship. State whether a join is one-to-one, many-to-one, or many-to-many, and decide how the last case should be handled.

Do not give the agent a catalog and hope it finds the intended route. Expose approved paths such as:

opportunity.account_id -> account.id       many-to-one
opportunity.owner_id   -> employee.id      many-to-one
activity.opportunity_id -> opportunity.id  many-to-one

If two valid paths connect the same entities, name when each applies. Snowflake’s semantic-view specification, for example, makes relationships explicit and allows a metric definition to identify which relationship to use when multiple paths exist. It also supports metadata such as synonyms and verified natural-language queries. The details are platform-specific, but the design lesson is portable: ambiguity should be resolved in the model, not during every prompt. See the Snowflake semantic-view reference.

3. Measures, metrics, and time rules

A measure is an aggregatable value such as opportunity amount or resolved-ticket count. A metric adds business logic: qualified pipeline, net revenue retention, or median resolution time.

For every metric, record:

• the base measure and aggregation;
• required filters and exclusions;
• the valid time dimension;
• whether it can be summed across time;
• the dimensions by which it may be grouped;
• currency, timezone, and fiscal-calendar behavior;
• treatment of late-arriving or corrected records.

Snapshot measures require special care. Headcount at the end of January plus headcount at the end of February is not meaningful total headcount. Make non-additive behavior part of the contract rather than relying on an agent to infer it.

MetricFlow provides a concrete example of this model-as-code approach: it compiles reusable metric definitions into SQL and handles joins, metric types, and time granularities. Its open-source repository documents the query-compilation model.

4. Business vocabulary and boundaries

Map common language to approved objects, but include negative guidance as well as synonyms.

For example:

term: active_customer
definition: account with at least one completed core workflow in the last 28 days
synonyms: [engaged account]
not_equivalent_to: [paid account, user login]
owner: customer_success_operations

Negative guidance prevents a common failure: using the nearest familiar field when the requested concept has a narrower meaning. Include caveats that materially change interpretation, but keep long policies and narrative documents outside the metric definition. The semantic layer should point to that surrounding context when the job needs it.

5. Access and exposure rules

The semantic model should expose only the objects and fields needed for the job. The underlying data platform or application must still enforce access.

Pass the requester’s identity and scope into the query path. Apply row, column, tenant, and purpose restrictions before results reach the model. Do not treat a prompt instruction such as “show only my region” as an authorization control.

The full access design is covered in the guide to AI-agent permissions for enterprise data. The important semantic-layer rule is simple: the meaning of a metric and the authority to view its contributing records are separate controls, and both must hold.

6. Provenance, freshness, and failure behavior

An answer should retain enough information to identify the semantic definition, source state, and records used. At minimum, capture:

• metric and model version;
• source or query reference;
• extraction or snapshot time;
• applied filters and access scope;
• contributing record identifiers where appropriate;
• missing, stale, or conflicting sources.

Freshness is part of meaning. “Current pipeline” based on a sync that failed overnight is not current. Define what the agent should do when freshness falls outside the contract: refuse, return partial results with a visible limitation, or route the issue to an owner.

Expose a narrow query surface to the agent

Once the model exists, decide how the agent will use it. The connection might be a semantic query service, a governed SQL view, or a typed business API. The four main options and their tradeoffs are covered in how to connect AI agents to enterprise data.

Whatever interface you choose, make discovery constrained and descriptive. The agent should be able to find certified entities and metrics, inspect their definitions and valid dimensions, submit bounded filters, and receive both a result and evidence metadata.

Avoid exposing hundreds of similarly named fields. A smaller domain view such as revenue_review is easier to test than an enterprise catalog containing every table. The layer can grow as real questions reveal missing concepts.

Looker’s current modeling guidance reflects the same general architecture: a semantic layer centralizes metrics, calculations, and relationships so downstream BI and AI workflows can use shared business meaning. See Google Cloud’s Looker modeling overview.

Test meaning as well as SQL execution

A query that runs successfully can still answer the wrong question. Build tests at three levels.

Definition tests

Reconcile each metric against an approved report or independently calculated fixture. Test exclusions, timezone boundaries, empty periods, late data, and non-additive measures.

Language tests

Ask the same question in different ways. “Qualified pipeline this quarter,” “open pipeline expected before quarter end,” and “how much late-stage pipeline remains?” should either resolve to the same approved concept or trigger a useful clarification.

Also test overloaded terms. If “bookings” has separate sales and finance meanings, the agent should not choose silently.

Workflow tests

Run the entire job with representative permissions and source conditions. Check whether the answer uses the right metric, period, dimensions, records, and access scope. Remove a source, make it stale, and ask for a forbidden region. A passing system should fail visibly and safely.

The article on evaluating AI agents with business data provides a broader release scorecard for correctness, grounding, permission behavior, and recovery.

Operate the semantic layer as a product

Business meaning changes. Sales stages are renamed, fiscal calendars shift, products merge, and source systems gain new owners. A semantic layer needs a release process.

Keep definitions versioned. Require review from both the data owner and the business owner for material changes. Show affected metrics and agent jobs before deployment. Run regression questions, publish the effective date, and preserve enough history to explain why an answer changed.

Measure the layer by the work it supports:

• How often does the agent ask for a definition that does not exist?
• Which queries require a disallowed or ambiguous join?
• How many answers use stale or incomplete sources?
• Which terms cause repeated clarification?
• Do reconciliations remain within the agreed tolerance?
• Can an operator trace a disputed answer to its model and source state?

These signals turn production failures into modeling work. They are more useful than counting how many definitions the catalog contains.

A sensible first release

Choose one recurring review with an accountable owner. Define three to five metrics, the entities and joins they require, and the questions people already ask after seeing those metrics. Expose only that domain. Test normal, ambiguous, stale, and unauthorized cases. Run it beside the current workflow until the owner can explain where the agent helps and where it still needs context.