Building a Better Microsoft Fabric Data Agent: Instructions, Visual Policy, and Cost-Aware Design

Co-Authors — Natarajan Manivasagan & praful potphode

AFabric Data Agent can generate technically valid DAX and still return the wrong business answer. The missing piece is often not the model; it is the context we give the agent around it.

Question is now — How do I make sure the agent interprets the same business question consistently, uses the right measure, chooses the right date, routes to the right source, and presents the answer in the right way?

That is where things get interesting. Take a simple question:
— Which region performed best last quarter?

It sounds straightforward. But before answering it, the agent has to make several decisions.
What does performed best mean?

• Highest Sales?

• Highest Profit?

• Best Profit Margin?

Which date should define “last quarter”?

• Order Date?

• Ship Date?

Should the agent return only the highest-performing region? Or should it compare all regions? Would a chart help? If yes, which chart?

And if the semantic model already contains an approved Profit Margin measure, should the AI use that measure or calculate margin again from the underlying columns?

These are not really DAX questions.
They are context and governance questions.

After working with Fabric Data Agents beyond the proof-of-concept stage, I stopped treating instructions as one large prompt.

There are multiple layers involved:
1. Data Enrichment
2. Semantic Model AI Instructions
3. Data Agent Instructions
4. Routing and ambiguity handling
5. Response and visual policy

Each layer has a different job. We already covered Data Enrichment in one of the blogs, where Praful Potphode showed us how to do data enrichment in detail.

Press enter or click to view image in full size

Figure.1 Data Agent Architecture with areas of responsibilities

Before we proceed to dive deep into instructions and policies, we should know how, through these implementations, we could actually save costs. Fabric Data Agent consumes capacity based on AI tokens; getting these layers right isn’t only about improving answer quality. It can also reduce unnecessary reasoning, retries, query execution, and overly verbose responses.

Press enter or click to view image in full size

Figure.2 Things to know

1. There Is a Cost to Ambiguity

Fabric Data Agent usage is token-based. The user question is only part of the context processed by the AI. Agent instructions, source instructions, example queries, conversation history, and supporting context can also contribute to the input.

This creates an important architectural consideration.

Poorly prepared Data Agent
Imagine a user asks:

Which region performed best?

The agent assumes “performance” means Sales. It runs the query. Returns the answer.

The user responds:

I meant profitability.

Now we have another interaction, another round of reasoning, another response, and potentially another underlying query.

A better approach would be to define the business interpretation once:

When performance is used without a specific KPI, evaluate Sales and Profit.

Now the agent has better context on the first attempt. So the objective shouldn’t be: Use the fewest tokens possible.
It should be:

Use the minimum useful context required to produce the right answer with the least unnecessary reasoning.

A smaller prompt that produces the wrong answer is not an optimization. Likewise, adding thousands of characters of unnecessary instructions to every interaction isn’t an optimization either. The better objective is:

Optimize the amount of context, reasoning, querying, and output required to produce a trusted answer.

Or more simply:

Optimize for cost per successful answer — not tokens per prompt.

Press enter or click to view image in full size

Figure.3 An illustrative on cost and its consumption

2. Data Enrichment Comes First — Start With the Model

praful potphode covered semantic-model enrichment in my previous article, so I won’t repeat the entire process here.

Link — Why Your Fabric Data Agent Gives Wrong Answers (And How Data Enrichment Fixes It)

Microsoft’s current guidance recommends exactly this direction. A focused AI Data Schema reduces ambiguity, improves query accuracy, and can reduce response latency by keeping the AI focused on the objects that actually matter.

Key Note — Instructions should add business context. They should not be used to repair a poorly designed semantic model.

3. The Most Important Separation: Semantic Model Instructions vs Data Agent Instructions

This is probably the most important architectural point in the article.

Semantic Model AI Instructions and Data Agent Instructions are not the same thing. And they shouldn’t contain the same information.

Microsoft explicitly states that Data Agent-level instructions aren’t passed to the DAX-generation tool for semantic-model query generation.

That changes how we should architect our instructions.
Consider this rule:

When a user asks for margin, always use Profit Margin.

