Merge pull request #1832 from aahill/agents

updating tool docs

Author: Jill Grant

articles/ai-services/agents/how-to/tools/bing-grounding.md

@@ -112,99 +112,13 @@ Your use of Grounding with Bing Search will be governed by the Terms of Use. By
 
 ::: zone-end
 
-::: zone pivot="csharp-example"
+::: zone pivot="code-example"
 
-```csharp
-using System;
-using System.Collections.Generic;
-using System.Threading.Tasks;
-using Azure.Core;
-using Azure.Core.TestFramework;
-using NUnit.Framework;
-
-namespace Azure.AI.Projects.Tests;
-
-public partial class Sample_Agent_Bing_Grounding : SamplesBase<AIProjectsTestEnvironment>
-{
-    [Test]
-    public async Task BingGroundingExample()
-    {
-        var connectionString = TestEnvironment.AzureAICONNECTIONSTRING;
-
-        var clientOptions = new AIProjectClientOptions();
-
-        // Adding the custom headers policy
-        clientOptions.AddPolicy(new CustomHeadersPolicy(), HttpPipelinePosition.PerCall);
-        var projectClient = new AIProjectClient(connectionString, new DefaultAzureCredential(), clientOptions);
-
-        GetConnectionResponse bingConnection = await projectClient.GetConnectionsClient().GetConnectionAsync(TestEnvironment.BINGCONNECTIONNAME);
-        var connectionId = bingConnection.Id;
-
-        AgentsClient agentClient = projectClient.GetAgentsClient();
-
-        ToolConnectionList connectionList = new ToolConnectionList
-        {
-            ConnectionList = { new ToolConnection(connectionId) }
-        };
-        BingGroundingToolDefinition bingGroundingTool = new BingGroundingToolDefinition(connectionList);
-
-        Response<Agent> agentResponse = await agentClient.CreateAgentAsync(
-           model: "gpt-4-1106-preview",
-           name: "my-assistant",
-           instructions: "You are a helpful assistant.",
-           tools: new List<ToolDefinition> { bingGroundingTool });
-        Agent agent = agentResponse.Value;
-
-        // Create thread for communication
-        Response<AgentThread> threadResponse = await agentClient.CreateThreadAsync();
-        AgentThread thread = threadResponse.Value;
-
-        // Create message to thread
-        Response<ThreadMessage> messageResponse = await agentClient.CreateMessageAsync(
-            thread.Id,
-            MessageRole.User,
-            "How does wikipedia explain Euler's Identity?");
-        ThreadMessage message = messageResponse.Value;
-
-        // Run the agent
-        Response<ThreadRun> runResponse = await agentClient.CreateRunAsync(thread, agent);
-
-        do
-        {
-            await Task.Delay(TimeSpan.FromMilliseconds(500));
-            runResponse = await agentClient.GetRunAsync(thread.Id, runResponse.Value.Id);
-        }
-        while (runResponse.Value.Status == RunStatus.Queued
-            || runResponse.Value.Status == RunStatus.InProgress);
-
-        Response<PageableList<ThreadMessage>> afterRunMessagesResponse
-            = await agentClient.GetMessagesAsync(thread.Id);
-        IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;
-
-        // Note: messages iterate from newest to oldest, with the messages[0] being the most recent
-        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)
-                {
-                    Console.Write(textItem.Text);
-                }
-                else if (contentItem is MessageImageFileContent imageFileItem)
-                {
-                    Console.Write($"<image from ID: {imageFileItem.FileId}");
-                }
-                Console.WriteLine();
-            }
-        }
-    }
-}
-```
-::: zone-end
+## Step 1: Create an agent with bing grounding
 
-::: zone pivot="python-example"
+Create a client object, which will contain the connection string for connecting to your AI project and other resources.
 
+# [Python](#tab/python)
 
 ```python
 import os
@@ -213,15 +127,45 @@ from azure.identity import DefaultAzureCredential
 from azure.ai.projects.models import BingGroundingTool
 
 
-# Create an Azure AI Client from a connection string, copied from your Azure AI project.
+# Create an Azure AI Client from a connection string, copied from your AI Studio project.
 # At the moment, it should be in the format "<HostName>;<AzureSubscriptionId>;<ResourceGroup>;<HubName>"
 # Customer needs to login to Azure subscription via Azure CLI and set the environment variables
 
 project_client = AIProjectClient.from_connection_string(
     credential=DefaultAzureCredential(),
     conn_str=os.environ["PROJECT_CONNECTION_STRING"],
 )
+```
+
+# [C#](#tab/csharp)
+
+```csharp
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Azure.Core;
+using Azure.Core.TestFramework;
+using NUnit.Framework;
+
+var connectionString = TestEnvironment.AzureAICONNECTIONSTRING;
+
+var clientOptions = new AIProjectClientOptions();
+
+// Adding the custom headers policy
+clientOptions.AddPolicy(new CustomHeadersPolicy(), HttpPipelinePosition.PerCall);
+var projectClient = new AIProjectClient(connectionString, new DefaultAzureCredential(), clientOptions);
+
+```
+
+---
+
+## Step 2: Enable the Bing search tool
+
+To make the Bing search tool available to your agent, create a Bing connection to initialize the Bing search tool and attach it to the agent. 
 
