chore: import upstream snapshot with attribution

dotnet/samples/02-agents/AGUI/Step02_BackendTools/Client/Client.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+    <PackageReference Include="AGUI.Client" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AGUI/Step02_BackendTools/Client/Program.cs

@@ -0,0 +1,129 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using AGUI.Abstractions;
+using AGUI.Client;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:8888";
+
+Console.WriteLine($"Connecting to AG-UI server at: {serverUrl}\n");
+
+// Create the AG-UI client agent
+using HttpClient httpClient = new()
+{
+    Timeout = TimeSpan.FromSeconds(60)
+};
+
+AGUIChatClient chatClient = new(new(httpClient, serverUrl));
+
+AIAgent agent = chatClient.AsAIAgent(
+    name: "agui-client",
+    description: "AG-UI Client Agent");
+
+AgentSession session = await agent.CreateSessionAsync();
+List<ChatMessage> messages =
+[
+    new(ChatRole.System, "You are a helpful assistant.")
+];
+
+try
+{
+    while (true)
+    {
+        // Get user input
+        Console.Write("\nUser (:q or quit to exit): ");
+        string? message = Console.ReadLine();
+
+        if (string.IsNullOrWhiteSpace(message))
+        {
+            Console.WriteLine("Request cannot be empty.");
+            continue;
+        }
+
+        if (message is ":q" or "quit")
+        {
+            break;
+        }
+
+        messages.Add(new ChatMessage(ChatRole.User, message));
+
+        // Stream the response
+        bool isFirstUpdate = true;
+        string? threadId = null;
+
+        await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(messages, session))
+        {
+            ChatResponseUpdate chatUpdate = update.AsChatResponseUpdate();
+
+            // First update indicates run started
+            if (isFirstUpdate)
+            {
+                // AGUIChatClient is stateless and never surfaces a ConversationId; the thread
+                // id is carried on the AG-UI RUN_STARTED event's raw representation.
+                threadId = (chatUpdate.RawRepresentation as RunStartedEvent)?.ThreadId;
+                Console.ForegroundColor = ConsoleColor.Yellow;
+                Console.WriteLine($"\n[Run Started - Thread: {threadId}, Run: {chatUpdate.ResponseId}]");
+                Console.ResetColor();
+                isFirstUpdate = false;
+            }
+
+            // Display streaming content
+            foreach (AIContent content in update.Contents)
+            {
+                switch (content)
+                {
+                    case TextContent textContent:
+                        Console.ForegroundColor = ConsoleColor.Cyan;
+                        Console.Write(textContent.Text);
+                        Console.ResetColor();
+                        break;
+
+                    case FunctionCallContent functionCallContent:
+                        Console.ForegroundColor = ConsoleColor.Green;
+                        Console.WriteLine($"\n[Function Call - Name: {functionCallContent.Name}]");
+
+                        // Display individual parameters
+                        if (functionCallContent.Arguments != null)
+                        {
+                            foreach (var kvp in functionCallContent.Arguments)
+                            {
+                                Console.WriteLine($"  Parameter: {kvp.Key} = {kvp.Value}");
+                            }
+                        }
+                        Console.ResetColor();
+                        break;
+
+                    case FunctionResultContent functionResultContent:
+                        Console.ForegroundColor = ConsoleColor.Magenta;
+                        Console.WriteLine($"\n[Function Result - CallId: {functionResultContent.CallId}]");
+
+                        if (functionResultContent.Exception != null)
+                        {
+                            Console.WriteLine($"  Exception: {functionResultContent.Exception}");
+                        }
+                        else
+                        {
+                            Console.WriteLine($"  Result: {functionResultContent.Result}");
+                        }
+                        Console.ResetColor();
+                        break;
+
+                    case ErrorContent errorContent:
+                        Console.ForegroundColor = ConsoleColor.Red;
+                        Console.WriteLine($"\n[Error: {errorContent.Message}]");
+                        Console.ResetColor();
+                        break;
+                }
+            }
+        }
+
+        Console.ForegroundColor = ConsoleColor.Green;
+        Console.WriteLine($"\n[Run Finished - Thread: {threadId}]");
+        Console.ResetColor();
+    }
+}
+catch (Exception ex)
+{
+    Console.WriteLine($"\nAn error occurred: {ex.Message}");
+}

dotnet/samples/02-agents/AGUI/Step02_BackendTools/Server/Program.cs