If we put that only inside the global Data Agent instruction, we’ve placed model-specific guidance at a layer where the DAX-generation tool doesn’t directly use it.

That rule belongs in Semantic Model AI Instructions.
The easiest way to remember it is:

Semantic Model AI Instructions explain how AI should understand the model.
Data Agent Instructions explain how the agent should orchestrate and communicate.

Once this separation is clear, the framework becomes much easier to maintain.

Press enter or click to view image in full size

Figure.4 Resuable Framwork Points

4. Semantic Model Instruction — Give the Semantic Model a Clear Purpose

Use these for rules that affect how the semantic model should be interpreted and queried.
It is intentionally generic. The business rules will change between Finance, Sales, HR, Supply Chain, Operations, or any other domain.

The structure does not need to.

Instead of one long block of rules, I use a repeatable structure.

SEMANTIC MODEL AI INSTRUCTIONS
1. Purpose & Scope
2. Measure Priority
3. Authoritative Objects
4. Business Definitions
5. Governed Measure Mapping
6. Business Rules
7. Time Rules
8. Source Priority
9. Default Behaviour
10. Ambiguity Rules
11. Domain Restrictions
12. Cross-Domain Rules

The reusable framework in our implementation guide follows the same pattern: purpose, authoritative tables, business definitions, governed measures, business rules, time logic, defaults, ambiguity rules, and restrictions.

Generic Semantic Model Instruction Framework

The principle is straightforward:

If a rule changes the query, it probably belongs close to the semantic model.

5.Then Keep the Data Agent Focused on Orchestration

Once semantic logic lives where it belongs, the Data Agent instruction becomes much cleaner.

A generic framework can look like:

Data Agent Instruction Framework

DATA AGENT INSTRUCTIONS 

1. Purpose 
2. Scope 
3. Data Source Behaviour 
4. Response Policy 
5. Visual Policy 
6. Insight Generation 
7. Recommendation Policy 
8. Comparison Rules 
9. Large Result Handling 
10. Conversation Style 
11. Explainability 
12. Formatting 
13. Missing Data 
14. Follow-up Questions 
15. Guardrails

This is based directly on the reusable Data Agent framework in our implementation guide.
The production instruction pattern also reinforces one important rule:

Retrieve governed results from the semantic model and never override the model’s business rules, measure selection, relationships, or calculations.

6. Make the Response Policy Adaptive

A fixed seven-section response is useful for deep analysis.

It is unnecessary for:

What were Total Sales in 2025?

So I prefer an adaptive policy.

## Simple KPI Question 

- Answer directly. 
- State important period and filter context. 
- Keep the response concise. 
- Do not force a chart. 

## Analytical Question Provide: 
1. Scope 
2. Short summary 
3. Supporting result 
4. One useful visual 
5. Key takeaways 

## Deeper Analysis 
Add recommendations and follow-up questions only when they add value.

Our existing Data Agent framework already uses a structured flow of Scope, Executive Summary, Supporting Details, Visual, Key Takeaways, Recommendations, and Follow-up Questions.

7. Visual Policy Should Be Governed Too

One of the more interesting recent improvements in Fabric Data Agent is native visual responses. The agent can generate interactive Fabric visuals, and Agent Instructions can influence when visuals should be used and which chart types should be preferred.
That gives us another layer of governance:

At the time of writing, Fabric Data Agent supports:
Line chart
Multi-line chart
Column chart
Multi-column chart
Stacked column chart
Pie chart
Scatter plot
Area chart
Stacked area chart
Our current instruction framework already follows this analytical-intent pattern and limits the response to one visual by default.

The safeguards matter just as much:

- Do not create a visual when it adds no value.
- Always create one when explicitly requested and supported.
- Do not generate several charts when one is enough.
- Keep KPI, filters, and time context consistent.
- Never change the business calculation just to make a visual.

A chart should explain the result. The result should never be changed to fit the chart.

Press enter or click to view image in full size

Figure.5 Illustration on Visual Policy

8. Guardrails Matter More Than More Instructions

A good framework should also make the non-negotiable behaviour clear.

Always:
- respect semantic-model rules,
- respect user filters,
- respect security,
- use governed results.