+# [Python](#tab/python)
+
+```python
 bing_connection = project_client.connections.get(
     connection_name=os.environ["BING_CONNECTION_NAME"]
 )
@@ -242,35 +186,128 @@ with project_client:
         headers={"x-ms-enable-preview": "true"}
     )
     print(f"Created agent, ID: {agent.id}")
+```
 
-    # Create thread for communication
-    thread = project_client.agents.create_thread()
-    print(f"Created thread, ID: {thread.id}")
+# [C#](#tab/csharp)
 
-    # Create message to thread
-    message = project_client.agents.create_message(
-        thread_id=thread.id,
-        role="user",
-        content="How is the weather in Seattle today?",
-    )
-    print(f"Created message, ID: {message.id}")
+```csharp
+GetConnectionResponse bingConnection = await projectClient.GetConnectionsClient().GetConnectionAsync(TestEnvironment.BINGCONNECTIONNAME);
+var connectionId = bingConnection.Id;
+
+AgentsClient agentClient = projectClient.GetAgentsClient();
 
-    # Create and process agent run in thread with tools
-    run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
-    print(f"Run finished with status: {run.status}")
+ToolConnectionList connectionList = new ToolConnectionList
+{
+    ConnectionList = { new ToolConnection(connectionId) }
+};
+BingGroundingToolDefinition bingGroundingTool = new BingGroundingToolDefinition(connectionList);
+
+Response<Agent> agentResponse = await agentClient.CreateAgentAsync(
+    model: "gpt-4o-mini",
+    name: "my-assistant",
+    instructions: "You are a helpful assistant.",
+    tools: new List<ToolDefinition> { bingGroundingTool });
+Agent agent = agentResponse.Value;
+```
+---
 
-    if run.status == "failed":
-        print(f"Run failed: {run.last_error}")
 
-    # Delete the assistant when done
-    project_client.agents.delete_agent(agent.id)
-    print("Deleted agent")
+## Step 3: Create a thread
 
-    # Fetch and log all messages
-    messages = project_client.agents.list_messages(thread_id=thread.id)
-    print(f"Messages: {messages}")
+# [Python](#tab/python)
+
+```python
+# Create thread for communication
+thread = project_client.agents.create_thread()
+print(f"Created thread, ID: {thread.id}")
+
+# Create message to thread
+message = project_client.agents.create_message(
+    thread_id=thread.id,
+    role="user",
+    content="How is the weather in Seattle today?",
+)
+print(f"Created message, ID: {message.id}")
 ```
 
+# [C#](#tab/csharp)
+
+```csharp
+// Create thread for communication
+Response<AgentThread> threadResponse = await agentClient.CreateThreadAsync();
+AgentThread thread = threadResponse.Value;
+
+// Create message to thread
+Response<ThreadMessage> messageResponse = await agentClient.CreateMessageAsync(
+    thread.Id,
+    MessageRole.User,
+    "How does wikipedia explain Euler's Identity?");
+ThreadMessage message = messageResponse.Value;
+```
+
+---
+
+## Step 4: Create a run and check the output
+
+Create a run and observe that the model uses the file search tool to provide a response to the user's question.
+
+# [Python](#tab/python)
+
+```python
+# Create and process agent run in thread with tools
+run = project_client.agents.create_and_process_run(thread_id=thread.id, assistant_id=agent.id)
+print(f"Run finished with status: {run.status}")
+
+if run.status == "failed":
+    print(f"Run failed: {run.last_error}")
+
+# Delete the assistant when done
+project_client.agents.delete_agent(agent.id)
+print("Deleted agent")
+
+# Fetch and log all messages
+messages = project_client.agents.list_messages(thread_id=thread.id)
+print(f"Messages: {messages}")
+```
+
+# [C#](#tab/csharp)
+
+```csharp
+// Run the agent
+Response<ThreadRun> runResponse = await agentClient.CreateRunAsync(thread, agent);
+
+do
+{
+    await Task.Delay(TimeSpan.FromMilliseconds(500));
+    runResponse = await agentClient.GetRunAsync(thread.Id, runResponse.Value.Id);
+}
+while (runResponse.Value.Status == RunStatus.Queued
+    || runResponse.Value.Status == RunStatus.InProgress);
+
+Response<PageableList<ThreadMessage>> afterRunMessagesResponse
+    = await agentClient.GetMessagesAsync(thread.Id);
+IReadOnlyList<ThreadMessage> messages = afterRunMessagesResponse.Value.Data;
+
+// Note: messages iterate from newest to oldest, with the messages[0] being the most recent
+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)
+        {
+            Console.Write(textItem.Text);
+        }
+        else if (contentItem is MessageImageFileContent imageFileItem)
+        {
+            Console.Write($"<image from ID: {imageFileItem.FileId}");
+        }
+        Console.WriteLine();
+    }
+}
+```
+---
+
 ::: zone-end
 
 ## Next steps