@@ -0,0 +1,125 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Options;
+using OpenAI.Chat;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+builder.Services.AddHttpClient().AddLogging();
+builder.Services.ConfigureHttpJsonOptions(options =>
+    options.SerializerOptions.TypeInfoResolverChain.Add(SampleJsonSerializerContext.Default));
+builder.Services.AddAGUIServer();
+
+// WARNING: When adding session persistence (e.g., WithInMemorySessionStore), or running in production,
+// make sure to also register a SessionIsolationKeyProvider to scope sessions by principal in multi-user
+// deployments, e.g.:
+// builder.Services.UseClaimsBasedSessionIsolation(new() { ClaimType = ClaimTypes.NameIdentifier });
+
+WebApplication app = builder.Build();
+
+string endpoint = builder.Configuration["AZURE_OPENAI_ENDPOINT"]
+    ?? throw new InvalidOperationException("AZURE_OPENAI_ENDPOINT is not set.");
+string deploymentName = builder.Configuration["AZURE_OPENAI_DEPLOYMENT_NAME"]
+    ?? throw new InvalidOperationException("AZURE_OPENAI_DEPLOYMENT_NAME is not set.");
+
+// Define the function tool
+[Description("Search for restaurants in a location.")]
+static RestaurantSearchResponse SearchRestaurants(
+    [Description("The restaurant search request")] RestaurantSearchRequest request)
+{
+    // Simulated restaurant data
+    string cuisine = request.Cuisine == "any" ? "Italian" : request.Cuisine;
+
+    return new RestaurantSearchResponse
+    {
+        Location = request.Location,
+        Cuisine = request.Cuisine,
+        Results =
+        [
+            new RestaurantInfo
+            {
+                Name = "The Golden Fork",
+                Cuisine = cuisine,
+                Rating = 4.5,
+                Address = $"123 Main St, {request.Location}"
+            },
+            new RestaurantInfo
+            {
+                Name = "Spice Haven",
+                Cuisine = cuisine == "Italian" ? "Indian" : cuisine,
+                Rating = 4.7,
+                Address = $"456 Oak Ave, {request.Location}"
+            },
+            new RestaurantInfo
+            {
+                Name = "Green Leaf",
+                Cuisine = "Vegetarian",
+                Rating = 4.3,
+                Address = $"789 Elm Rd, {request.Location}"
+            }
+        ]
+    };
+}
+
+// Get JsonSerializerOptions from the configured HTTP JSON options
+Microsoft.AspNetCore.Http.Json.JsonOptions jsonOptions = app.Services.GetRequiredService<IOptions<Microsoft.AspNetCore.Http.Json.JsonOptions>>().Value;
+
+// Create tool with serializer options
+AITool[] tools =
+[
+    AIFunctionFactory.Create(
+        SearchRestaurants,
+        serializerOptions: jsonOptions.SerializerOptions)
+];
+
+// Create the AI agent with tools
+// WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+// In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+// latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+ChatClient chatClient = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetChatClient(deploymentName);
+
+ChatClientAgent agent = chatClient.AsAIAgent(
+    name: "AGUIAssistant",
+    instructions: "You are a helpful assistant with access to restaurant information.",
+    tools: tools);
+
+// Map the AG-UI agent endpoint
+app.MapAGUIServer("/", agent);
+
+await app.RunAsync();
+
+// Define request/response types for the tool
+internal sealed class RestaurantSearchRequest
+{
+    public string Location { get; set; } = string.Empty;
+    public string Cuisine { get; set; } = "any";
+}
+
+internal sealed class RestaurantSearchResponse
+{
+    public string Location { get; set; } = string.Empty;
+    public string Cuisine { get; set; } = string.Empty;
+    public RestaurantInfo[] Results { get; set; } = [];
+}
+
+internal sealed class RestaurantInfo
+{
+    public string Name { get; set; } = string.Empty;
+    public string Cuisine { get; set; } = string.Empty;
+    public double Rating { get; set; }
+    public string Address { get; set; } = string.Empty;
+}
+
+// JSON serialization context for source generation
+[JsonSerializable(typeof(RestaurantSearchRequest))]
+[JsonSerializable(typeof(RestaurantSearchResponse))]
+internal sealed partial class SampleJsonSerializerContext : JsonSerializerContext;

dotnet/samples/02-agents/AGUI/Step02_BackendTools/Server/Properties/launchSettings.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json.schemastore.org/launchsettings.json",
+  "profiles": {
+    "http": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "http://localhost:5253",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7047;http://localhost:5253",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

dotnet/samples/02-agents/AGUI/Step02_BackendTools/Server/Server.csproj

@@ -0,0 +1,21 @@
+<Project Sdk="Microsoft.NET.Sdk.Web">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.AI.OpenAI" />
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore\Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.Hosting.AspNetCore\Microsoft.Agents.AI.Hosting.AspNetCore.csproj" />
+    <ProjectReference Include="..\..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/AGUI/Step02_BackendTools/Server/appsettings.Development.json

@@ -0,0 +1,8 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  }
+}

dotnet/samples/02-agents/AGUI/Step02_BackendTools/Server/appsettings.json

@@ -0,0 +1,9 @@
+{
+  "Logging": {
+    "LogLevel": {
+      "Default": "Information",
+      "Microsoft.AspNetCore": "Warning"
+    }
+  },
+  "AllowedHosts": "*"
+}