Update Bing Grounding Sample

Author: Peter Hauge

doc-samples/agents/c#/azure-ai-agent-sdk/Sample4_PersistentAgents_Bing_Grounding.md

@@ -0,0 +1,199 @@
+# Sample for use of an agent with Bing grounding in Azure.AI.Agents.
+
+To enable your Agent to perform search through Bing search API, you use `BingGroundingToolDefinition` along with a connection.
+1. First we need to create an agent and read the environment variables, which will be used in the next steps.
+
+```C# Snippet:AgentsBingGrounding_CreateProject
+
+// Get Connection information from Environment Variables
+// To use App Config instead:  https://learn.microsoft.com/en-us/visualstudio/ide/managing-application-settings-dotnet
+var projectEndpoint = System.Environment.GetEnvironmentVariable("PROJECT_ENDPOINT");
+var modelDeploymentName = System.Environment.GetEnvironmentVariable("MODEL_DEPLOYMENT_NAME");
+var connectionId = System.Environment.GetEnvironmentVariable("AZURE_BING_CONECTION_ID");
+
+// Create the Agent Client
+PersistentAgentsClient agentClient = new(projectEndpoint, new DefaultAzureCredential());
+```
+
+2. We will use the Bing connection ID to initialize the `BingGroundingToolDefinition`.
+
+```C# Snippet:AgentsBingGrounding_GetConnection
+ToolConnectionList connectionList = new()
+{
+    ConnectionList = { new ToolConnection(bingConnectionId) }
+};
+BingGroundingToolDefinition bingGroundingTool = new(connectionList);
+```
+
+3. We will use the `BingGroundingToolDefinition` during the agent initialization.
+
+Synchronous sample:
+```C# Snippet:AgentsBingGrounding_CreateAgent
+// Create the Agent
+PersistentAgent agent = agentClient.CreateAgent(
+   model: modelDeploymentName,
+   name: "my-agent",
+   instructions: "You are a helpful agent.",
+   tools: [bingGroundingTool]);
+```
+
+Asynchronous sample:
+```C# Snippet:AgentsBingGroundingAsync_CreateAgent
+// Create the Agent
+PersistentAgent agent = await agentClient.CreateAgentAsync(
+   model: modelDeploymentName,
+   name: "my-agent",
+   instructions: "You are a helpful agent.",
+   tools: [ bingGroundingTool ]);
+```
+
+4. Now we will create the thread, add the message , containing a question for agent and start the run.
+
+Synchronous sample:
+```C# Snippet:AgentsBingGrounding_CreateThreadMessage
+PersistentAgentThread thread = agentClient.CreateThread();
+
+// Create message and run the agent
+ThreadMessage message = agentClient.CreateMessage(
+    thread.Id,
+    MessageRole.User,
+    "How does wikipedia explain Euler's Identity?");
+ThreadRun run = agentClient.CreateRun(thread, agent);
+
+// Wait for the agent to finish running
+do
+{
+    Thread.Sleep(TimeSpan.FromMilliseconds(500));
+    run = agentClient.GetRun(thread.Id, run.Id);
+}
+while (run.Status == RunStatus.Queued
+    || run.Status == RunStatus.InProgress);
+
+// Confirm that the run completed successfully
+if (run.Status != RunStatus.Completed)
+{
+    throw new Exception("Run did not complete successfully, error: " + run.LastError?.Message);
+}
+
+```
+
+Asynchronous sample:
+```C# Snippet:AgentsBingGroundingAsync_CreateThreadMessage
+PersistentAgentThread thread = await agentClient.CreateThreadAsync();
+
+// Create message and run the agent
+ThreadMessage message = await agentClient.CreateMessageAsync(
+    thread.Id,
+    MessageRole.User,
+    "How does wikipedia explain Euler's Identity?");
+ThreadRun run = await agentClient.CreateRunAsync(thread, agent);
+
+// Wait for the agent to finish running
+do
+{
+    await Task.Delay(TimeSpan.FromMilliseconds(500));
+    run = await agentClient.GetRunAsync(thread.Id, run.Id);
+}
+while (run.Status == RunStatus.Queued
+    || run.Status == RunStatus.InProgress);
+
+// Confirm that the run completed successfully
+if (run.Status != RunStatus.Completed)
+{
+    throw new Exception("Run did not complete successfully, error: " + run.LastError?.Message);
+}
+
+```
+
+5. Print the agent messages to console in chronological order.
+
+Synchronous sample:
+```C# Snippet:AgentsBingGrounding_Print
+PageableList<ThreadMessage> messages = agentClient.GetMessages(
+    threadId: thread.Id,
+    order: ListSortOrder.Ascending
+);
+
+foreach (ThreadMessage threadMessage in messages)
+{
+    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
+    foreach (MessageContent contentItem in threadMessage.ContentItems)
+    {
+        if (contentItem is MessageTextContent textItem)
+        {
+            string response = textItem.Text;
+            if (textItem.Annotations != null)
+            {
+                foreach (MessageTextAnnotation annotation in textItem.Annotations)
+                {
+                    if (annotation is MessageTextUrlCitationAnnotation urlAnnotation)
+                    {
+                        response = response.Replace(urlAnnotation.Text, $" [{urlAnnotation.UrlCitation.Title}]({urlAnnotation.UrlCitation.Url})");
+                    }
+                }
+            }
+            Console.Write($"Agent response: {response}");
+        }
+        else if (contentItem is MessageImageFileContent imageFileItem)
+        {
+            Console.Write($"<image from ID: {imageFileItem.FileId}");
+        }
+        Console.WriteLine();
+    }
+}
+```
+
+Asynchronous sample:
+```C# Snippet:AgentsBingGroundingAsync_Print
+PageableList<ThreadMessage> messages = await agentClient.GetMessagesAsync(
+    threadId: thread.Id,
+    order: ListSortOrder.Ascending
+);
+
+foreach (ThreadMessage threadMessage in messages)
+{
+    Console.Write($"{threadMessage.CreatedAt:yyyy-MM-dd HH:mm:ss} - {threadMessage.Role,10}: ");
+
+    foreach (MessageContent contentItem in threadMessage.ContentItems)
+    {
+        if (contentItem is MessageTextContent textItem)
+        {
+            string response = textItem.Text;
+
+            // If we have Text URL citation annotations, reformat the response to show title & URL for citations
+            if (textItem.Annotations != null)
+            {
+                foreach (MessageTextAnnotation annotation in textItem.Annotations)
+                {
+                    if (annotation is MessageTextUrlCitationAnnotation urlAnnotation)
+                    {
+                        response = response.Replace(urlAnnotation.Text, $" [{urlAnnotation.UrlCitation.Title}]({urlAnnotation.UrlCitation.Url})");
+                    }
+                }
+            }
+            Console.Write($"Agent response: {response}");
+        }
+        else if (contentItem is MessageImageFileContent imageFileItem)
+        {
+            Console.Write($"<image from ID: {imageFileItem.FileId}");
+        }
+        Console.WriteLine();
+    }
+}
+```
+
+6. Clean up resources by deleting thread and agent.
+
+Synchronous sample:
+```C# Snippet:AgentsBingGroundingCleanup
+// Delete thread and agent
+agentClient.DeleteThread(threadId: thread.Id);
+agentClient.DeleteAgent(agentId: agent.Id);
+```
+
+Asynchronous sample:
+```C# Snippet:AgentsBingGroundingCleanupAsync
+// Delete thread and agent
+await agentClient.DeleteThreadAsync(threadId: thread.Id);
+await agentClient.DeleteAgentAsync(agentId: agent.Id);
+```