Azure Fabric Data Agents

Microsoft Fabric Data Agents

Conversational analytics agents inside Microsoft Fabric — a generally available Fabric workspace item type (DataAgent) that grounds an Azure-OpenAI-Assistants-API agent on data living in OneLake. Accessible from the Fabric portal chat surface, from Microsoft 365 Copilot / Teams (via sharing), and programmatically via the fabric-data-agent-sdk Python package inside Fabric notebooks.

Sources & scope — this skill is grounded in the Microsoft Learn docs at learn.microsoft.com/en-us/fabric/data-science/concept-data-agent, …/how-to-create-data-agent, …/data-agent-sharing, …/fabric-data-agent-sdk, …/data-agent-tenant-settings, the REST API reference at learn.microsoft.com/en-us/rest/api/fabric/dataagent/items/create-data-agent, and the official sample notebooks at github.com/microsoft/fabric-samples/tree/main/docs-samples/data-science/data-agent-sdk. Where docs and samples disagree (most notably on capacity SKU), this skill calls it out explicitly.

For a 20-minute first-agent path, see azure-fabric-data-agents-quickstart.

Architecture

User (chat surface: Fabric portal, M365 Copilot, Teams, embedded app, notebook)
  │
  ▼
Fabric Data Agent (workspace item, type=DataAgent)
  │  ├── instructions          (agent-level persona & rules)
  │  ├── data sources (max 5)  ─┐
  │  │                          │  per-source:
  │  │                          ├── selected tables (whitelist)
  │  │                          ├── datasource instructions
  │  │                          └── few-shot examples (NL → SQL/DAX/KQL)
  │  └── publish state          (Draft → Published)
  ▼
Microsoft-managed Azure OpenAI Assistants API
  │  parses Q → routes to a tool → generates query → validates → executes
  ▼
Per-source query engines  (NL2SQL / NL2DAX / NL2KQL / Microsoft Graph / Ontology)
  │
  └── Auth: caller's Entra ID identity. Read-only. Honors:
       • workspace RBAC + item permissions
       • Power BI model RLS / OLS
       • OneLake item ACLs (incl. shortcuts & cross-tenant shares)
       • Purview DLP (Warehouse, GA), access-restriction policies
         (Warehouse / KQL DB / Fabric SQL DB, preview), sensitivity labels

Three things to understand first

1. The agent is GA, but the Python SDK and several governance features are still preview. Don't conflate them.
2. It is read-only. "The Fabric data agent strictly enforces read-only access, maintaining read-only data connections to all data sources."
3. There is no service-account "execution mode." Every query runs as the Entra ID identity of the caller (user OR service principal calling the API). Workspace + data permissions of that identity gate everything.

Prerequisites

Provisioning

There are three supported ways to create and configure a Data Agent:

SDK path (recommended for code-first)

%pip install fabric-data-agent-sdk     # only inside a Fabric notebook

from fabric.dataagent.client import (
    FabricDataAgentManagement,
    create_data_agent,
    delete_data_agent,
)

# Create new — errors with ConflictName if it already exists
data_agent = create_data_agent("sales-analyst")

# Or attach to existing
data_agent = FabricDataAgentManagement("sales-analyst")

# Inspect current configuration
data_agent.get_configuration()

# Add agent-level instructions
data_agent.update_configuration(instructions="""
You are the Sales Analyst. You answer questions about pipeline, bookings,
quotas, and rep performance using the lakehouse and warehouse attached.

Rules:
- "Booked revenue" = SUM(amount_usd) WHERE stage = 'Closed Won'.
- "Pipeline" = stage NOT IN ('Closed Won','Closed Lost').
- Fiscal year starts February 1 — use fiscal_quarter, not calendar quarter,
  unless the user explicitly says "calendar".
- Always show the executed SQL/DAX/KQL beneath the answer.
- Out of scope: root cause, prediction, why-questions. Refuse and stop.
""")

# Add data sources (up to 5 total per agent, in any combination)
data_agent.add_datasource("sales_lakehouse",  type="lakehouse")
data_agent.add_datasource("sales_warehouse",  type="warehouse")
data_agent.add_datasource("Sales Model",      type="semanticmodel")
data_agent.add_datasource("EventsKQL",        type="kqldatabase")

