chore: import upstream snapshot with attribution

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

@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
+using Microsoft.AspNetCore.Http.Json;
+using Microsoft.AspNetCore.HttpLogging;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.Options;
+using OpenAI.Chat;
+using ServerFunctionApproval;
+
+WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
+
+builder.Services.AddHttpLogging(logging =>
+{
+    logging.LoggingFields = HttpLoggingFields.RequestPropertiesAndHeaders | HttpLoggingFields.RequestBody
+        | HttpLoggingFields.ResponsePropertiesAndHeaders | HttpLoggingFields.ResponseBody;
+    logging.RequestBodyLogLimit = int.MaxValue;
+    logging.ResponseBodyLogLimit = int.MaxValue;
+});
+
+builder.Services.AddHttpClient().AddLogging();
+builder.Services.ConfigureHttpJsonOptions(options =>
+    options.SerializerOptions.TypeInfoResolverChain.Add(ApprovalJsonContext.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();
+
+app.UseHttpLogging();
+
+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 approval-required tool
+[Description("Approve the expense report.")]
+static string ApproveExpenseReport(string expenseReportId)
+{
+    return $"Expense report {expenseReportId} approved";
+}
+
+// Get JsonSerializerOptions
+var jsonOptions = app.Services.GetRequiredService<IOptions<JsonOptions>>().Value;
+
+// Create approval-required tool
+#pragma warning disable MEAI001 // Type is for evaluation purposes only
+AITool[] tools = [new ApprovalRequiredAIFunction(AIFunctionFactory.Create(ApproveExpenseReport))];
+#pragma warning restore MEAI001
+
+// Create base agent
+// 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 openAIChatClient = new AzureOpenAIClient(
+        new Uri(endpoint),
+        new DefaultAzureCredential())
+    .GetChatClient(deploymentName);
+
+ChatClientAgent baseAgent = openAIChatClient.AsAIAgent(
+    name: "AGUIAssistant",
+    instructions: "You are a helpful assistant in charge of approving expenses",
+    tools: tools);
+
+// Wrap with ServerFunctionApprovalAgent
+var agent = new ServerFunctionApprovalAgent(baseAgent, jsonOptions.SerializerOptions);
+
+app.MapAGUIServer("/", agent);
+await app.RunAsync();

dotnet/samples/02-agents/AGUI/Step04_HumanInLoop/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:5100",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    },
+    "https": {
+      "commandName": "Project",
+      "dotnetRunMessages": true,
+      "launchBrowser": true,
+      "applicationUrl": "https://localhost:7047;http://localhost:5100",
+      "environmentVariables": {
+        "ASPNETCORE_ENVIRONMENT": "Development"
+      }
+    }
+  }
+}

dotnet/samples/02-agents/AGUI/Step04_HumanInLoop/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/Step04_HumanInLoop/Server/ServerFunctionApprovalServerAgent.cs

