AgentSkillsCN

fabric-data-agent-remediate

诊断并解决 Microsoft Fabric 数据代理的问题，包括租户设置、数据源配置、查询生成失败、跨区域容量错误、XMLA 端点设置、Power BI 语义模型集成、湖仓/仓库/KQL 连接、示例查询验证、发布/共享问题，以及 Azure AI Foundry 集成等问题。适用于在被要求排查数据代理问题、修复 Fabric AI 代理、调试 NL2SQL/NL2DAX/NL2KQL、解决 Copilot 租户设置，或诊断 Fabric 数据代理错误时使用。

SKILL.md
--- frontmatter
name: fabric-data-agent-remediate
description: 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.
license: Complete terms in LICENSE.txt

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.

powershell
./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