How does Fabric Data Agent works

Hi Jeanxyz, you need to "teach" your agent how to correctly query your data. You need to provide instructions, that combine sample questions with the sample queries. You need to explain, precisely, in the instructions how to find "most profitable products". You can write it in plain language, or provide a sample query.
When you test your query, you can see how the model decided to construct a query. You can compare that query with your correct one and see the difference. And, again, as many concrete instructions as you can add to the instructions, as better your Data Agent will be answering.

Hope this helps. If you din this answer useful, please consider giving kudos and accept as a solution.

Hi Jean,

Great question , and you’re absolutely right to look deeper here, because what you’re seeing isn’t just coming from your explicit instructions.

What’s happening is that the Fabric Data Agent doesn’t rely only on your prompt or example queries. It also uses an internal interpretation layer that combines:

• Your natural language question
• The semantic model / Lakehouse schema
• Column metadata (names, relationships, measures)
• Built-in reasoning heuristics for generating “useful” queries

That’s why your question:
“most profitable products in 2024”

is being expanded into something like:

• ProductName
• Category
• Brand
• Additional metrics

Even though you didn’t explicitly define those , the agent is auto-expanding the query based on available dimensions in the model, trying to provide a richer breakdown.

So to answer your key question:

The generated text is coming from the LLM + semantic model inference layer, not directly from your agent instructions.

Hi Jeanxyz 

it's something that's really confusing the first time you run into it. Let me explain:

That rephrased text you see in the response details doesn't come directly from your instructions or your examples. It's the Fabric data agent itself that rephrases your question as an intermediate step before generating the SQL/DAX/KQL query. This is officially documented here: https://learn.microsoft.com/en-us/fabric/data-science/concept-data-agent ("Once the correct data source or sources are identified, the Fabric data agent rephrases the question for clarity and structure, and then invokes the corresponding tool to generate a structured query").

In other words, the agent takes your original question, combines it with the data source schema, the instructions and the examples you've configured, and generates a "structured" version of the question that it then uses to build the query. That rephrasing is done by the underlying LLM (Azure OpenAI Assistant API), it's not a field you can edit directly.

Why is it adding category and brand if you didn't ask for it? The most likely cause is one of these (or a combination):

1. The schema is "suggesting" those columns. If your product table has columns like Category and Brand close to ProductName, the LLM tends to interpret them as natural dimensions to group products by. It's typical behavior of a model "helping you" without being asked.
2. An example query you left may be grouping by those columns. Even if you don't think so, it's worth carefully reviewing whether any generic example (something like "top products by revenue") has a GROUP BY that includes category/brand. The agent retrieves the top ~4 most relevant examples and uses them as guidance, so one poorly tuned example contaminates many responses.
3. The instructions are not restrictive enough. If the agent's instructions don't explicitly state how "most profitable product" is defined in your business, the LLM fills in the blanks.

How to fix it:

1. Check the "run steps" view or the agent's steps to see exactly which examples were retrieved for that question. It's the best way to diagnose where the rephrasing comes from.
2. Add a specific example query with the question "What are the most profitable products in 2024?" and the exact query you expect (GROUP BY only by product name, without category or brand). This gives the agent a very clear pattern for that intent.
3. Use Data Source Instructions (per-data-source instructions), which let you define specific rules for each source, such as "when asked about product profitability, group only by ProductName, do not include Category or Brand unless explicitly requested".
4. If you have several similar examples, check that they aren't in conflict. The Fabric Data Agent SDK detects examples that point to the same intent with different logic, and it's a common cause of inconsistent behavior.

Practical summary: the rephrased text is not directly editable, but it can be controlled through more restrictive instructions and well-tuned examples. The rephrasing is a normal part of how the agent works, not a bug.

Hope these tips help you solve or at least clarify the issue.

If this helped, please consider giving it a Like. If it solved your issue, please mark it as the Accepted Solution to help others facing the same problem.

Thanks