Skip to content

Commit 20c07d5

Browse files
nick863nick863
authored
Add A2A and Microsoft Fabric samples. (#54439)
* Add A2A and Microsoft Fabric samples. * Fix links
1 parent fb06b55 commit 20c07d5

File tree

12 files changed

+622
-9
lines changed

12 files changed

+622
-9
lines changed

‎sdk/ai/Azure.AI.Projects.OpenAI/README.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -38,7 +38,19 @@ Develop Agents using the Azure AI Foundry platform, leveraging an extensive ecos
3838
- [OpenAPI tool](#openapi-tool)
3939
- [OpenAPI tool with project connection](#openapi-tool-project-connection)
4040
- [Browser automation](#browser-automation)
41+
- [Create Azure Playwright workspace](#create-azure-playwright-workspace)
42+
- [Configure Microsoft Foundry](#configure-microsoft-foundry)
43+
- [Using Browser automation tool](#using-browser-automation-tool)
4144
- [SharePoint tool](#sharepoint-tool)
45+
- [Fabric Data Agent tool](#fabric-data-agent-tool)
46+
- [Create a Fabric Capacity](#create-a-fabric-capacity)
47+
- [Create a Lakehouse data repository](#create-a-lakehouse-data-repository)
48+
- [Add a data agent to the Fabric](#add-a-data-agent-to-the-fabric)
49+
- [Create a Fabric connection in Microsoft Foundry](#create-a-fabric-connection-in-microsoft-foundry)
50+
- [Using Microsoft Fabric tool](#using-microsoft-fabric-tool)
51+
- [A2ATool](#a2atool)
52+
- [Create a connection to A2A agent](#create-a-connection-to-a2a-agent)
53+
- [Using A2A Tool](#using-a2a-tool)
4254
- [Tracing](#tracing)
4355
- [Tracing to Azure Monitor](#tracing-to-azure-monitor)
4456
- [Tracing to Console](#tracing-to-console)
@@ -1112,6 +1124,8 @@ Playwright is a Node.js library for browser automation. Microsoft provides the [
11121124
4. Provide a name, then paste your Access Token into the **Key** field.
11131125
5. Set the Playwright Workspace Browser endpoint as the **Target URI**. You can find this endpoint on the Workspace **Overview page**. It begins with `wss://`.
11141126

1127+
### Using Browser automation tool
1128+
11151129
Please note that Browser automation operations may take longer than typical calls to process. Using background mode for Responses or applying a network timeout of at least five minutes for non-background calls is highly recommended.
11161130

11171131
```C# Snippet:Sample_CreateProjectClient_BrowserAutomotion
@@ -1229,6 +1243,99 @@ Assert.That(response.Status, Is.EqualTo(ResponseStatus.Completed));
12291243
Console.WriteLine($"{response.GetOutputText()}{GetFormattedAnnotation(response)}");
12301244
```
12311245

1246+
## Fabric Data Agent tool
1247+
1248+
As a prerequisite to this example, we will need to create Microsoft Fabric with Lakehouse data repository. Please see the end-to end tutorials on using Microsoft Fabric [here](https://learn.microsoft.com/fabric/fundamentals/end-to-end-tutorials) for more information.
1249+
1250+
### Create a Fabric Capacity
1251+
1252+
1. Create a **Fabric Capacity** resource in the Azure Portal **(attention, the rate is being applied!)**.
1253+
2. Create the workspace in [Power BI portal](https://msit.powerbi.com/home) by clicking **Workspaces** icon on the left panel.
1254+
3. At the bottom click **+ New workspace**.
1255+
4. At the right panel populate the name of a workspace, select **Fabric capacity** as a **License mode**; in the **Capacity** dropdown select Fabric Capacity resource we have just created.
1256+
5. Click **Apply**.
1257+
1258+
### Create a Lakehouse data repository
1259+
1260+
1. Click a **Lakehouse** icon in **Other items you can create with Microsoft Fabric** section and name the new data repository.
1261+
2. Download the [public holidays data set](https://github.com/microsoft/fabric-samples/raw/refs/heads/main/docs-samples/data-engineering/Lakehouse/PublicholidaysSample/publicHolidays.parquet).
1262+
3. At the Lakehouse menu select **Get data > Upload files** and upload the `publicHolidays.parquet`.
1263+
4. In the **Files** section, click on three dots next to uploaded file and click **Load to Tables > new table** and then **Load** in the opened window.
1264+
5. Delete the uploaded file, by clicking three dots and selecting **Delete**.
1265+
1266+
### Add a data agent to the Fabric
1267+
1268+
1. At the top panel select **Add to data agent > New data agent** and name the newly created Agent.
1269+
2. In the open view on the left panel select the Lakehouse "publicholidays" table and set a checkbox next to it.
1270+
4. Ask the question we will further use in the Requests API. "What was the number of public holidays in Norway in 2024?"
1271+
5. The Agent should show a table containing one column called "NumberOfPublicHolidays" with the single row, containing number 62.
1272+
6. Click **Publish** and in the description add "Agent has data about public holidays." If this stage was omitted the error, saying "Stage configuration not found." will be returned during sample run.
1273+
1274+
### Create a Fabric connection in Microsoft Foundry.
1275+
1276+
After we have created the Fabric data Agent, we can connect fabric to our Microsoft Foundry.
1277+
1. Open the [Power BI](https://msit.powerbi.com/home) and select the workspace we have created.
1278+
2. In the open view select the Agent we have created.
1279+
3. The URL of the opened page will look like `https://msit.powerbi.com/groups/%workspace_id%/aiskills/%artifact_id%?experience=power-bi`, where `workspace_id` and `artifact_id` are GUIDs in a form like `811acded-d5f7-11f0-90a4-04d3b0c6010a`.
1280+
4. In the **Microsoft Foundry** you are using for the experimentation, on the left panel select **Management center**.
1281+
5. Choose **Connected resources**.
1282+
6. Create a new connection of type **Microsoft Fabric**.
1283+
7. Populate **workspace-id** and **artifact-id** fields with GUIDs found in the Microsoft Data Agent URL and name the new connection.
1284+
1285+
### Using Microsoft Fabric tool
1286+
1287+
To use the Agent with Microsoft Fabric tool, we need to include `MicrosoftFabricAgentTool` into `PromptAgentDefinition`.
1288+
1289+
```C# Snippet:Sample_CreateAgent_Fabric_Async
1290+
AIProjectConnection fabricConnection = await projectClient.Connections.GetConnectionAsync(fabricConnectionName);
1291+
FabricDataAgentToolOptions fabricToolOption = new()
1292+
{
1293+
ProjectConnections = { new ToolProjectConnection(projectConnectionId: fabricConnection.Id) }
1294+
};
1295+
PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
1296+
{
1297+
Instructions = "You are a helpful assistant.",
1298+
Tools = { new MicrosoftFabricAgentTool(fabricToolOption), }
1299+
};
1300+
AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync(
1301+
agentName: "myAgent",
1302+
options: new(agentDefinition));
1303+
```
1304+
1305+
## A2ATool
1306+
1307+
The [A2A or Agent2Agent](https://a2a-protocol.org/latest/) protocol is designed to enable seamless communication between agents. In the scenario below we assume that we have the application endpoint, which complies with A2A; the authentication is happening through header `x-api-key` value.
1308+
1309+
### Create a connection to A2A agent
1310+
1311+
1. In the **Microsoft Foundry** you are using for the experimentation, on the left panel select **Management center**.
1312+
2. Choose **Connected resources**.
1313+
3. Create a new connection of type **Custom keys**.
1314+
4. Add two key-value pairs:
1315+
* x-api-key: \<your key\>
1316+
* type: custom_A2A
1317+
5. Name and save the connection.
1318+
1319+
### Using A2A Tool
1320+
1321+
To use the Agent with A2A tool, we need to include `A2ATool` into `PromptAgentDefinition`.
1322+
1323+
```C# Snippet:Sample_CreateAgent_AgentToAgent_Async
1324+
AIProjectConnection a2aConnection = projectClient.Connections.GetConnection(a2aConnectionName);
1325+
A2ATool a2aTool = new(baseUri: new Uri(a2aBaseUri))
1326+
{
1327+
ProjectConnectionId = a2aConnection.Id
1328+
};
1329+
PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
1330+
{
1331+
Instructions = "You are a helpful assistant.",
1332+
Tools = { a2aTool }
1333+
};
1334+
AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync(
1335+
agentName: "myAgent",
1336+
options: new(agentDefinition));
1337+
```
1338+
12321339
## Tracing
12331340
**Note:** The tracing functionality is currently in preview with limited scope. Only agent creation operations generate dedicated gen_ai traces currently. As a preview feature, the trace structure including spans, attributes, and events may change in future releases.
12341341

‎sdk/ai/Azure.AI.Projects.OpenAI/samples/Sample23_BrowserAutomationTool.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Playwright is a Node.js library for browser automation. Microsoft provides the [
1010

1111
## Configure Microsoft Foundry
1212

13-
1. Open the left navigation and select **Management center**.
13+
1. On the left panel select **Management center**.
1414
2. Choose **Connected resources**.
1515
3. Create a new connection of type **Serverless Model**.
1616
4. Provide a name, then paste your Access Token into the **Key** field.

‎sdk/ai/Azure.AI.Projects.OpenAI/samples/Sample24_Sharepoint.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -102,7 +102,7 @@ Console.WriteLine($"{response.GetOutputText()}{GetFormattedAnnotation(response)}
102102
```
103103

104104

105-
6. Clean up resources by deleting thread and agent.
105+
6. After the sample is completed, delete the Agent we have created.
106106

107107
Synchronous sample:
108108
```C# Snippet:Sample_Cleanup_Sharepoint_Sync

‎sdk/ai/Azure.AI.Projects.OpenAI/samples/Sample25_FabricDataAgent.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Sample for use of an Agent with Fabric Data Agent in Azure.AI.Projets.OpenAI.
2+
3+
As a prerequisite to this example, we will need to create Microsoft Fabric with Lakehouse data repository. Please see the end-to end tutorials on using Microsoft Fabric [here](https://learn.microsoft.com/fabric/fundamentals/end-to-end-tutorials) for more information.
4+
5+
## Create a Fabric Capacity
6+
7+
1. Create a **Fabric Capacity** resource in the Azure Portal **(attention, the rate is being applied!)**.
8+
2. Create the workspace in [Power BI portal](https://msit.powerbi.com/home) by clicking **Workspaces** icon on the left panel.
9+
3. At the bottom click **+ New workspace**.
10+
4. At the right panel populate the name of a workspace, select **Fabric capacity** as a **License mode**; in the **Capacity** dropdown select Fabric Capacity resource we have just created.
11+
5. Click **Apply**.
12+
13+
## Create a Lakehouse data repository
14+
15+
1. Click a **Lakehouse** icon in **Other items you can create with Microsoft Fabric** section and name the new data repository.
16+
2. Download the [public holidays data set](https://github.com/microsoft/fabric-samples/raw/refs/heads/main/docs-samples/data-engineering/Lakehouse/PublicholidaysSample/publicHolidays.parquet).
17+
3. At the Lakehouse menu select **Get data > Upload files** and upload the `publicHolidays.parquet`.
18+
4. In the **Files** section, click on three dots next to uploaded file and click **Load to Tables > new table** and then **Load** in the opened window.
19+
5. Delete the uploaded file, by clicking three dots and selecting **Delete**.
20+
21+
## Add a data agent to the Fabric
22+
23+
1. At the top panel select **Add to data agent > New data agent** and name the newly created Agent.
24+
2. In the open view on the left panel select the Lakehouse "publicholidays" table and set a checkbox next to it.
25+
4. Ask the question we will further use in the Requests API. "What was the number of public holidays in Norway in 2024?"
26+
5. The Agent should show a table containing one column called "NumberOfPublicHolidays" with the single row, containing number 62.
27+
6. Click **Publish** and in the description add "Agent has data about public holidays." If this stage was omitted the error, saying "Stage configuration not found." will be returned during sample run.
28+
29+
## Create a Fabric connection in Microsoft Foundry
30+
31+
After we have created the Fabric data Agent, we can connect fabric to our Microsoft Foundry.
32+
1. Open the [Power BI](https://msit.powerbi.com/home) and select the workspace we have created.
33+
2. In the open view select the Agent we have created.
34+
3. The URL of the opened page will look like `https://msit.powerbi.com/groups/%workspace_id%/aiskills/%artifact_id%?experience=power-bi`, where `workspace_id` and `artifact_id` are GUIDs in a form like `811acded-d5f7-11f0-90a4-04d3b0c6010a`.
35+
4. In the **Microsoft Foundry** you are using for the experimentation, on the left panel select **Management center**.
36+
5. Choose **Connected resources**.
37+
6. Create a new connection of type **Microsoft Fabric**.
38+
7. Populate **workspace-id** and **artifact-id** fields with GUIDs found in the Microsoft Data Agent URL and name the new connection.
39+
40+
41+
## Run the sample
42+
43+
To enable your Agent to access Microsoft Fabric Data Agent, use `MicrosoftFabricAgentTool`.
44+
45+
1. First, create an Agent client and read the environment variables, which will be used in the next steps.
46+
47+
```C# Snippet:Sample_CreateAgentClient_Fabric
48+
var projectEndpoint = System.Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
49+
var modelDeploymentName = System.Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME");
50+
var fabricConnectionName = System.Environment.GetEnvironmentVariable("FABRIC_CONNECTION_NAME");
51+
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());
52+
```
53+
54+
2. Use the Microsoft Fabric connection name as it is shown in the connections section of Microsoft Foundry to get the connection. Get the connection ID to initialize the `FabricDataAgentToolOptions`, which will be used to create `MicrosoftFabricAgentTool`.
55+
56+
Synchronous sample:
57+
```C# Snippet:Sample_CreateAgent_Fabric_Sync
58+
AIProjectConnection fabricConnection = projectClient.Connections.GetConnection(fabricConnectionName);
59+
FabricDataAgentToolOptions fabricToolOption = new()
60+
{
61+
ProjectConnections = { new ToolProjectConnection(projectConnectionId: fabricConnection.Id) }
62+
};
63+
PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
64+
{
65+
Instructions = "You are a helpful assistant.",
66+
Tools = { new MicrosoftFabricAgentTool(fabricToolOption), }
67+
};
68+
AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
69+
agentName: "myAgent",
70+
options: new(agentDefinition));
71+
```
72+
73+
Asynchronous sample:
74+
```C# Snippet:Sample_CreateAgent_Fabric_Async
75+
AIProjectConnection fabricConnection = await projectClient.Connections.GetConnectionAsync(fabricConnectionName);
76+
FabricDataAgentToolOptions fabricToolOption = new()
77+
{
78+
ProjectConnections = { new ToolProjectConnection(projectConnectionId: fabricConnection.Id) }
79+
};
80+
PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
81+
{
82+
Instructions = "You are a helpful assistant.",
83+
Tools = { new MicrosoftFabricAgentTool(fabricToolOption), }
84+
};
85+
AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync(
86+
agentName: "myAgent",
87+
options: new(agentDefinition));
88+
```
89+
90+
3. Create the response and make sure we are always using tool.
91+
92+
Synchronous sample:
93+
```C# Snippet:Sample_CreateResponse_Fabric_Sync
94+
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);
95+
ResponseCreationOptions responseOptions = new()
96+
{
97+
ToolChoice = ResponseToolChoice.CreateRequiredChoice()
98+
};
99+
OpenAIResponse response = responseClient.CreateResponse("What was the number of public holidays in Norway in 2024?", options: responseOptions);
100+
```
101+
102+
Asynchronous sample:
103+
```C# Snippet:Sample_CreateResponse_Fabric_Async
104+
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);
105+
ResponseCreationOptions responseOptions = new()
106+
{
107+
ToolChoice = ResponseToolChoice.CreateRequiredChoice()
108+
};
109+
OpenAIResponse response = await responseClient.CreateResponseAsync("What was the number of public holidays in Norway in 2024?", options: responseOptions);
110+
```
111+
112+
4. Print the Agent output.
113+
114+
```C# Snippet:Sample_WaitForResponse_Fabric
115+
Assert.That(response.Status, Is.EqualTo(ResponseStatus.Completed));
116+
Console.WriteLine(response.GetOutputText());
117+
```
118+
119+
120+
5. After the sample is completed, delete the Agent we have created.
121+
122+
Synchronous sample:
123+
```C# Snippet:Sample_Cleanup_Fabric_Sync
124+
projectClient.Agents.DeleteAgentVersion(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
125+
```
126+
127+
Asynchronous sample:
128+
```C# Snippet:Sample_Cleanup_Fabric_Async
129+
await projectClient.Agents.DeleteAgentVersionAsync(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
130+
```

‎sdk/ai/Azure.AI.Projects.OpenAI/samples/Sample26_A2A.md‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
# Sample for use of an Agent with Fabric Data Agent in Azure.AI.Projets.OpenAI.
2+
3+
The [A2A or Agent2Agent](https://a2a-protocol.org/latest/) protocol is designed to enable seamless communication between agents. In the scenario below we assume that we have the application endpoint, which complies with A2A; the authentication is happening through header `x-api-key` value.
4+
5+
## Create a connection to A2A agent
6+
7+
1. In the **Microsoft Foundry** you are using for the experimentation, on the left panel select **Management center**.
8+
2. Choose **Connected resources**.
9+
3. Create a new connection of type **Custom keys**.
10+
4. Add two key-value pairs:
11+
* x-api-key: \<your key\>
12+
* type: custom_A2A
13+
5. Name and save the connection.
14+
15+
16+
## Run the sample
17+
18+
To enable your Agent communication to the A2A endpoint, use `A2ATool`.
19+
20+
1. First, create an Agent client and read the environment variables, which will be used in the next steps.
21+
22+
```C# Snippet:Sample_CreateAgentClient_AgentToAgent
23+
var projectEndpoint = System.Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
24+
var modelDeploymentName = System.Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME");
25+
var a2aConnectionName = System.Environment.GetEnvironmentVariable("A2A_CONNECTION_NAME");
26+
var a2aBaseUri = System.Environment.GetEnvironmentVariable("A2A_BASE_URI");
27+
28+
AIProjectClient projectClient = new(endpoint: new Uri(projectEndpoint), tokenProvider: new DefaultAzureCredential());
29+
```
30+
31+
2. Create the `A2ATool` and provide it with the A2A connection ID and service endpoint as a `baseUri` parameter.
32+
33+
Synchronous sample:
34+
```C# Snippet:Sample_CreateAgent_AgentToAgent_Sync
35+
AIProjectConnection a2aConnection = projectClient.Connections.GetConnection(a2aConnectionName);
36+
A2ATool a2aTool = new(baseUri: new Uri(a2aBaseUri))
37+
{
38+
ProjectConnectionId = a2aConnection.Id
39+
};
40+
PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
41+
{
42+
Instructions = "You are a helpful assistant.",
43+
Tools = { a2aTool }
44+
};
45+
AgentVersion agentVersion = projectClient.Agents.CreateAgentVersion(
46+
agentName: "myAgent",
47+
options: new(agentDefinition));
48+
```
49+
50+
Asynchronous sample:
51+
```C# Snippet:Sample_CreateAgent_AgentToAgent_Async
52+
AIProjectConnection a2aConnection = projectClient.Connections.GetConnection(a2aConnectionName);
53+
A2ATool a2aTool = new(baseUri: new Uri(a2aBaseUri))
54+
{
55+
ProjectConnectionId = a2aConnection.Id
56+
};
57+
PromptAgentDefinition agentDefinition = new(model: modelDeploymentName)
58+
{
59+
Instructions = "You are a helpful assistant.",
60+
Tools = { a2aTool }
61+
};
62+
AgentVersion agentVersion = await projectClient.Agents.CreateAgentVersionAsync(
63+
agentName: "myAgent",
64+
options: new(agentDefinition));
65+
```
66+
67+
3. Create the response and make sure we are always using tool.
68+
69+
Synchronous sample:
70+
```C# Snippet:Sample_CreateResponse_AgentToAgent_Sync
71+
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);
72+
ResponseCreationOptions responseOptions = new()
73+
{
74+
ToolChoice = ResponseToolChoice.CreateRequiredChoice()
75+
};
76+
OpenAIResponse response = responseClient.CreateResponse("What can the secondary agent do?", options: responseOptions);
77+
```
78+
79+
Asynchronous sample:
80+
```C# Snippet:Sample_CreateResponse_AgentToAgent_Async
81+
ProjectResponsesClient responseClient = projectClient.OpenAI.GetProjectResponsesClientForAgent(agentVersion.Name);
82+
ResponseCreationOptions responseOptions = new()
83+
{
84+
ToolChoice = ResponseToolChoice.CreateRequiredChoice()
85+
};
86+
OpenAIResponse response = await responseClient.CreateResponseAsync("What can the secondary agent do?", options: responseOptions);
87+
```
88+
89+
4. Print the Agent output.
90+
91+
```C# Snippet:Sample_WaitForResponse_AgentToAgent
92+
Assert.That(response.Status, Is.EqualTo(ResponseStatus.Completed));
93+
Console.WriteLine(response.GetOutputText());
94+
```
95+
96+
97+
5. After the sample is completed, delete the Agent we have created.
98+
99+
Synchronous sample:
100+
```C# Snippet:Sample_Cleanup_AgentToAgent_Sync
101+
projectClient.Agents.DeleteAgentVersionAsync(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
102+
```
103+
104+
Asynchronous sample:
105+
```C# Snippet:Sample_Cleanup_AgentToAgent_Async
106+
await projectClient.Agents.DeleteAgentVersionAsync(agentName: agentVersion.Name, agentVersion: agentVersion.Version);
107+
```

0 commit comments

Comments
 (0)