Fabric Data Agent API: Complete Guide to the Public Preview (2026)

The Fabric Data Agent API entered public preview at Microsoft Build 2026 and quietly changed what is possible when you connect a large language model to enterprise analytical data. Instead of shipping raw table access to an LLM and hoping it invents good SQL, the Data Agent API gives you a governed, schema-aware, permission-respecting question-answering surface over any Fabric semantic model, warehouse, lakehouse, or KQL database. This guide is the first independent deep-dive on the API for enterprise analytics teams. It covers what the Data Agent is, how the API differs from the in-product Copilot experience, how to authenticate, how to design prompts that reliably return correct answers, how to embed the agent into your own applications, and what to watch before you promote it to production.

What Is the Fabric Data Agent?

A Fabric Data Agent is a governed, model-grounded AI endpoint. You point it at one or more Fabric data items — semantic models, warehouses, lakehouses, KQL databases — and Fabric wraps those items with metadata (table names, column descriptions, measure names, business glossary terms, sample queries, few-shot examples) that the LLM uses at inference time to translate natural language questions into correct, permission-scoped queries against your data. The agent handles three hard problems that raw LLM-over-database patterns fail at:

• Schema grounding: the agent introspects your semantic model measures and DAX, warehouse columns, and Delta table stats, so it does not hallucinate column names or invent joins that do not exist.
• Permission propagation: queries execute under the *end user's* identity, so row-level security in the semantic model and object-level permissions in the warehouse are enforced automatically. There is no way for a Data Agent to accidentally leak a row a user cannot see.
• Answer verification: the agent returns not just an answer but the exact DAX, T-SQL, or KQL it generated, plus row counts, execution time, and a citation trail. This is the difference between a demo-quality chatbot and a production analytics assistant.

At Build 2026, Microsoft demonstrated the Data Agent answering questions like "What was our top-margin product category last quarter, broken down by region and shipping method?" — a query that would have required a data analyst to write joined DAX or SQL with three CALCULATE filters. The agent produced the answer in under three seconds with a citation link back to the exact measure and the underlying query.

Data Agent API vs Copilot in the Fabric Portal

Copilot in the Fabric portal has been available since 2024. The Data Agent API is different and more powerful for enterprise embedding scenarios. Here is the comparison every architect needs before choosing between them:

If your goal is to give your Fabric users a better in-portal experience, use Copilot. If your goal is to embed data-grounded AI answers into a customer-facing product, a Teams bot, a Slack app, or a mobile field-worker app, you need the Data Agent API. The two are complementary — many enterprise deployments will use both.

Data Agent API Architecture

The Data Agent API is a REST API exposed at `/v1.0/myorg/agents/{agentId}/query`. When a client sends a natural language question, the following happens in order:

1. Authentication and permission resolution. Fabric validates the caller's OAuth token, resolves the effective identity (either the end user via on-behalf-of, or the service principal for system integrations), and pulls the identity's row-level security context from every grounded semantic model.
2. Question rewriting and planning. The LLM (currently GPT-4.1 for the preview, with an option to swap in Azure-hosted models on a private tenant) rewrites ambiguous questions using the agent's business glossary and few-shot examples, then decides which grounded data item is the right source.
3. Query generation and validation. The LLM produces DAX (for semantic models), T-SQL (for warehouses), Spark SQL (for lakehouses), or KQL (for KQL databases). Fabric validates the query against the schema before execution — hallucinated table names or bad joins are rejected before touching your data.
4. Query execution under end-user identity. The validated query runs in Fabric's engine with the caller's permissions. Row-level security fires. Object-level security fires. The query cannot see data the caller cannot see.
5. Answer synthesis with citations. The LLM turns the query result into a natural language answer, attaches the exact query text, cites the source item and measure/column names, and returns the response.
6. Optional tool use. For multi-step questions ("compare Q3 to Q4 and explain the difference"), the agent can chain multiple queries in a single conversation turn, and each query is validated and executed under the same identity.

The full request/response cycle typically completes in 1.5 to 4 seconds depending on query complexity, LLM cold-start, and Fabric capacity headroom.

Authentication Patterns for the Data Agent API

Choosing the right authentication pattern is the difference between a secure enterprise integration and a production incident. Here are the three patterns and when to use each.

Pattern 1: On-Behalf-Of (OBO) — for user-facing apps

Use OBO when a real end user is asking the question and you need row-level security to fire under their identity. The flow: your app authenticates the user against Entra ID, exchanges the user's token for a Fabric-scoped token using OBO, and passes that token in the `Authorization: Bearer` header to the Data Agent API.

```typescript // Node.js example — OBO token exchange import { ConfidentialClientApplication } from '@azure/msal-node';

const msal = new ConfidentialClientApplication({ auth: { clientId: process.env.APP_CLIENT_ID!, clientSecret: process.env.APP_CLIENT_SECRET!, authority: `https://login.microsoftonline.com/${process.env.TENANT_ID}`, }, });

