A Fabric Data Agent rule can be precise, visible in the editor, and irrelevant to the tool that answers the question. A semantic-model definition placed at agent level can influence routing but never reach NL2DAX. A source-specific join rule placed in general agent instructions can compete with routing guidance. A user prompt can request behavior that organizational policy or role permissions correctly refuse.
Fabric Data Agent is not one prompt. It is an orchestrator, source-specific query tools, configuration artifacts, grounding sources, policy layers, user identity, and a draft-to-published lifecycle. Rewording an ignored instruction without tracing that path creates motion without control.
Can you name the component that consumed each instruction in a failed run? If not, do not add more rules yet.
Trace the runtime path before rewriting instructions
For each failed question, capture the user and role, published agent version, conversation context, candidate sources, selected source, query tool, instructions available to that tool, retrieved examples or verified answer, generated SQL, DAX, KQL, or GQL, source result, policy behavior, and final response. Compare the same question in a clean conversation and under each representative permission set.
Classify the failure before editing: source routing, query generation, business semantics, source permissions, policy enforcement, example retrieval, response synthesis, formatting, context drift, or stale publication. One answer can contain more than one failure, and a formatting instruction can make a wrong result look consistent.
Assign every rule to the component that can use it
| Layer | Used by | Put here | Common failure |
|---|---|---|---|
| Organizational and role intent | Tenant policy, workspace governance, source permissions, Purview, RLS, CLS, and read-only enforcement. | Security, compliance, access, and allowed-operation boundaries. | Developer instructions or user prompts are expected to override a higher-precedence control. |
| Data Agent instructions | The agent orchestrator before and around source-tool selection. | Cross-source routing, shared terminology, general response behavior, abbreviations, and tone. | SQL join logic or semantic-model business logic is placed here and never reaches the query tool that needs it. |
| Data source description | The orchestrator when deciding whether a supported source is relevant. | Source purpose, domain, authority, coverage, and questions the source can answer. | Descriptions overlap, advertise unsupported coverage, or are unavailable for the selected source type. |
| Data source instructions | Supported source-specific query-generation tools such as NL2SQL, NL2KQL, and NL2GQL. | Schema meaning, joins, dates, filters, categorical values, grain, exclusions, and query rules. | A team expects a Power BI semantic model to consume source instructions that it doesn't support. |
| Power BI Prep for AI | The semantic model's DAX generation and verified-answer path. | AI Data Schema, model terminology, business logic, AI Instructions, and Verified Answers. | Semantic-model rules are duplicated at agent level, where Microsoft says the DAX tool ignores them. |
| Examples and verified answers | Few-shot retrieval for supported sources or trigger matching in Prep for AI. | Known complex query patterns and controlled answers for high-value questions. | Examples are stale, too broad, contradictory, or assumed to be supported for every source type. |
| User prompt | The current conversation within every higher-precedence boundary. | The explicit question, filters, period, comparison, and clarification. | A prompt is treated as authority over policy, unavailable schema, developer scope, or prior truncated context. |
Configuration capabilities differ by source type. Confirm the current support matrix before standardizing one template across SQL, Eventhouse, semantic model, Graph, ontology, and unstructured sources.
Diagnose conflicts from evidence, not prompt intuition
| Symptom | Inspect | Likely cause | Corrective action |
|---|---|---|---|
| The agent chooses the wrong source. | Run-step route, source descriptions, agent instructions, question scope, and competing source authority. | Routing guidance is absent, overlapping, or mixed with source-query logic. | Define mutually distinguishable source contracts and test positive, negative, and ambiguous routes. |
| The query runs but answers the wrong business question. | Generated query, selected schema, source instructions, retrieved examples, values, joins, grain, and date rules. | Business logic is missing from the query tool's configuration or conflicts with an example. | Move source-specific logic to the supported source layer and reconcile against a deterministic control query. |
| A Power BI rule is ignored. | Prep for AI schema, AI Instructions, Verified Answers, generated DAX, and agent-level duplication. | Semantic-model guidance was placed only in Data Agent instructions. | Configure the rule in Prep for AI, remove conflicting duplication, save affected artifacts, and retest DAX. |
| The answer is refused, empty, or incomplete. | User identity, source permissions, RLS, CLS, Purview DLP, access restrictions, policy logs, and row limits. | A higher-precedence control or response limit is working as designed. | Fix entitlement or policy configuration through its owner; never attempt to prompt around the control. |
| Testing works but shared users see old behavior. | Draft and published definitions, workspace, source binding, Git diff, publish event, consumer permissions, and cache or session. | The tested change wasn't published, promoted, rebound, or opened in a clean session. | Version the artifact, publish through an approved gate, verify bindings, and run consumer-role smoke tests. |
| The agent follows a rule only sometimes. | Instruction length, ambiguity, duplicates, contradictions, conversation state, model/runtime version, and question variants. | Probabilistic guidance is complex or competing; an instruction is being mistaken for deterministic enforcement. | Reduce and structure the rule, remove conflict, add clarification, or move deterministic logic into the data model or application. |
| An irrelevant example dominates the answer. | Retrieved few-shots, similarity, question overlap, source schema, query execution, trigger questions, and filters. | Examples collide, contain stale objects, or match wording without matching business intent. | Curate, split, or remove examples and regression-test retrieval and generated queries separately. |
| The answer format is consistent but the value is wrong. | Source result, generated query, response synthesis, formatting instructions, truncation, and conversation history. | Presentation rules are masking an upstream query or grounding failure. | Gate formatting on reconciled source results and score query correctness before response style. |
Score source routing, generated-query correctness, business-result correctness, policy behavior, grounding, response completeness, and presentation separately. A rule should pass representative roles, clean and multi-turn conversations, paraphrases, negative cases, and the published runtime. “The answer looks better” is not a release criterion.
Version configuration as production behavior
Store agent instructions, source instructions, descriptions, schema selection, examples, runtime settings, and source bindings in controlled definitions where supported. Review draft changes through pull requests, test in isolated workspaces, publish from an approved draft, and compare the published definition instead of assuming the editor state is live.
Build agent with AI can propose agent instructions, source instructions, descriptions, and examples for supported sources, but Microsoft currently lists schema selection, semantic models and Prep for AI, ontology, Graph, and unstructured data among unsupported creator-assistant configuration areas. Treat generated suggestions as candidates, inspect query-history provenance, execute proposed queries, and accept only measured improvements.
Maintain a rule registry with owner, purpose, layer, supported source types, question families, policy dependencies, examples, expected query behavior, release version, regression cases, and retirement condition. Monitor route distribution, query failures, wrong-answer reports, policy events, latency, capacity, model/runtime changes, and configuration drift.
Run a two-to-four-week instruction conflict assessment
- Select one Data Agent, attached sources, target applications, representative roles, critical question families, current failures, and prohibited decisions.
- Inventory tenant and role controls, agent instructions, source descriptions, source instructions, Prep for AI, examples, schema scope, runtime, draft, published version, and source bindings.
- Trace each critical question through routing, configuration available to the selected query tool, generated query, source result, policy behavior, and final response.
- Create ground truth for source route, query logic, result, allowed behavior, response completeness, and clarification or abstention.
- Run paraphrase, ambiguity, negative-route, role, clean-session, follow-up, example-collision, policy, draft/published, runtime, and application-integration tests.
- Remove, relocate, or simplify conflicting rules; correct Prep for AI and source configuration; validate generated queries; and define deterministic controls outside prompts.
- Deliver the layer map, rule registry, failure analysis, revised configuration, scorecard, regression suite, versioned changes, release gates, monitoring, rollback, and go, limited pilot, or stop recommendation.
Frequently asked questions
Why are my Microsoft Fabric Data Agent instructions not working?
The instruction may be in a layer the active query tool doesn't use, conflict with a higher-precedence policy, compete with another instruction or example, refer to unavailable schema, or remain only in a draft that wasn't republished. Trace the selected source and query tool before changing wording.
What is the difference between Data Agent instructions and data source instructions?
Data Agent instructions guide orchestration across the whole agent, including source routing, shared terminology, response preferences, and cross-source behavior. Data source instructions provide source-specific schema, join, filter, value, date, and query guidance to supported query-generation tools.
Where should Power BI semantic model instructions be configured?
Configure semantic-model business logic in Power BI Prep for AI. Microsoft states that the DAX generation tool uses Prep for AI instructions and ignores semantic-model-specific guidance placed in Data Agent instructions. Keep only cross-source routing and general response guidance at agent level.
Can Fabric Data Agent instructions override security or Purview policy?
No. Microsoft's intent hierarchy places organizational policy and role-based permissions above developer configuration and user prompts. Instructions cannot bypass source permissions, RLS, CLS, DLP, access restrictions, read-only behavior, or other higher-precedence controls.
How long does a Fabric Data Agent instruction conflict assessment take?
A focused assessment commonly takes two to four weeks for one agent, its configured sources, representative roles, and critical question families. It maps configuration layers, reproduces failures, reconciles generated queries, removes conflicts, versions changes, and establishes regression and release gates.
Official implementation references
- Fabric Data Agent intent hierarchy and agent-level configuration
- Configuration capabilities by Fabric Data Agent source type
- Fabric Data Agent instruction and source-description guidance
- Power BI Prep for AI and Data Agent instruction boundary
- Fabric Data Agent draft, published, Git, and configuration definitions
- Build agent with AI supported and unsupported configuration areas
Start with the question where the team keeps adding instructions but cannot explain why the published answer remains wrong. Datrick can trace the effective configuration, reconcile the query, remove conflicts, and establish a measured release gate.