Update samples

sdk/ai/Azure.AI.Client/README.md

@@ -32,9 +32,12 @@ creating, running, and using assistants and threads.
 
 To get started, create an `AssistantsClient`:
 ```C# Snippet:OverviewCreateClient
-AssistantsClient client = isAzureOpenAI
-    ? new AssistantsClient(new Uri(azureResourceUrl), new AzureKeyCredential(azureApiKey))
-    : new AssistantsClient(nonAzureApiKey);
+Agents client = new AzureAIClient(
+    endpoint: new Uri(Environment.GetEnvironmentVariable("AZURE_AI_ENDPOINT")),
+    subscriptionId: Environment.GetEnvironmentVariable("AZURE_AI_SUBSCRIPTION_ID"),
+    resourceGroupName: Environment.GetEnvironmentVariable("AZURE_AI_RESOURCE_GROUP_NAME"),
+    projectName: Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_NAME"),
+    credential: new DefaultAzureCredential()).GetAgentsClient();
 ```
 
 > **NOTE**: The Assistants API should always be used from a trusted device. Because the same authentication mechanism for running threads also allows changing persistent resources like Assistant instructions, a malicious user could extract an API key and modify Assistant behavior for other customers.
@@ -51,21 +54,19 @@ For an overview of Assistants and the pertinent key concepts like Threads, Messa
 ### Examples
 
 With an authenticated client, an assistant can be created:
-```C# Snippet:OverviewCreateAssistant
-Response<Assistant> assistantResponse = await client.CreateAssistantAsync(
-    new AssistantCreationOptions("gpt-4-1106-preview")
-    {
-        Name = "Math Tutor",
-        Instructions = "You are a personal math tutor. Write and run code to answer math questions.",
-        Tools = { new CodeInterpreterToolDefinition() }
-    });
-Assistant assistant = assistantResponse.Value;
+```C# Snippet:OverviewCreateAgent
+Response<Agent> agentResponse = await client.CreateAgentAsync(
+    model: "gpt-4-1106-preview",
+    name: "Math Tutor",
+    instructions: "You are a personal math tutor. Write and run code to answer math questions.",
+    tools: new List<ToolDefinition> { new CodeInterpreterToolDefinition() });
+Agent agent = agentResponse.Value;
 ```
 
 Next, create a thread:
 ```C# Snippet:OverviewCreateThread
-Response<AssistantThread> threadResponse = await client.CreateThreadAsync();
-AssistantThread thread = threadResponse.Value;
+Response<AgentThread> threadResponse = await client.CreateThreadAsync();
+AgentThread thread = threadResponse.Value;
 ```
 
 With a thread created, messages can be created on it:
@@ -81,10 +82,8 @@ A run can then be started that evaluates the thread against an assistant:
 ```C# Snippet:OverviewCreateRun
 Response<ThreadRun> runResponse = await client.CreateRunAsync(
     thread.Id,
-    new CreateRunOptions(assistant.Id)
-    {
-        AdditionalInstructions = "Please address the user as Jane Doe. The user has a premium account.",
-    });
+    agent.Id,
+    additionalInstructions: "Please address the user as Jane Doe. The user has a premium account.");
 ThreadRun run = runResponse.Value;
 ```
 
@@ -135,28 +134,26 @@ Example output from this sequence:
 
 Files can be uploaded and then referenced by assistants or messages. First, use the generalized upload API with a
 purpose of 'assistants' to make a file ID available:
-```C# Snippet:UploadAssistantFilesToUse
+```C# Snippet:UploadAgentFilesToUse
 File.WriteAllText(
     path: "sample_file_for_upload.txt",
     contents: "The word 'apple' uses the code 442345, while the word 'banana' uses the code 673457.");
-Response<OpenAIFile> uploadAssistantFileResponse = await client.UploadFileAsync(
+Response<OpenAIFile> uploadAgentFileResponse = await client.UploadFileAsync(
     localFilePath: "sample_file_for_upload.txt",
-    purpose: OpenAIFilePurpose.Assistants);
-OpenAIFile uploadedAssistantFile = uploadAssistantFileResponse.Value;
+    purpose: OpenAIFilePurpose.Agents);
+OpenAIFile uploadedAgentFile = uploadAgentFileResponse.Value;
 ```
 
 Once uploaded, the file ID can then be provided to an assistant upon creation. Note that file IDs will only be used
 if an appropriate tool like Code Interpreter or Retrieval is enabled.