async function getFabricTokenOBO(userAccessToken: string) { const result = await msal.acquireTokenOnBehalfOf({ oboAssertion: userAccessToken, scopes: ['https://api.fabric.microsoft.com/Item.ReadWrite.All'], }); return result?.accessToken; } ```

Pattern 2: Service Principal — for system-to-system integrations

Use a service principal when the caller is a background job, a scheduled process, or an integration that needs to run without a user context. Trade-off: RLS runs under the service principal's identity, so you must either grant the service principal the appropriate role or design the agent for aggregated data that does not require user-scoped filtering.

Pattern 3: Managed Identity — for Azure-hosted apps

Use a managed identity when your app runs in Azure (Functions, App Service, AKS, VMs). The token exchange is handled by the Azure platform and you never see the credential. This is the pattern I recommend for any Fabric integration hosted in Azure.

Prompt Engineering for the Data Agent

Data Agent quality depends heavily on the instruction template and few-shot examples you give the agent. Here is the pattern I use in enterprise deployments:

1. Business context (2-3 sentences): what industry, what use case, what audience.
2. Terminology map (bulleted list): every ambiguous business term mapped to the exact measure or column name in the data. Example: "revenue" → "Total Revenue (Net)" measure; "customer" → the "DimCustomer" dimension.
3. Answer format (short paragraph): whether to return numbers as currency, percentages as decimals or basis points, dates as ISO or long form, and when to include an executive summary versus a raw data answer.
4. Refusal rules (bulleted list): when to refuse to answer. Example: "If a question asks about individual customer records or PII, respond with a suggestion to use the customer 360 report instead of returning raw data."
5. Few-shot examples (5-10 question-and-answer pairs): the same category of question the users will actually ask, with the exact DAX or SQL the agent should generate. This is where accuracy comes from.

Skip the terminology map and you will spend the next three weeks fielding tickets that say "the agent doesn't understand what we mean by margin." Include it and the agent will be right the first time.

Grounding Sources: Semantic Model vs Warehouse vs Lakehouse

You can ground a Data Agent on any Fabric item, but each source has different accuracy characteristics for different question types:

• Semantic model (Direct Lake or Import): best for questions that map to measures your BI team has already defined. Time intelligence, ratios, hierarchical filters. DAX quality is generally high because the LLM has the measure library to lean on.
• Warehouse (T-SQL): best for exploratory questions that need aggregations over raw columns, or when the semantic model does not have the required measure. T-SQL generation is very reliable when the warehouse has documented column descriptions.
• Lakehouse (Spark SQL): best for questions over unstructured or semi-structured data, or over datasets too large or too rarely queried to model in a semantic model.
• KQL database: best for time-series and log/event questions. KQL generation improved dramatically in Build 2026's model update.

For most enterprises, the sweet spot is a Data Agent grounded on one primary semantic model (for the common business questions) and one secondary warehouse (for the "I need to dig into raw data" fallback). Do not ground an agent on more than 3-4 items in the preview — the LLM's ability to correctly pick the right source degrades quickly beyond that.

Cost Model and Capacity Sizing

The Data Agent API bills capacity units (CUs) per query. The current preview pricing is:

• Query planning + validation: 8 CU-seconds per query, fixed.
• Query execution: variable, matches the underlying engine cost (DAX in semantic model, T-SQL in warehouse, Spark SQL in lakehouse, KQL in KQL DB).
• Answer synthesis: 4 CU-seconds per query, fixed.

A representative enterprise workload of 1,000 queries per day at moderate complexity consumes approximately 200 CU-hours per month. That fits comfortably in an F32 capacity if the agent is the only workload, or in an F64 alongside typical Power BI reporting workloads. For latency-sensitive customer-facing applications, provision an F64 minimum to avoid CU throttling during peak hours.

Production Readiness Checklist

Before promoting a Data Agent from public preview to production, verify every item on this list:

• [ ] All grounded items have full column and measure descriptions filled in (empty descriptions cause hallucinations).
• [ ] Business glossary has been reviewed by domain experts and includes every synonym users actually say.
• [ ] Row-level security has been tested with at least three distinct user identities to confirm data isolation.
• [ ] Instruction template includes explicit refusal rules for PII, sensitive columns, and out-of-scope questions.
• [ ] At least 20 few-shot examples cover the top question categories users will ask.
• [ ] Response latency P95 measured under representative load and confirmed under the SLA you promised.
• [ ] Fabric capacity has 30% CU headroom above measured peak load.
• [ ] Query logs are being exported to Log Analytics or a data lake for audit and quality improvement.
• [ ] User feedback mechanism (thumbs up / thumbs down + free text) is wired into the client app so the analytics team can spot quality regressions.
• [ ] Fallback path is defined for when the agent cannot answer (typically: escalate to the analytics team via a ticket, or return a pre-canned response with a link to the relevant report).

What Is Still Missing in the Preview

The Data Agent API is genuinely useful today, but three capabilities are still on Microsoft's roadmap and worth waiting for before you commit to certain architectures:

1. Native model swapping. The preview is locked to GPT-4.1. Enterprises wanting Azure-hosted or private Anthropic models must wait for GA.
2. Multi-turn conversation memory at the API layer. Today you must manage conversation history in your own app. GA is expected to add server-side conversation state.
3. Fine-grained CU quotas per agent. Today CU is capacity-wide. GA will let you cap CU per agent so a runaway consumer app cannot starve the rest of your Fabric workloads.

Related Guides

• Microsoft Fabric Real-Time Intelligence: Complete Guide
• Direct Lake+ vs Import Mode: The 2026 Decision Framework
• Microsoft Fabric vs Power BI Premium: Break-Even Analysis
• Microsoft Fabric Consulting Services

Ready to prototype a Data Agent on your own Fabric estate? Book a free 30-minute strategy call and we will scope a preview implementation on a single semantic model with your top-10 user questions as few-shot examples.