# Per-source: select tables (NOTHING is selected by default)
ds = data_agent.get_datasources()[0]
ds.pretty_print()                       # tables marked "*" are visible to the agent
ds.select("dbo", "opportunities")       # whitelist
ds.select("dbo", "quotas")
ds.unselect("dbo", "internal_audit")    # explicit removal

# Per-source instructions (query-generation hints)
ds.update_configuration(instructions="""
- For revenue questions, use opportunities.amount_usd (already FX-normalized).
- For quota math, JOIN opportunities to quotas on owner_email AND fiscal_quarter.
""")

# Per-source few-shot examples (NL → query, dialect of the source)
ds.add_fewshots({
    "Q1 2026 booked revenue by region":
        "SELECT region, SUM(amount_usd) AS booked_revenue_usd "
        "FROM dbo.opportunities "
        "WHERE stage = 'Closed Won' "
        "  AND close_date BETWEEN '2026-01-01' AND '2026-03-31' "
        "GROUP BY region ORDER BY booked_revenue_usd DESC",
    "Pipeline coverage for next quarter by rep":
        "SELECT o.owner_email, "
        "       SUM(CASE WHEN o.stage NOT IN ('Closed Won','Closed Lost') THEN o.amount_usd END) AS open_pipe, "
        "       q.quota_usd "
        "FROM dbo.opportunities o "
        "LEFT JOIN dbo.quotas q ON q.owner_email = o.owner_email AND q.quarter = '2026Q2' "
        "WHERE o.close_date BETWEEN '2026-04-01' AND '2026-06-30' "
        "GROUP BY o.owner_email, q.quota_usd",
})
ds.get_fewshots()

# Inspect / delete a few-shot
ds.remove_fewshot("<fewshot-id-from-get_fewshots>")

# Publish — until you publish, only the creator can chat
data_agent.publish()

# Delete (cleanup)
delete_data_agent("sales-analyst")

Portal path (recommended for first agent)

+ New item → search "Fabric data agent" → name it → the OneLake catalog opens → Add a data source (one at a time; up to 5) → in the left Explorer pane, check the tables that the agent should see → start chatting in the right pane → use Edit instructions and Add example in the UI.

Microsoft's tip from the docs: "Use descriptive names for both tables and columns. A table named SalesData is more meaningful than TableA, and column names like ActiveCustomer or IsCustomerActive are clearer than C1 or ActCu. Descriptive names help the AI generate more accurate and reliable queries."

REST path (CI/CD)

