agentleFS
PatrickGallucciPatrickGallucci/fabric-skills/skills/fabric-data-agent-remediate/SKILL.md

fabric-data-agent-remediate

Skill17 starsChanged 9 months agoMITView on GitHub

Diagnose and resolve Microsoft Fabric Data Agent issues including tenant settings, data source configuration, query generation failures, cross-region capacity errors, XMLA endpoint setup, Power BI semantic model integration, lakehouse/warehouse/KQL connectivity, example query validation, publishing/sharing problems, and Azure AI Foundry integration. Use when asked to troubleshoot data agent, fix Fabric AI agent, debug NL2SQL/NL2DAX/NL2KQL, resolve Copilot tenant settings, or diagnose Fabric data agent errors.

The file

We split this skill into the rules it gives an agent

3 rules. About 0 are common, 3 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈3

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Follow this decision tree to rapidly identify your issue category:

    line 33
  2. Distinctive:

    Run the Fabric Data Agent Diagnostic PowerShell script to validate tenant settings and connectivity prerequisites programmatically.

    line 75
  3. Distinctive:

    Use the Configuration Checklist template to document and track your data agent configuration for team handoff or support tickets.

    line 83

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Fabric Data Agent remediate

Structured remediate guide for diagnosing and resolving issues with Microsoft Fabric Data Agent (preview). Covers the full lifecycle from tenant configuration through data source setup, query tuning, publishing, and external integration.

When to Use This Skill

  • Fabric data agent cannot be created or is missing from the workspace
  • Data agent returns errors, empty results, or inaccurate queries
  • Tenant settings are misconfigured for Copilot and Azure OpenAI
  • Power BI semantic model data source fails to connect (XMLA)
  • Cross-region capacity errors prevent query execution
  • Example queries fail validation or are ignored by the agent
  • Published data agent is inaccessible to shared users
  • Azure AI Foundry or Copilot Studio integration issues
  • Agent generates incorrect SQL, DAX, or KQL queries
  • Conversation history is lost or not persisting

Prerequisites

  • Microsoft Fabric capacity: F2 or higher (or Power BI Premium P1+ with Fabric enabled)
  • Fabric Admin Portal access (for tenant settings)
  • At least one data source with data: lakehouse, warehouse, Power BI semantic model, KQL database, or ontology
  • Workspace Contributor (or higher) permissions
  • PowerShell 7+ recommended for diagnostic scripts

Quick Diagnosis Workflow

Follow this decision tree to rapidly identify your issue category:

  1. Cannot create data agent? → See Tenant Settings Checklist
  2. Data agent created but queries fail? → See Query remediate
  3. Data source not appearing or erroring? → See Data Source Connectivity
  4. Published agent inaccessible? → See Publishing and Sharing
  5. Integration with Foundry/Teams failing? → See External Integration

Known Limitations (Preview)

These are product limitations, not configuration errors. Do not troubleshoot these as bugs:

LimitationDetail
Read-only queriesAgent generates only SELECT/read queries; no INSERT, UPDATE, or DELETE
English onlyNon-English questions, instructions, and examples are not supported
No unstructured dataPDF, DOCX, TXT files cannot be used as data sources
Lakehouse filesAgent reads lakehouse tables only, not standalone CSV/JSON files
Fixed LLMThe underlying LLM model cannot be changed
Max 5 data sourcesUp to five data sources in any combination per agent
Max 100 example queriesPer data source limit for example query pairs
Cross-region blockedData source and agent capacities must be in the same region
Conversation historyMay reset during backend updates or model upgrades
No PBI example queriesPower BI semantic models do not support sample query/question pairs

Common Error Patterns

SymptomLikely CauseQuick Fix
"Data agent" item type missingTenant setting disabledEnable "Fabric data agent" in Admin Portal
Agent created but no responseCopilot tenant switch offEnable "Users can use Copilot and other features powered by Azure OpenAI"
Cross-geo processing errorCross-geo settings disabledEnable both cross-geo processing AND storing settings
XMLA connection failureXMLA endpoints not enabledEnable "Allow XMLA endpoints" in Integration settings
Query returns empty/wrong resultsPoor table/column names or missing examplesAdd descriptive names and example query pairs
"Cannot execute query" errorCapacity region mismatchMove agent or data source to same region capacity
First queries fail after creationAgent initialization delayWait 2-3 minutes after creation before querying
Example queries ignoredInvalid SQL/KQL syntaxValidate all example queries match schema exactly
Published agent not visiblePermissions not sharedShare agent with Read permission to target users
403 Forbidden on data sourceUser lacks data accessGrant workspace Contributor or data Read permissions

Diagnostic Script

Run the Fabric Data Agent Diagnostic PowerShell script to validate tenant settings and connectivity prerequisites programmatically.

./scripts/Test-FabricDataAgentConfig.ps1 -WorkspaceId "<guid>" -Verbose

Configuration Validation Template

Use the Configuration Checklist template to document and track your data agent configuration for team handoff or support tickets.

References

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.