Never:
- recreate governed KPIs,
- fabricate values,
- infer causes without evidence,
- override semantic-model logic,
- expose technical objects unnecessarily,
- change user scope without permission.

These same guardrails are part of the production instruction set we use.

Press enter or click to view image in full size

Figure.6 Gaurdrails

9. What Changes When the Source Is SQL? (Bonus Section)

Now let’s move beyond the semantic model. Imagine that the same Data Agent also has access to a Fabric Warehouse.

A semantic model already provides: relationships, governed measures, business-friendly metadata, DAX calculations, and a semantic layer.

A raw SQL source is different. The Data Agent may need more direct guidance about:
what each table represents, how tables join, which columns own particular business concepts, which dates should be used, common stored values, the grain of the fact table, and query patterns that aren’t obvious from column names alone.
For SQL sources, Fabric gives us another configuration layer:

Data Source Instructions: Explain How the Source Should Be Queried

Think of Data Source Instructions as a short onboarding guide for someone seeing the database for the first time.
They should answer questions such as:

Which table owns Sales?
Is one row one Order or one Order Line?
Which key should be used to join Customer?
Should analysis use Order Date or Ship Date?
Does Region contain West or WEST?

A concise pattern can look like this:

## Source Purpose
Use this source for Sales, Customer, Product,
and Inventory analysis.
## Table Grain
FactSales contains one row per Order Line.
FactInventory contains Product inventory by location.
## Join Rules
FactSales.CustomerKey → DimCustomer.CustomerKey
FactSales.ProductKey → DimProduct.ProductKey
FactSales.DateKey → DimDate.DateKey
## Business Rules
Revenue = SUM(SalesAmount)
Order Count = COUNT(DISTINCT OrderID)
Do not use COUNT(*) for Order Count because
one Order can contain multiple Order Lines.
## Date Rules
Use OrderDate for normal Sales analysis.
Use ShipDate only for shipping or fulfillment questions.
## Query Rules
Use explicit joins.
Avoid SELECT *.
Return only required fields.
Do not expose technical keys unless requested.

The goal is not to document the entire database. Include only the context that materially affects query generation.

Example Queries: Show the Pattern

For example:

Question

Who are the top 10 customers by revenue?

SELECT TOP 10
    c.CustomerName,
    SUM(s.SalesAmount) AS Revenue
FROM FactSales s
INNER JOIN DimCustomer c
    ON s.CustomerKey = c.CustomerKey
GROUP BY
    c.CustomerName
ORDER BY
    Revenue DESC;

This one example teaches the agent:

• which fact table contains Sales,

• how Customer should be joined,

• how Revenue is aggregated,

• how customer-level grouping works,

• and how Top N ranking should behave.

That leads to a useful rule:

Instructions explain the rule. Example Queries demonstrate the pattern.

A few carefully chosen examples are usually more valuable than dozens of near-identical queries.

Press enter or click to view image in full size

FIgure.7 Illustration on SQL Fabric Instruction

9. Limitations to Keep in Mind

Data Source Instructions improve context, but they do not turn a SQL source into a governed semantic model.

1. Instructions do not fix poor data modeling

2. Do not put every business KPI into SQL instructions

3. Stored values may need to be documented

4. Example Queries are patterns, not hard-coded answers

5. Too many examples can create noise

6. SQL Source Instructions are different from Semantic Model AI Instructions

Press enter or click to view image in full size

Figure. 8 Limitations

10. Final Thought

Building a reliable Fabric Data Agent is not about writing the longest possible prompt. It is about putting the right context at the right layer.

Use metadata to explain the data. Use Semantic Model AI Instructions to govern how the model is interpreted. Use Data Source Instructions and examples to guide SQL generation. And use Data Agent Instructions to govern orchestration, response behaviour, visuals, and guardrails.

The goal is not more instructions. It is less ambiguity.

That is what moves a Fabric Data Agent from a successful demo toward governed conversational analytics.

References:

Microsoft Learn — Data Agent consumption
Microsoft Learn — Semantic model best practices for Data Agent
Microsoft Learn — Configure your Data Agent
Microsoft Learn — Visual responses from a Fabric Data Agent
Microsoft Learn — Improve Data Source routing