FABRIC_TOKEN=$(az account get-access-token \
  --resource https://api.fabric.microsoft.com --query accessToken -o tsv)

# Minimal create — no definition; you configure via SDK or portal afterwards.
curl -sX POST "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/dataAgents" \
  -H "Authorization: Bearer $FABRIC_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "displayName": "sales-analyst", "description": "Sales agent" }'

The definition body, when supplied, is a parts[] array of base64-encoded JSON files at paths like Files/Config/data_agent.json, Files/Config/draft/lakehouse-<name>/datasource.json, Files/Config/draft/lakehouse-<name>/fewshots.json, Files/Config/draft/stage_config.json, Files/Config/published/..., and Files/Config/publish_info.json. The SDK is the practical way to produce these payloads — see the REST reference for the exact shape.

Required Entra scope for the API: Item.ReadWrite.All. Service principals and managed identities are supported.

Identity & Access

The agent always runs queries as the Entra ID identity of the caller — there is no "service account execution mode" toggle. The chatting principal's permissions are the floor.

What permissions a chatter actually needs

Cross-tenant data

If your workspace contains tables shared in via OneLake external data sharing, the agent queries them through the OneLake shortcut created at share-acceptance — no extra credentials, runs under the consumer's Entra ID, and consumer-tenant governance applies.

Sharing

Per data-agent-sharing, agents are shared as a first-class operation distinct from workspace RBAC. Share dialog supports per-user/group permission tiers. Recipients still need read on the underlying data sources (or, for semantic models, just Read on the model) for queries to actually return data — sharing the agent does not elevate data access.

Operational rule: the agent's share is who can chat; the data sources' permissions are who gets answers. If a user can chat but gets "no access," they're missing data permissions, not agent permissions.

What to put in instructions vs few-shots vs descriptions

The agent has three context surfaces. Use each for what it's good at:

Always validate few-shots with the Few-Shot Examples Validator notebook (Fabric-DataAgent-Few-Shot-Examples-Validator-sample.ipynb in the fabric-samples repo) — it actually runs each example's SQL and checks the result is non-empty and well-formed.

Consumption (chat from code)

Use the FabricOpenAI client bundled with fabric-data-agent-sdk. It wraps the Azure OpenAI Assistants API with the agent as the assistant target.

from fabric.dataagent.client import FabricOpenAI

fabric_client = FabricOpenAI(artifact_name="sales-analyst")

assistant = fabric_client.beta.assistants.create(model="gpt-4o")
thread    = fabric_client.beta.threads.create()

fabric_client.beta.threads.messages.create(
    thread_id=thread.id, role="user",
    content="Q1 2026 booked revenue by region",
)

run = fabric_client.beta.threads.runs.create_and_poll(
    thread_id=thread.id, assistant_id=assistant.id,
)
assert run.status == "completed", run.status

for m in fabric_client.beta.threads.messages.list(thread_id=thread.id).data:
    if m.role == "assistant":
        for part in m.content:
            if part.type == "text":
                print(part.text.value)
        break

Multi-turn: reuse thread.id across calls. The agent maintains conversational context within a thread.

The SDK is only supported inside Fabric notebooks. Microsoft explicitly says it "isn't supported for local execution." For non-notebook automation use a notebook scheduled in a pipeline, a Spark Job Definition, or call the REST API directly.

Governance & Safety

Microsoft Purview integration

Per the concept doc, the following Purview capabilities apply to Data Agents:

Outbound access protection

Outbound connections from agents are subject to the tenant's network and access rules in the Fabric admin portal. Admins can control which external endpoints agents may reach.

Cross-region rule (hard fail)

"The Fabric data agent can't execute queries when the data source's workspace capacity is in a different region than the data agent's workspace capacity."

Example: agent in France Central, lakehouse in North Europe → query fails. Fix: move the agent's workspace to a capacity in the same region as the data, or move/re-shortcut the data.

Read-only enforcement

The agent maintains read-only connections to all sources. Even a crafted prompt cannot get it to issue a write. This is an architectural property, not a guardrail rule — but verify in your audit logs anyway.

Out-of-scope question patterns

Per the docs, these are not what the agent does (it's NL→query, not analysis):

• "Why is Q2 productivity lower?"
• "What is the root cause of the sales spike?"
• "Forecast next quarter's revenue."
• Anything requiring causal inference, ML, or external context.

Put a refusal rule in the agent instructions. Better: include a few-shot whose "answer" is a refusal, so the model learns the pattern.

Evaluation

The SDK ships an evaluation utility plus a sample notebook (Fabric-DataAgent-Evaluation-sample.ipynb). The pattern is the standard golden-set scoring:

1. Maintain a CSV/Delta table of (question, expected_query_or_answer) pairs.
2. For each row, send the question to the agent, capture the executed query and the result.
3. Score correctness (numeric tolerance for aggregates, exact match for labels), latency, refusal-when-out-of-scope, and SQL similarity (e.g., via sqlglot AST comparison).
4. Persist results to a Delta table; chart drift over time.

Re-run weekly (or after every agent edit) and alert on regressions. See the Microsoft blog post on programmatic evaluation for the canonical pattern.

Common Patterns

Pattern: agent-per-domain, not one mega-agent

A single agent capped at 5 sources is also capped in instruction-context budget. For broad analytics, build per-domain agents:

sales-analyst       → sales_lakehouse, crm_warehouse, Sales Model
finance-analyst     → finance_warehouse, billing_lakehouse, Finance Model
ops-analyst         → ops_lakehouse, telemetry_kql
exec-summary        → cross-domain *_summary semantic models

Pattern: curated layer is non-negotiable

Don't point an agent at raw landing tables. Build curated *_curated schemas with descriptive names, column comments, partitioning/liquid clustering, and views that hide unstable internals. The agent is only as good as the schema it reads.

Pattern: validate few-shots in CI

Wire the Few-Shot Examples Validator into a scheduled notebook. Any few-shot whose query returns 0 rows or errors should fail the build — that means schema drift broke the example, and the agent is now learning from broken SQL.

Pattern: snapshot for reproducible answers

If users complain "the agent gave a different number yesterday," it's almost always because the data changed. For monthly-board-deck reproducibility, snapshot *_curated to *_curated_snapshot_YYYYMMDD and bind the agent to the snapshot.

Gotchas

1. F2 vs F64 SKU contradiction. The official prerequisites include says F2 is enough; the official SDK consumption sample says F64. Reality: F2 gets you a functioning agent for the portal chat path; the OpenAI-Assistants notebook consumption path is more reliable on F64+. Plan accordingly.

2. The SDK is preview and notebook-only. Don't try to pip install it on your laptop; it expects the Fabric notebook runtime.

3. The REST definition body is base64-encoded JSON parts, not the friendly {dataSources: [...]} shape that some unofficial blog posts imply. The SDK or portal generates these for you.

4. Default table selection is empty. After add_datasource(), NO tables are visible to the agent until you ds.select("schema", "table"). A freshly-added datasource that returns "I don't see any tables" usually just means you forgot to select.

5. Lakehouse SQL endpoint is read-only. Add column descriptions via Spark ALTER TABLE … ALTER COLUMN … COMMENT '…' on the underlying Delta table, not via T-SQL sp_addextendedproperty against the SQL endpoint (which will fail). Warehouses (writable T-SQL) do accept sp_addextendedproperty.

6. Cross-region = hard fail, not slow. Same-region the agent and all its sources, or use shortcuts to bring the data into the agent's region.

7. Publish or no chat for others. Drafts work only for the creator. Recipients of a share see "no access" until you data_agent.publish().

8. Sharing the agent ≠ granting data access. Recipient still needs Read on each underlying source (except Power BI semantic models, where Read on the model is sufficient and workspace membership is not required).

9. 5 source maximum per agent. Hard cap. Hit this and you need to either consolidate sources via shortcuts/views, or split into multiple agents.

10. Few-shots can override descriptions. A few-shot that joins opportunities to quotas on owner_email will bias the agent toward that join even when irrelevant. Keep few-shots narrow and high-quality.

11. No service-account "mode." Every query runs as the caller. If a Teams bot uses an SP, that SP needs Read on the data sources — and every user of the bot effectively gets the SP's data access, regardless of their own permissions. For mixed-audience bots, build audience filtering at the data layer (separate datasets/lakehouses per audience), not "in the bot."

12. Tenant settings can silently disable agents. "AI skill", "Copilot for Fabric", and "cross-geo processing/storing for AI" all need to be on for your security group. Agents in disabled tenants fail with vague auth errors.

13. Renamed columns require re-publish. Schema changes propagate to the agent only on the next publish. Until then it generates SQL using the old names.

14. The agent does not do analytics. It does NL→SQL/DAX/KQL→answer. Root cause / forecasting / "why" questions are explicitly out of scope per the Microsoft docs. Refuse them in the agent instructions.

Quick Reference

(Per the docs, ontologies, mirrored databases, and Microsoft Graph are also supported source types — check current SDK release notes for the exact type= string for each, which has been moving.)

See also

• azure-fabric-data-agents-quickstart — 20-minute first-agent path
• Concept: learn.microsoft.com/en-us/fabric/data-science/concept-data-agent
• How-to: learn.microsoft.com/en-us/fabric/data-science/how-to-create-data-agent
• SDK: learn.microsoft.com/en-us/fabric/data-science/fabric-data-agent-sdk
• Sharing: learn.microsoft.com/en-us/fabric/data-science/data-agent-sharing
• Tenant settings: learn.microsoft.com/en-us/fabric/data-science/data-agent-tenant-settings
• REST API: learn.microsoft.com/en-us/rest/api/fabric/dataagent
• Sample notebooks: github.com/microsoft/fabric-samples/tree/main/docs-samples/data-science/data-agent-sdk
• Evaluation blog: blog.fabric.microsoft.com/en-US/blog/evaluate-your-fabric-data-agents-programmatically-with-the-python-sdk/