How does Fabric Data Agent works

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