Skip to content

Commit a0b296b

Browse files
authored
Merge pull request #54314 from MicrosoftDocs/NEW-fabric-data-agent
Add Fabric IQ learning path and build-fabric-data-agent-ontology module
2 parents 0e95a7f + 2440d43 commit a0b296b

22 files changed

Lines changed: 407 additions & 1 deletion
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
### YamlMime:LearningPath
2+
uid: learn.wwl.get-started-fabric-iq
3+
metadata:
4+
title: Get Started with Fabric IQ
5+
description: Learn how to use Fabric IQ to model business concepts in an ontology, bind them to data sources, visualize relationships, and build data agents grounded in your business vocabulary.
6+
ms.date: 04/17/2026
7+
author: theresa-i
8+
ms.author: theresai
9+
ms.topic: learning-path
10+
title: Get started with Fabric IQ
11+
prerequisites: |
12+
- Familiarity with Microsoft Fabric workspaces and navigation
13+
- Basic understanding of data concepts such as tables, relationships, and queries
14+
summary: |
15+
Fabric IQ lets you define business vocabulary in an ontology and bind it to data sources in OneLake. In this learning path, you start with the fundamentals of Fabric IQ, then build an ontology by creating entity types and relationships, visualize your data through interactive graphs, and connect an ontology to a data agent so business users can ask questions in natural language.
16+
iconUrl: /training/achievements/generic-trophy.svg
17+
levels:
18+
- beginner
19+
roles:
20+
- data-analyst
21+
- data-engineer
22+
products:
23+
- fabric
24+
subjects:
25+
- data-analytics
26+
modules:
27+
- learn.wwl.understand-fabric-iq-fundamentals
28+
- learn.wwl.create-ontology-with-fabric-iq
29+
- learn.wwl.visualize-ontology-fabric-iq
30+
- learn.wwl.build-fabric-data-agent-ontology
31+
trophy:
32+
uid: learn.wwl.get-started-fabric-iq.trophy
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.build-fabric-data-agent-ontology.introduction
3+
title: Introduction
4+
metadata:
5+
title: Introduction
6+
description: Introduction to building a Fabric data agent with an ontology as its data source, letting clinical staff ask natural language questions and get governed answers without writing code.
7+
ms.date: 04/17/2026
8+
author: theresa-i
9+
ms.author: theresai
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
azureSandbox: false
13+
labModal: false
14+
durationInMinutes: 3
15+
content: |
16+
[!include[](includes/1-introduction.md)]
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.build-fabric-data-agent-ontology.understand-fabric-data-agents-ontology
3+
title: Understand Fabric data agents and ontology as a data source
4+
metadata:
5+
title: Understand Fabric Data Agents and Ontology as a Data Source
6+
description: Learn what a Fabric data agent is, how it uses an ontology as a data source to map natural language questions to entity types and relationships, and why GQL is the query language used for ontology data sources.
7+
ms.date: 04/17/2026
8+
author: theresa-i
9+
ms.author: theresai
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
azureSandbox: false
13+
labModal: false
14+
durationInMinutes: 8
15+
content: |
16+
[!include[](includes/2-understand-fabric-data-agents-ontology.md)]
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.build-fabric-data-agent-ontology.create-fabric-data-agent-connect-ontology
3+
title: Create a Fabric data agent and connect it to an ontology
4+
metadata:
5+
title: Create a Fabric Data Agent and Connect It to an Ontology
6+
description: Learn how to create a Fabric data agent in your workspace, connect an ontology as a data source, and configure agent instructions to improve query accuracy.
7+
ms.date: 04/17/2026
8+
author: theresa-i
9+
ms.author: theresai
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
azureSandbox: false
13+
labModal: false
14+
durationInMinutes: 8
15+
content: |
16+
[!include[](includes/3-create-fabric-data-agent-connect-ontology.md)]
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.build-fabric-data-agent-ontology.test-validate-publish-fabric-data-agent
3+
title: Test, validate, and publish a Fabric data agent
4+
metadata:
5+
title: Test, Validate, and Publish a Fabric Data Agent
6+
description: Learn how to test a Fabric data agent with natural language questions, examine the generated GQL queries and reasoning steps, refine agent instructions, and publish and share the agent with colleagues.
7+
ms.date: 04/17/2026
8+
author: theresa-i
9+
ms.author: theresai
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
azureSandbox: false
13+
labModal: false
14+
durationInMinutes: 8
15+
content: |
16+
[!include[](includes/4-test-validate-publish-fabric-data-agent.md)]
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.build-fabric-data-agent-ontology.exercise-build-data-agent-ontology
3+
title: Exercise - Build a Fabric data agent with an ontology
4+
metadata:
5+
title: Exercise - Build a Fabric Data Agent with an Ontology
6+
description: Practice creating a Fabric data agent connected to a Lamna Healthcare ontology, configuring agent instructions, testing natural language queries, and publishing the agent.
7+
ms.date: 04/17/2026
8+
author: theresa-i
9+
ms.author: theresai
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
azureSandbox: false
13+
labModal: false
14+
durationInMinutes: 30
15+
content: |
16+
[!include[](includes/5-exercise-build-data-agent-ontology.md)]
Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.build-fabric-data-agent-ontology.knowledge-check
3+
title: Module assessment
4+
metadata:
5+
title: Module Assessment
6+
module_assessment: true
7+
ai_generated_module_assessment: false
8+
description: Check your knowledge of creating, configuring, testing, and publishing a Fabric data agent with an ontology as its data source.
9+
ms.date: 04/17/2026
10+
author: theresa-i
11+
ms.author: theresai
12+
ms.topic: unit
13+
ai-usage: ai-generated
14+
azureSandbox: false
15+
labModal: false
16+
durationInMinutes: 5
17+
quiz:
18+
title: "Check your knowledge"
19+
questions:
20+
- content: "What query language does a Fabric data agent generate when an ontology is the data source?"
21+
choices:
22+
- content: "GQL (Graph Query Language), because it traverses the graph structure of the ontology."
23+
isCorrect: true
24+
explanation: "Correct. When an ontology is the data source, the agent generates GQL to traverse entity types and relationships. SQL is used for lakehouses and warehouses; KQL is used for KQL databases; DAX is used for Power BI semantic models."
25+
- content: "SQL, because the ontology is bound to lakehouse tables."
26+
isCorrect: false
27+
explanation: "Incorrect. Although the ontology binds to lakehouse tables, the agent queries the ontology layer using GQL, not SQL directly. GQL is designed to traverse the graph structure of entity types and relationships."
28+
- content: "KQL, because the ontology includes an eventhouse data source."
29+
isCorrect: false
30+
explanation: "Incorrect. KQL is used when the agent queries a KQL database data source directly. When the data source is an ontology, the agent uses GQL regardless of what underlying sources the ontology binds to."
31+
- content: "When an ontology is the data source for a Fabric data agent, how do you improve the agent's accuracy?"
32+
choices:
33+
- content: "By refining agent instructions, which guide how the agent interprets terminology, reasoning steps, response behavior, and scope."
34+
isCorrect: true
35+
explanation: "Correct. For ontology data sources, agent instructions are how you shape the agent's behavior. Instructions let you map user terminology to ontology concepts, define reasoning paths, set response format expectations, and constrain scope."
36+
- content: "By adding example query/question pairs to the data source configuration."
37+
isCorrect: false
38+
explanation: "Incorrect. Example queries aren't supported for ontology data sources. They're available for lakehouses, warehouses, and KQL databases. For ontology sources, use agent instructions to guide interpretation."
39+
- content: "By modifying the ontology entity type definitions to match user phrasing."
40+
isCorrect: false
41+
explanation: "Incorrect. Modifying entity type definitions changes the underlying data model, which affects all tools connected to the ontology. The correct approach is to write agent instructions that map user terminology to existing ontology concepts."
42+
- content: "A colleague receives a shared link for a published Fabric data agent backed by an ontology. They have the default (no extra) permission on the data agent link, but no permissions on the ontology item or its underlying lakehouse. What happens when they try to query the agent?"
43+
choices:
44+
- content: "Their queries fail or return empty results, because they lack the required Read permissions on the ontology and its underlying data sources."
45+
isCorrect: true
46+
explanation: "Correct. For ontology-backed data agents, users need Read permission on both the ontology item and the underlying data sources (such as the lakehouse and KQL database) bound to the ontology. The data agent link alone isn't sufficient."
47+
- content: "Their queries succeed, because the default permission grants full read access to all connected data sources."
48+
isCorrect: false
49+
explanation: "Incorrect. The default permission grants access to query the published version of the data agent only. Users still need separate Read permissions on the ontology item and its underlying data sources for queries to return results."
50+
- content: "They can only see the draft version of the agent, not the published version."
51+
isCorrect: false
52+
explanation: "Incorrect. The default permission (no extra permissions) grants access to the published version only—not the draft version. However, without Read on the ontology and its data sources, queries against even the published version will fail."
53+
- content: "After publishing a Fabric data agent, what happens to the draft version?"
54+
choices:
55+
- content: "The draft version remains editable, allowing you to continue refining the agent without affecting the published version that colleagues use."
56+
isCorrect: true
57+
explanation: "Correct. Publishing creates a stable published version while leaving the draft version available for ongoing development. Changes to the draft don't affect the published version, so you can iterate safely."
58+
- content: "The draft version is automatically deleted when you publish."
59+
isCorrect: false
60+
explanation: "Incorrect. Publishing does not delete the draft version. Both versions exist simultaneously after publishing — the draft for continued development and the published version for colleague access."
61+
- content: "The draft version becomes read-only and can no longer be edited."
62+
isCorrect: false
63+
explanation: "Incorrect. The draft version remains fully editable after publishing. This is intentional — it lets you incorporate feedback and refine the agent over time without disrupting the stable published version."
Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
### YamlMime:ModuleUnit
2+
uid: learn.wwl.build-fabric-data-agent-ontology.summary
3+
title: Summary
4+
metadata:
5+
title: Summary
6+
description: Summary of building, configuring, testing, and publishing a Fabric data agent with an ontology as its data source for natural language queries over governed hospital data.
7+
ms.date: 04/17/2026
8+
author: theresa-i
9+
ms.author: theresai
10+
ms.topic: unit
11+
ai-usage: ai-generated
12+
azureSandbox: false
13+
labModal: false
14+
durationInMinutes: 3
15+
content: |
16+
[!include[](includes/7-summary.md)]
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
Imagine you work for a fictitious company called Lamna Healthcare. Your organization has consolidated data from multiple operational systems into a Microsoft Fabric lakehouse and eventhouse, and built a Fabric IQ ontology that models the hospital domain — hospitals, departments, rooms, patients, and vital sign monitoring equipment. In this module, you learn how to build a Fabric data agent on top of that ontology — how to create the agent, connect it to the ontology, configure instructions to improve accuracy, test it with natural language questions, and publish it so colleagues can ask questions and get answers directly from the data.
2+
3+
> [!IMPORTANT]
4+
> Ontology in Microsoft Fabric is currently in [preview](/fabric/fundamentals/preview).
Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
A Fabric data agent is a conversational interface to your data. It connects to data sources in your Fabric environment — people ask questions in natural language and get data-backed answers without writing queries or building reports. In this module, the focus is on using an ontology as the data source.
2+
3+
## What is a Fabric data agent?
4+
5+
When you ask a question, the agent identifies the relevant data source, generates a query in the appropriate language (SQL, DAX, KQL, or GQL depending on the source type), executes the query, and returns the result.
6+
7+
Each agent can connect to up to five data sources in any combination:
8+
9+
- **Lakehouses** — query Delta tables using SQL
10+
- **Warehouses** — query structured data using SQL
11+
- **KQL databases** — query event streams and time-series data using KQL
12+
- **Power BI semantic models** — query business metrics using DAX
13+
- **Ontologies** — query graph-structured domain models using GQL
14+
- **Microsoft Graph** — query organizational data (people, calendars, files) using Microsoft Graph APIs
15+
16+
> [!NOTE]
17+
> The agent runs under the querying user's Entra ID identity — it can only reach data that user is authorized to view, and it's strictly read-only. For more information, see [Fabric data agent sharing and permission management](/fabric/data-science/data-agent-sharing#sharing-permission-models-and-required-source-access).
18+
19+
## What is an ontology?
20+
21+
An **ontology** is a structured model that describes your business domain — the entity types, their properties, and how they relate to each other. Instead of raw column names like `rm_id` or `adm_flag` that you might find in a database schema, an ontology uses business terms like `Room`, `Patient`, and `admittedTo`.
22+
23+
The Lamna Healthcare ontology defines entity types like **Hospital**, **Department**, **Room**, **Patient**, and **VitalSignEquipment**. Each entity type has properties that describe its characteristics: a Room has properties like `roomNumber`, `capacity`, and `isOccupied`. Relationships connect entities in meaningful ways: a Patient is `admittedTo` a Room, and a Room is `inDepartment` a Department.
24+
25+
**Connecting to the ontology** gives the agent a structured vocabulary so it maps natural language questions to defined entity types, properties, and relationship labels rather than guessing from raw column names. The Lamna ontology is bound to lakehouse tables and an eventhouse — when the agent queries through the ontology layer, it accesses real data while using the conceptual structure the ontology provides.
26+
27+
This combination of meaningful vocabulary and real data bindings makes the ontology a bridge between how clinical staff ask questions and how data is stored.
28+
29+
## How the agent uses the ontology
30+
31+
When you use an ontology as the data source, the Fabric data agent generates **GQL (Graph Query Language)**. GQL is designed to traverse the graph structure of the ontology, following relationships between entities.
32+
33+
Here's how it works. When a nurse manager asks "Which departments have patients without vital sign equipment assigned?", the agent matches "departments" to the `Department` entity type, traverses the `inDepartment` relationship to find rooms, follows `admittedTo` to reach patients, and checks whether a `VitalSignEquipment` entity is linked to each patient's room. This semantic understanding guides the agent to generate GQL that retrieves the answer.
34+
35+
The process relies on the ontology's structure. The agent interprets "ICU" as a department filter, "beds" as rooms, and "occupied" as the `isOccupied` property or the presence of an `admittedTo` relationship. This mapping happens because the ontology defines these concepts explicitly. But terms like "ICU" or "beds" aren't always exact matches to entity type names or property values. That's where **instructions** come in — natural language guidance you write when configuring the agent to explain how domain-specific vocabulary maps to ontology concepts.
36+
37+
The agent's ability to generate accurate GQL depends entirely on how well the ontology models your domain and how clearly your instructions explain common question patterns.
38+
39+
## What the ontology layer provides
40+
41+
The agent inherits the ontology's governance layer. Entity definitions, relationships, and data bindings all flow through the ontology — you manage these in one place rather than configuring them separately for each agent. When the clinical team adds a new entity type like `MedicalDevice`, the agent immediately understands questions about devices without reconfiguration.
42+
43+
This centralized structure also means every user who asks the same question gets the same interpretation. The ontology defines how domain vocabulary maps to data, so results are consistent and repeatable.

0 commit comments

Comments
 (0)