@@ -0,0 +1,249 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using System.Text.Json.Serialization;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using ServerFunctionApproval;
+
+/// <summary>
+/// A delegating agent that handles function approval requests on the server side.
+/// Transforms between ToolApprovalRequestContent/ToolApprovalResponseContent
+/// and the request_approval tool call pattern for client communication.
+/// </summary>
+internal sealed class ServerFunctionApprovalAgent : DelegatingAIAgent
+{
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    public ServerFunctionApprovalAgent(AIAgent innerAgent, JsonSerializerOptions jsonSerializerOptions)
+        : base(innerAgent)
+    {
+        this._jsonSerializerOptions = jsonSerializerOptions;
+    }
+
+    protected override Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        return this.RunCoreStreamingAsync(messages, session, options, cancellationToken)
+            .ToAgentResponseAsync(cancellationToken);
+    }
+
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // Process and transform incoming approval responses from client, creating a new message list
+        var processedMessages = ProcessIncomingFunctionApprovals(messages.ToList(), this._jsonSerializerOptions);
+
+        // Run the inner agent and intercept any approval requests
+        await foreach (var update in this.InnerAgent.RunStreamingAsync(
+            processedMessages, session, options, cancellationToken).ConfigureAwait(false))
+        {
+            yield return ProcessOutgoingApprovalRequests(update, this._jsonSerializerOptions);
+        }
+    }
+
+#pragma warning disable MEAI001 // Type is for evaluation purposes only
+    private static ToolApprovalRequestContent ConvertToolCallToApprovalRequest(FunctionCallContent toolCall, JsonSerializerOptions jsonSerializerOptions)
+    {
+        if (toolCall.Name != "request_approval" || toolCall.Arguments == null)
+        {
+            throw new InvalidOperationException("Invalid request_approval tool call");
+        }
+
+        var request = (toolCall.Arguments.TryGetValue("request", out var reqObj) &&
+            reqObj is JsonElement argsElement &&
+            argsElement.Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(ApprovalRequest))) is ApprovalRequest approvalRequest &&
+            approvalRequest != null ? approvalRequest : null) ?? throw new InvalidOperationException("Failed to deserialize approval request from tool call");
+        return new ToolApprovalRequestContent(
+            requestId: request.ApprovalId,
+            new FunctionCallContent(
+                callId: request.ApprovalId,
+                name: request.FunctionName,
+                arguments: request.FunctionArguments));
+    }
+
+    private static ToolApprovalResponseContent ConvertToolResultToApprovalResponse(FunctionResultContent result, ToolApprovalRequestContent approval, JsonSerializerOptions jsonSerializerOptions)
+    {
+        var approvalResponse = (result.Result is JsonElement je ?
+            (ApprovalResponse?)je.Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(ApprovalResponse))) :
+            result.Result is string str ?
+                (ApprovalResponse?)JsonSerializer.Deserialize(str, jsonSerializerOptions.GetTypeInfo(typeof(ApprovalResponse))) :
+                result.Result as ApprovalResponse) ?? throw new InvalidOperationException("Failed to deserialize approval response from tool result");
+        return approval.CreateResponse(approvalResponse.Approved);
+    }
+#pragma warning restore MEAI001
+
+    private static List<ChatMessage> CopyMessagesUpToIndex(List<ChatMessage> messages, int index)
+    {
+        var result = new List<ChatMessage>(index);
+        for (int i = 0; i < index; i++)
+        {
+            result.Add(messages[i]);
+        }
+        return result;
+    }
+
+    private static List<AIContent> CopyContentsUpToIndex(IList<AIContent> contents, int index)
+    {
+        var result = new List<AIContent>(index);
+        for (int i = 0; i < index; i++)
+        {
+            result.Add(contents[i]);
+        }
+        return result;
+    }
+
+    private static List<ChatMessage> ProcessIncomingFunctionApprovals(
+        List<ChatMessage> messages,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        List<ChatMessage>? result = null;
+
+        // Track approval ID to original call ID mapping
+        _ = new Dictionary<string, string>();
+#pragma warning disable MEAI001 // Type is for evaluation purposes only and is subject to change or removal in future updates. Suppress this diagnostic to proceed.
+        Dictionary<string, ToolApprovalRequestContent> trackedRequestApprovalToolCalls = []; // Remote approvals
+        for (int messageIndex = 0; messageIndex < messages.Count; messageIndex++)
+        {
+            var message = messages[messageIndex];
+            List<AIContent>? transformedContents = null;
+            for (int j = 0; j < message.Contents.Count; j++)
+            {
+                var content = message.Contents[j];
+                if (content is FunctionCallContent { Name: "request_approval" } toolCall)
+                {
+                    result ??= CopyMessagesUpToIndex(messages, messageIndex);
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, j);
+                    var approvalRequest = ConvertToolCallToApprovalRequest(toolCall, jsonSerializerOptions);
+                    transformedContents.Add(approvalRequest);
+                    trackedRequestApprovalToolCalls[toolCall.CallId] = approvalRequest;
+                    result.Add(new ChatMessage(message.Role, transformedContents)
+                    {
+                        AuthorName = message.AuthorName,
+                        MessageId = message.MessageId,
+                        CreatedAt = message.CreatedAt,
+                        RawRepresentation = message.RawRepresentation,
+                        AdditionalProperties = message.AdditionalProperties
+                    });
+                }
+                else if (content is FunctionResultContent toolResult &&
+                    trackedRequestApprovalToolCalls.TryGetValue(toolResult.CallId, out var approval))
+                {
+                    result ??= CopyMessagesUpToIndex(messages, messageIndex);
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, j);
+                    var approvalResponse = ConvertToolResultToApprovalResponse(toolResult, approval, jsonSerializerOptions);
+                    transformedContents.Add(approvalResponse);
+                    result.Add(new ChatMessage(message.Role, transformedContents)
+                    {
+                        AuthorName = message.AuthorName,
+                        MessageId = message.MessageId,
+                        CreatedAt = message.CreatedAt,
+                        RawRepresentation = message.RawRepresentation,
+                        AdditionalProperties = message.AdditionalProperties
+                    });
+                }
+                else
+                {
+                    result?.Add(message);
+                }
+            }
+        }
+#pragma warning restore MEAI001
+
+        return result ?? messages;
+    }
+
+    private static AgentResponseUpdate ProcessOutgoingApprovalRequests(
+        AgentResponseUpdate update,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        IList<AIContent>? updatedContents = null;
+        for (var i = 0; i < update.Contents.Count; i++)
+        {
+            var content = update.Contents[i];
+#pragma warning disable MEAI001 // Type is for evaluation purposes only
+            if (content is ToolApprovalRequestContent request && request.ToolCall is FunctionCallContent functionCall)
+            {
+                updatedContents ??= [.. update.Contents];
+                var approvalId = request.RequestId;
+
+                var approvalData = new ApprovalRequest
+                {
+                    ApprovalId = approvalId,
+                    FunctionName = functionCall.Name,
+                    FunctionArguments = functionCall.Arguments,
+                    Message = $"Approve execution of '{functionCall.Name}'?"
+                };
+
+                updatedContents[i] = new FunctionCallContent(
+                    callId: approvalId,
+                    name: "request_approval",
+                    arguments: new Dictionary<string, object?> { ["request"] = approvalData });
+            }
+#pragma warning restore MEAI001
+        }
+
+        if (updatedContents is not null)
+        {
+            var chatUpdate = update.AsChatResponseUpdate();
+            // Yield a tool call update that represents the approval request
+            return new AgentResponseUpdate(new ChatResponseUpdate()
+            {
+                Role = chatUpdate.Role,
+                Contents = updatedContents,
+                MessageId = chatUpdate.MessageId,
+                AuthorName = chatUpdate.AuthorName,
+                CreatedAt = chatUpdate.CreatedAt,
+                RawRepresentation = chatUpdate.RawRepresentation,
+                ResponseId = chatUpdate.ResponseId,
+                AdditionalProperties = chatUpdate.AdditionalProperties
+            })
+            {
+                AgentId = update.AgentId,
+                ContinuationToken = update.ContinuationToken
+            };
+        }
+
+        return update;
+    }
+}
+
+namespace ServerFunctionApproval
+{
+    // Define approval models
+    public sealed class ApprovalRequest
+    {
+        [JsonPropertyName("approval_id")]
+        public required string ApprovalId { get; init; }
+
+        [JsonPropertyName("function_name")]
+        public required string FunctionName { get; init; }
+
+        [JsonPropertyName("function_arguments")]
+        public IDictionary<string, object?>? FunctionArguments { get; init; }
+
+        [JsonPropertyName("message")]
+        public string? Message { get; init; }
+    }
+
+    public sealed class ApprovalResponse
+    {
+        [JsonPropertyName("approval_id")]
+        public required string ApprovalId { get; init; }
+
+        [JsonPropertyName("approved")]
+        public required bool Approved { get; init; }
+    }
+
+    [JsonSerializable(typeof(ApprovalRequest))]
+    [JsonSerializable(typeof(ApprovalResponse))]
+    [JsonSerializable(typeof(Dictionary<string, object?>))]
+    public sealed partial class ApprovalJsonContext : JsonSerializerContext;
+}

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

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

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

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