-```C# Snippet:CreateAssistantWithFiles
-Response<Assistant> assistantResponse = await client.CreateAssistantAsync(
-    new AssistantCreationOptions("gpt-4-1106-preview")
-    {
-        Name = "SDK Test Assistant - Retrieval",
-        Instructions = "You are a helpful assistant that can help fetch data from files you know about.",
-        Tools = { new RetrievalToolDefinition() },
-        FileIds = { uploadedAssistantFile.Id },
-    });
-Assistant assistant = assistantResponse.Value;
+```C# Snippet:CreateAgentWithFiles
+Response<Agent> agentResponse = await client.CreateAgentAsync(
+        model: "gpt-4-1106-preview",
+        name: "SDK Test Agent - Retrieval",
+        instructions: "You are a helpful agent that can help fetch data from files you know about.",
+        tools: new List<ToolDefinition> { new FileSearchToolDefinition() });
+        //toolResources: new ToolResources() { FileSearch = new FileSearchToolResource() { VectorStoreIds.Add(uploadedAgentFile.Id) },
+Agent agent = agentResponse.Value;
 ```
 
 With a file ID association and a supported tool enabled, the assistant will then be able to consume the associated
@@ -238,23 +235,17 @@ FunctionToolDefinition getCurrentWeatherAtLocationTool = new(
 
 With the functions defined in their appropriate tools, an assistant can be now created that has those tools enabled:
 
-```C# Snippet:FunctionsCreateAssistantWithFunctionTools
-Response<Assistant> assistantResponse = await client.CreateAssistantAsync(
-    // note: parallel function calling is only supported with newer models like gpt-4-1106-preview
-    new AssistantCreationOptions("gpt-4-1106-preview")
-    {
-        Name = "SDK Test Assistant - Functions",
-        Instructions = "You are a weather bot. Use the provided functions to help answer questions. "
+```C# Snippet:FunctionsCreateAgentWithFunctionTools
+// note: parallel function calling is only supported with newer models like gpt-4-1106-preview
+Response<Agent> agentResponse = await client.CreateAgentAsync(
+    model: "gpt-4-1106-preview",
+    name: "SDK Test Agent - Functions",
+        instructions: "You are a weather bot. Use the provided functions to help answer questions. "
             + "Customize your responses to the user's preferences as much as possible and use friendly "
             + "nicknames for cities whenever possible.",
-        Tools =
-        {
-            getUserFavoriteCityTool,
-            getCityNicknameTool,
-            getCurrentWeatherAtLocationTool,
-        },
-    });
-Assistant assistant = assistantResponse.Value;
+    tools: new List<ToolDefinition> { getUserFavoriteCityTool, getCityNicknameTool, getCurrentWeatherAtLocationTool }
+    );
+Agent agent = agentResponse.Value;
 ```
 
 If the assistant calls tools, the calling code will need to resolve `ToolCall` instances into matching
@@ -410,7 +401,7 @@ You have the flexibility to explicitly select a supported service API version wh
 
 For example,
 
-```C# Snippet:Create<YourService>ClientForSpecificApiVersion
+```C#
 Uri endpoint = new Uri("<your endpoint>");
 DefaultAzureCredential credential = new DefaultAzureCredential();
 <YourService>ClientOptions options = new <YourService>ClientOptions(<YourService>ClientOptions.ServiceVersion.<API Version>)

sdk/ai/Azure.AI.Client/tests/Samples/Samples_Agents.cs → sdk/ai/Azure.AI.Client/tests/Samples/Sample_Agent_Basics.cs

@@ -1,8 +1,6 @@
 // Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
-// <auto-generated/>
-
 #nullable disable
 
 using System;
@@ -15,10 +13,10 @@
 
 namespace Azure.AI.Client.Tests;
 
-public partial class Samples_Agents
+public partial class Sample_Agent_Basics
 {
     [Test]
-    public async Task AgentSample()
+    public async Task BasicExample()
     {
         #region Snippet:OverviewCreateClient
         Agents client = new AzureAIClient(
@@ -29,18 +27,17 @@ public async Task AgentSample()
             credential: new DefaultAzureCredential()).GetAgentsClient();
         #endregion
 
-        // Step 1: Create an assistant
-        #region Snippet:OverviewCreateAssistant
+        // Step 1: Create an agent
+        #region Snippet:OverviewCreateAgent
         Response<Agent> agentResponse = await client.CreateAgentAsync(
             model: "gpt-4-1106-preview",
             name: "Math Tutor",
             instructions: "You are a personal math tutor. Write and run code to answer math questions.",
-            tools: new List<ToolDefinition> { new CodeInterpreterToolDefinition() }
-            );
-        Agent assistant = agentResponse.Value;
+            tools: new List<ToolDefinition> { new CodeInterpreterToolDefinition() });
+        Agent agent = agentResponse.Value;
         #endregion
 
-        // Intermission: assistant should now be listed
+        // Intermission: agent should now be listed
 
         Response<PageableList<Agent>> agentListResponse = await client.GetAgentsAsync();
 
@@ -70,7 +67,7 @@ public async Task AgentSample()
         #region Snippet:OverviewCreateRun
         Response<ThreadRun> runResponse = await client.CreateRunAsync(
             thread.Id,
-            assistant.Id,
+            agent.Id,
             additionalInstructions: "Please address the user as Jane Doe. The user has a premium account.");
         ThreadRun run = runResponse.Value;
         #endregion

sdk/ai/Azure.AI.Client/tests/Samples/Sample_Agent_Functions.cs

@@ -0,0 +1,184 @@
+// Copyright (c) Microsoft Corporation. All rights reserved.
+// Licensed under the MIT License.
+
+#nullable disable
+
+using System;
+using System.Collections.Generic;
+using System.Text.Json;
+using System.Threading.Tasks;
+using Azure.AI.Client.Models;
+using Azure.Identity;
+using NUnit.Framework;
+
+namespace Azure.AI.Client.Tests;
+
+public partial class Sample_Agent_Functions
+{
+    [Test]
+    public async Task FunctionCallingExample()
+    {
+        Agents client = new AzureAIClient(
+            endpoint: new Uri(Environment.GetEnvironmentVariable("AZURE_AI_ENDPOINT")),
+            subscriptionId: Environment.GetEnvironmentVariable("AZURE_AI_SUBSCRIPTION_ID"),
+            resourceGroupName: Environment.GetEnvironmentVariable("AZURE_AI_RESOURCE_GROUP_NAME"),
+            projectName: Environment.GetEnvironmentVariable("AZURE_AI_PROJECT_NAME"),
+            credential: new DefaultAzureCredential()).GetAgentsClient();
+
+        #region Snippet:FunctionsDefineFunctionTools
+        // Example of a function that defines no parameters
+        string GetUserFavoriteCity() => "Seattle, WA";
+        FunctionToolDefinition getUserFavoriteCityTool = new("getUserFavoriteCity", "Gets the user's favorite city.");
+        // Example of a function with a single required parameter
+        string GetCityNickname(string location) => location switch
+        {
+            "Seattle, WA" => "The Emerald City",
+            _ => throw new NotImplementedException(),
+        };
+        FunctionToolDefinition getCityNicknameTool = new(
+            name: "getCityNickname",
+            description: "Gets the nickname of a city, e.g. 'LA' for 'Los Angeles, CA'.",
+            parameters: BinaryData.FromObjectAsJson(
+                new
+                {
+                    Type = "object",
+                    Properties = new
+                    {
+                        Location = new
+                        {
+                            Type = "string",
+                            Description = "The city and state, e.g. San Francisco, CA",
+                        },
+                    },
+                    Required = new[] { "location" },
+                },
+                new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }));
+        // Example of a function with one required and one optional, enum parameter
+        string GetWeatherAtLocation(string location, string temperatureUnit = "f") => location switch
+        {
+            "Seattle, WA" => temperatureUnit == "f" ? "70f" : "21c",
+            _ => throw new NotImplementedException()
+        };
+        FunctionToolDefinition getCurrentWeatherAtLocationTool = new(
+            name: "getCurrentWeatherAtLocation",
+            description: "Gets the current weather at a provided location.",
+            parameters: BinaryData.FromObjectAsJson(
+                new
+                {
+                    Type = "object",
+                    Properties = new
+                    {
+                        Location = new
+                        {
+                            Type = "string",
+                            Description = "The city and state, e.g. San Francisco, CA",
+                        },
+                        Unit = new
+                        {
+                            Type = "string",
+                            Enum = new[] { "c", "f" },
+                        },
+                    },
+                    Required = new[] { "location" },
+                },
+                new JsonSerializerOptions() { PropertyNamingPolicy = JsonNamingPolicy.CamelCase }));
+        #endregion
+
+        #region Snippet:FunctionsHandleFunctionCalls
+        ToolOutput GetResolvedToolOutput(RequiredToolCall toolCall)
+        {
+            if (toolCall is RequiredFunctionToolCall functionToolCall)
+            {
+                if (functionToolCall.Name == getUserFavoriteCityTool.Name)
+                {
+                    return new ToolOutput(toolCall, GetUserFavoriteCity());
+                }
+                using JsonDocument argumentsJson = JsonDocument.Parse(functionToolCall.Arguments);
+                if (functionToolCall.Name == getCityNicknameTool.Name)
+                {
+                    string locationArgument = argumentsJson.RootElement.GetProperty("location").GetString();
+                    return new ToolOutput(toolCall, GetCityNickname(locationArgument));
+                }
+                if (functionToolCall.Name == getCurrentWeatherAtLocationTool.Name)
+                {
+                    string locationArgument = argumentsJson.RootElement.GetProperty("location").GetString();
+                    if (argumentsJson.RootElement.TryGetProperty("unit", out JsonElement unitElement))
+                    {
+                        string unitArgument = unitElement.GetString();
+                        return new ToolOutput(toolCall, GetWeatherAtLocation(locationArgument, unitArgument));
+                    }
+                    return new ToolOutput(toolCall, GetWeatherAtLocation(locationArgument));
+                }
+            }
+            return null;
+        }
+        #endregion
+
+        #region Snippet:FunctionsCreateAgentWithFunctionTools
+        // note: parallel function calling is only supported with newer models like gpt-4-1106-preview
+        Response<Agent> agentResponse = await client.CreateAgentAsync(
+            model: "gpt-4-1106-preview",
+            name: "SDK Test Agent - Functions",
+                instructions: "You are a weather bot. Use the provided functions to help answer questions. "
+                    + "Customize your responses to the user's preferences as much as possible and use friendly "
+                    + "nicknames for cities whenever possible.",
+            tools: new List<ToolDefinition> { getUserFavoriteCityTool, getCityNicknameTool, getCurrentWeatherAtLocationTool }
+            );
+        Agent agent = agentResponse.Value;
+        #endregion
+
+        Response<AgentThread> threadResponse = await client.CreateThreadAsync();
+        AgentThread thread = threadResponse.Value;
+
+        Response<ThreadMessage> messageResponse = await client.CreateMessageAsync(
+            thread.Id,
+            MessageRole.User,
+            "What's the weather like in my favorite city?");
+        ThreadMessage message = messageResponse.Value;
+
+        Response<ThreadRun> runResponse = await client.CreateRunAsync(thread, agent);
+
+        #region Snippet:FunctionsHandlePollingWithRequiredAction
+        do
+        {
+            await Task.Delay(TimeSpan.FromMilliseconds(500));
+            runResponse = await client.GetRunAsync(thread.Id, runResponse.Value.Id);
+
+            if (runResponse.Value.Status == RunStatus.RequiresAction
+                && runResponse.Value.RequiredAction is SubmitToolOutputsAction submitToolOutputsAction)
+            {
+                List<ToolOutput> toolOutputs = new();
+                foreach (RequiredToolCall toolCall in submitToolOutputsAction.ToolCalls)
+                {
+                    toolOutputs.Add(GetResolvedToolOutput(toolCall));
+                }
+                runResponse = await client.SubmitToolOutputsToRunAsync(runResponse.Value, toolOutputs);
+            }
+        }
+        while (runResponse.Value.Status == RunStatus.Queued
+            || runResponse.Value.Status == RunStatus.InProgress);
+        #endregion
+
+        Response<PageableList<ThreadMessage>> afterRunMessagesResponse
+            = await client.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();
+            }
+        }
+    }
+}