Skip to content

Commit c5a3d04

Browse files
Albertyang0Albertyang0
authored
Merge pull request #3821 from MicrosoftDocs/main
OOB Publish -- 3/31 - 8:00 AM PST
2 parents 7dbd6d3 + 761695f commit c5a3d04

File tree

5 files changed

+345
-0
lines changed

5 files changed

+345
-0
lines changed

‎articles/ai-services/agents/how-to/tools/fabric.md

Lines changed: 328 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,328 @@
1+
---
2+
title: 'How to use the data agents in Microsoft Fabric with Azure AI Agent Service'
3+
titleSuffix: Azure OpenAI
4+
description: Learn how to perform data analytics in Azure AI Agents using Microsoft Fabric data agent.
5+
services: cognitive-services
6+
manager: nitinme
7+
ms.service: azure-ai-agent-service
8+
ms.topic: how-to
9+
ms.date: 02/25/2025
10+
author: aahill
11+
ms.author: aahi
12+
zone_pivot_groups: selection-fabric-data-agent
13+
ms.custom: azure-ai-agents, references_regions
14+
---
15+
16+
# Use the Microsoft Fabric data agent
17+
18+
::: zone pivot="overview"
19+
20+
Integrate your Azure AI Agent with the [**Microsoft Fabric data agent**](https://go.microsoft.com/fwlink/?linkid=2312815) to unlock powerful data analysis capabilities. The Fabric data agent transforms enterprise data into conversational Q&A systems, allowing users to interact with the data through chat and uncover data-driven and actionable insights.
21+
22+
You need to first build and publish a Fabric data agent and then connect your Fabric data agent with the published endpoint. When a user sends a query, Azure AI Agent will first determine if the Fabric data agent should be leveraged or not. If so, it will use the end user’s identity to generate queries over data they have access to. Lastly, Azure AI Agent will generate responses based on queries returned from Fabric data agents. With Identity Passthrough (On-Behalf-Of) authorization, this integration simplifies access to enterprise data in Fabric while maintaining robust security, ensuring proper access control and enterprise-grade protection.
23+
24+
## Usage support
25+
26+
|Azure AI foundry support | Python SDK | C# SDK | JavaScript SDK | REST API |Basic agent setup | Standard agent setup |
27+
|---------|---------|---------|---------|---------|---------|---------|
28+
| ✔️ | ✔️ | - | ✔️ | ✔️ | ✔️ | ✔️ |
29+
30+
## Prerequisites
31+
* You have created and published a Fabric data agent endpoint
32+
33+
* Developers and end users have at least `AI Developer` RBAC role.
34+
35+
* Developers and end users have at least `READ` access to the Fabric data agent and the underlying data sources it connects with.
36+
37+
## Setup
38+
> [!NOTE]
39+
> * The model you selected in Azure AI Agent setup is only used for agent orchestration and response generation. It doesn't impact which model Fabric data agent uses for NL2SQL operation.
40+
> * Supported regions: `westus`, `japaneast`.
41+
1. Create an Azure AI Agent by following the steps in the [quickstart](../../quickstart.md).
42+
43+
1. Create and publish a [Fabric data agent](https://go.microsoft.com/fwlink/?linkid=2312910)
44+
45+
1. You can add the Microsoft Fabric tool to an agent programatically using the code examples listed at the top of this article, or the Azure AI Foundry portal. If you want to use the portal, in the Create and debug screen for your agent, scroll down the Setup pane on the right to knowledge. Then select Add.
46+
:::image type="content" source="../../media/tools/knowledge-tools.png" alt-text="A screenshot showing the available tool categories in the Azure AI Foundry portal." lightbox="../../media/tools/knowledge-tools.png":::
47+
48+
1. Select **Microsoft Fabric** and follow the prompts to add the tool. You can add only one per agent.
49+
50+
1. Click to add new connections. Once you have added a connection, you can directly select from existing list.
51+
1. To create a new connection, you need to find `workspace-id` and `artifact-id` in your published Fabric data agent endpoint. Your Fabric data agent endpoint would look like `https://fabric.microsoft.com/groups/<workspace_id>/aiskills/<artifact-id>`
52+
53+
1. Then, you can add both to your connection. Make sure you have checked `is secret` for both of them
54+
55+
:::image type="content" source="../../media/tools/fabric-foundry.png" alt-text="A screenshot showing the fabric connection in the Azure AI Foundry portal." lightbox="../../media/tools/fabric-foundry.png":::
56+
57+
::: zone-end
58+
59+
::: zone pivot="code-example"
60+
## Step 1: Create a project client
61+
62+
Create a client object, which will contain the connection string for connecting to your AI project and other resources.
63+
64+
# [Python](#tab/python)
65+
66+
```python
67+
import os
68+
from azure.ai.projects import AIProjectClient
69+
from azure.identity import DefaultAzureCredential
70+
from azure.ai.projects.models import FabricTool
71+
```
72+
# [JavaScript](#tab/javascript)
73+
74+
```javascript
75+
const connectionString =
76+
process.env["AZURE_AI_PROJECTS_CONNECTION_STRING"] || "<project connection string>";
77+
78+
if (!connectionString) {
79+
throw new Error("AZURE_AI_PROJECTS_CONNECTION_STRING must be set.");
80+
}
81+
const client = AIProjectsClient.fromConnectionString(
82+
connectionString || "",
83+
new DefaultAzureCredential(),
84+
);
85+
```
86+
87+
# [REST API](#tab/rest)
88+
89+
>[!IMPORTANT]
90+
> This REST API allows developers to invoke the Grounding with Bing Search tool through the Azure AI Agent service. It does not send calls to the Grounding with Bing Search API directly.
91+
92+
Follow the [REST API Quickstart](../../quickstart.md?pivots=rest-api) to set the right values for the environment variables `AZURE_AI_AGENTS_TOKEN` and `AZURE_AI_AGENTS_ENDPOINT`. The client creation is demonstrated in the next section.
93+
94+
---
95+
96+
## Step 2: Create an agent with the Microsoft Fabric tool enabled
97+
98+
To make the Microsoft Fabric tool available to your agent, use a connection to initialize the tool and attach it to the agent. You can find your connection in the **connected resources** section of your project in the Azure AI Foundry portal.
99+
100+
# [Python](#tab/python)
101+
102+
```python
103+
# The Fabric connection id can be found in the Azure AI Foundry project as a property of the Fabric tool
104+
# Your connection id is in the format /subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-project-name>/connections/<your-fabric-connection-name>
105+
conn_id = "your-connection-id"
106+
107+
# Initialize agent fabric tool and add the connection id
108+
fabric = FabricTool(connection_id=conn_id)
109+
110+
# Create agent with the fabric tool and process agent run
111+
with project_client:
112+
agent = project_client.agents.create_agent(
113+
model="gpt-4o",
114+
name="my-assistant",
115+
instructions="You are a helpful assistant",
116+
tools=fabric.definitions,
117+
headers={"x-ms-enable-preview": "true"},
118+
)
119+
print(f"Created agent, ID: {agent.id}")
120+
```
121+
# [JavaScript](#tab/javascript)
122+
123+
```javascript
124+
const fabricConnection = await client.connections.getConnection("FABRICCONNECTIONNAME"
125+
);
126+
127+
const connectionId = fabricConnection.id;
128+
129+
// Initialize agent Microsoft Fabric tool with the connection id
130+
const fabricTool = ToolUtility.createFabricTool(connectionId);
131+
132+
// Create agent with the Microsoft Fabric tool and process assistant run
133+
const agent = await client.agents.createAgent("gpt-4o", {
134+
name: "my-agent",
135+
instructions: "You are a helpful agent",
136+
tools: [fabricTool.definition],
137+
toolResources: {}, // Add empty tool_resources which is required by the API
138+
});
139+
console.log(`Created agent, agent ID : ${agent.id}`);
140+
141+
```
142+
143+
# [REST API](#tab/rest)
144+
```console
145+
curl $AZURE_AI_AGENTS_ENDPOINT/assistants?api-version=2024-12-01-preview \
146+
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
147+
-H "Content-Type: application/json" \
148+
-d '{
149+
"instructions": "You are a helpful agent.",
150+
"name": "my-agent",
151+
"model": "gpt-4o",
152+
"tools": [
153+
{
154+
"type": "fabric_dataagent",
155+
"fabric_dataagent": {
156+
"connections": [
157+
{
158+
"connection_id": "/subscriptions/<your-subscription-id>/resourceGroups/<your-resource-group>/providers/Microsoft.MachineLearningServices/workspaces/<your-project-name>/connections/<your-fabric-connection-name>"
159+
}
160+
]
161+
}
162+
}
163+
]
164+
}'
165+
```
166+
---
167+
168+
## Step 3: Create a thread
169+
170+
# [Python](#tab/python)
171+
172+
```python
173+
# Create thread for communication
174+
thread = project_client.agents.create_thread()
175+
print(f"Created thread, ID: {thread.id}")
176+
177+
# Create message to thread
178+
# Remember to update the message with your data
179+
message = project_client.agents.create_message(
180+
thread_id=thread.id,
181+
role="user",
182+
content="what is top sold product in Contoso last month?",
183+
)
184+
print(f"Created message, ID: {message.id}")
185+
```
186+
# [JavaScript](#tab/javascript)
187+
188+
```javascript
189+
// create a thread
190+
const thread = await client.agents.createThread();
191+
192+
// add a message to thread
193+
await client.agents.createMessage(
194+
thread.id, {
195+
role: "user",
196+
content: "<Ask a question related to your Fabric data>",
197+
});
198+
```
199+
200+
# [REST API](#tab/rest)
201+
### Create a thread
202+
203+
```console
204+
curl $AZURE_AI_AGENTS_ENDPOINT/threads?api-version=2024-12-01-preview \
205+
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
206+
-H "Content-Type: application/json" \
207+
-d ''
208+
```
209+
210+
### Add a user question to the thread
211+
212+
```console
213+
curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
214+
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
215+
-H "Content-Type: application/json" \
216+
-d '{
217+
"role": "user",
218+
"content": "<question related to your data>"
219+
}'
220+
```
221+
222+
---
223+
224+
## Step 4: Create a run and check the output
225+
226+
Create a run and observe that the model uses the Fabric data agent tool to provide a response to the user's question.
227+
228+
# [Python](#tab/python)
229+
230+
```python
231+
# Create and process agent run in thread with tools
232+
run = project_client.agents.create_and_process_run(thread_id=thread.id, agent_id=agent.id)
233+
print(f"Run finished with status: {run.status}")
234+
235+
if run.status == "failed":
236+
print(f"Run failed: {run.last_error}")
237+
238+
# Delete the assistant when done
239+
project_client.agents.delete_agent(agent.id)
240+
print("Deleted agent")
241+
242+
# Fetch and log all messages
243+
messages = project_client.agents.list_messages(thread_id=thread.id)
244+
print(f"Messages: {messages}")
245+
```
246+
247+
# [JavaScript](#tab/javascript)
248+
249+
```javascript
250+
251+
// create a run
252+
const streamEventMessages = await client.agents.createRun(thread.id, agent.id).stream();
253+
254+
for await (const eventMessage of streamEventMessages) {
255+
switch (eventMessage.event) {
256+
case RunStreamEvent.ThreadRunCreated:
257+
break;
258+
case MessageStreamEvent.ThreadMessageDelta:
259+
{
260+
const messageDelta = eventMessage.data;
261+
messageDelta.delta.content.forEach((contentPart) => {
262+
if (contentPart.type === "text") {
263+
const textContent = contentPart;
264+
const textValue = textContent.text?.value || "No text";
265+
}
266+
});
267+
}
268+
break;
269+
270+
case RunStreamEvent.ThreadRunCompleted:
271+
break;
272+
case ErrorEvent.Error:
273+
console.log(`An error occurred. Data ${eventMessage.data}`);
274+
break;
275+
case DoneEvent.Done:
276+
break;
277+
}
278+
}
279+
280+
// Print the messages from the agent
281+
const messages = await client.agents.listMessages(thread.id);
282+
283+
// Messages iterate from oldest to newest
284+
// messages[0] is the most recent
285+
for (let i = messages.data.length - 1; i >= 0; i--) {
286+
const m = messages.data[i];
287+
if (isOutputOfType<MessageTextContentOutput>(m.content[0], "text")) {
288+
const textContent = m.content[0];
289+
console.log(`${textContent.text.value}`);
290+
console.log(`---------------------------------`);
291+
}
292+
}
293+
```
294+
295+
296+
# [REST API](#tab/rest)
297+
### Run the thread
298+
299+
```console
300+
curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs?api-version=2024-12-01-preview \
301+
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN" \
302+
-H "Content-Type: application/json" \
303+
-d '{
304+
"assistant_id": "asst_abc123",
305+
}'
306+
```
307+
308+
### Retrieve the status of the run
309+
310+
```console
311+
curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/runs/run_abc123?api-version=2024-12-01-preview \
312+
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"
313+
```
314+
315+
### Retrieve the agent response
316+
317+
```console
318+
curl $AZURE_AI_AGENTS_ENDPOINT/threads/thread_abc123/messages?api-version=2024-12-01-preview \
319+
-H "Authorization: Bearer $AZURE_AI_AGENTS_TOKEN"
320+
```
321+
322+
---
323+
324+
::: zone-end
325+
326+
## Next steps
327+
328+
[See the full sample for Fabric data agent.](https://github.com/Azure/azure-sdk-for-python/blob/main/sdk/ai/azure-ai-projects/samples/agents/sample_agents_fabric.py)

‎articles/ai-services/agents/media/tools/fabric-foundry.png

105 KB
Loading

‎articles/ai-services/agents/toc.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,8 @@ items:
3434
href: how-to/tools/file-search.md
3535
- name: Azure AI Search
3636
href: how-to/tools/azure-ai-search.md
37+
- name: Microsoft Fabric
38+
href: how-to/tools/fabric.md
3739
- name: Action tools
3840
items:
3941
- name: Function calling

‎articles/ai-services/agents/whats-new.md

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,12 @@ ms.custom: azure-ai-agents
1515

1616
This article provides a summary of the latest releases and major documentation updates for Azure AI Agent Service.
1717

18+
## March 2025
19+
20+
### Microsoft Fabric tool
21+
22+
The Microsoft Fabric tool is now available for the Azure AI Agent Service, allowing users to interact with data you have in Microsoft Fabric through chat and uncover data-driven and actionable insights. See the [how-to article](./how-to/tools/fabric.md) for more information.
23+
1824
## February 2025
1925

2026
### Use Azure AI Agent Service in the Azure AI Foundry portal

‎zone-pivots/zone-pivot-groups.yml

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1030,6 +1030,15 @@ groups:
10301030
title: Code examples
10311031
- id: supported-filetypes
10321032
title: Supported file types
1033+
# owner: aahi
1034+
- id: selection-fabric-data-agent
1035+
title: Selections
1036+
prompt: What would you like to see?
1037+
pivots:
1038+
- id: overview
1039+
title: Overview
1040+
- id: code-example
1041+
title: Code examples
10331042
# owner: fosteramanda
10341043
- id: selection-file-search
10351044
title: Selections

0 commit comments

Comments
 (0)