chore: import upstream snapshot with attribution

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

@@ -0,0 +1,152 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text.Json;
+using AGUI.Client;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+string serverUrl = Environment.GetEnvironmentVariable("AGUI_SERVER_URL") ?? "http://localhost:5100";
+
+// Connect to the AG-UI server
+using HttpClient httpClient = new()
+{
+    Timeout = TimeSpan.FromSeconds(60)
+};
+
+AGUIChatClient chatClient = new(new(httpClient, serverUrl));
+
+// Create agent
+ChatClientAgent baseAgent = chatClient.AsAIAgent(
+    name: "AGUIAssistant",
+    instructions: "You are a helpful assistant.");
+
+// Use default JSON serializer options
+JsonSerializerOptions jsonSerializerOptions = JsonSerializerOptions.Default;
+
+// Wrap the agent with ServerFunctionApprovalClientAgent
+ServerFunctionApprovalClientAgent agent = new(baseAgent, jsonSerializerOptions);
+
+List<ChatMessage> messages = [];
+AgentSession? session = null;
+
+Console.ForegroundColor = ConsoleColor.White;
+Console.WriteLine("Ask a question (or type 'exit' to quit):");
+Console.ResetColor();
+
+string? input;
+while ((input = Console.ReadLine()) != null && !input.Equals("exit", StringComparison.OrdinalIgnoreCase))
+{
+    if (string.IsNullOrWhiteSpace(input))
+    {
+        continue;
+    }
+
+    messages.Add(new ChatMessage(ChatRole.User, input));
+    Console.WriteLine();
+
+#pragma warning disable MEAI001
+    List<AIContent> approvalResponses = [];
+
+    do
+    {
+        approvalResponses.Clear();
+
+        List<AgentResponseUpdate> chatResponseUpdates = [];
+        await foreach (AgentResponseUpdate update in agent.RunStreamingAsync(messages, session, cancellationToken: default))
+        {
+            chatResponseUpdates.Add(update);
+            foreach (AIContent content in update.Contents)
+            {
+                switch (content)
+                {
+                    case ToolApprovalRequestContent approvalRequest when approvalRequest.ToolCall is FunctionCallContent fcc:
+                        DisplayApprovalRequest(approvalRequest, fcc);
+
+                        Console.Write($"\nApprove '{fcc.Name}'? (yes/no): ");
+                        string? userInput = Console.ReadLine();
+                        bool approved = userInput?.ToUpperInvariant() is "YES" or "Y";
+
+                        ToolApprovalResponseContent approvalResponse = approvalRequest.CreateResponse(approved);
+
+                        if (approvalRequest.AdditionalProperties != null)
+                        {
+                            approvalResponse.AdditionalProperties = [];
+                            foreach (var kvp in approvalRequest.AdditionalProperties)
+                            {
+                                approvalResponse.AdditionalProperties[kvp.Key] = kvp.Value;
+                            }
+                        }
+
+                        approvalResponses.Add(approvalResponse);
+                        break;
+
+                    case TextContent textContent:
+                        Console.ForegroundColor = ConsoleColor.Cyan;
+                        Console.Write(textContent.Text);
+                        Console.ResetColor();
+                        break;
+
+                    case FunctionCallContent functionCall:
+                        Console.ForegroundColor = ConsoleColor.Green;
+                        Console.WriteLine($"[Tool Call - Name: {functionCall.Name}]");
+                        if (functionCall.Arguments is { } arguments)
+                        {
+                            Console.WriteLine($"  Parameters: {JsonSerializer.Serialize(arguments)}");
+                        }
+                        Console.ResetColor();
+                        break;
+
+                    case FunctionResultContent functionResult:
+                        Console.ForegroundColor = ConsoleColor.Magenta;
+                        Console.WriteLine($"[Tool Result: {functionResult.Result}]");
+                        Console.ResetColor();
+                        break;
+
+                    case ErrorContent error:
+                        Console.ForegroundColor = ConsoleColor.Red;
+                        Console.WriteLine($"[Error: {error.Message}]");
+                        Console.ResetColor();
+                        break;
+                }
+            }
+        }
+
+        AgentResponse response = chatResponseUpdates.ToAgentResponse();
+        messages.AddRange(response.Messages);
+        foreach (AIContent approvalResponse in approvalResponses)
+        {
+            messages.Add(new ChatMessage(ChatRole.Tool, [approvalResponse]));
+        }
+    }
+    while (approvalResponses.Count > 0);
+#pragma warning restore MEAI001
+
+    Console.WriteLine("\n");
+    Console.ForegroundColor = ConsoleColor.White;
+    Console.WriteLine("Ask another question (or type 'exit' to quit):");
+    Console.ResetColor();
+}
+
+#pragma warning disable MEAI001
+static void DisplayApprovalRequest(ToolApprovalRequestContent approvalRequest, FunctionCallContent fcc)
+{
+    Console.ForegroundColor = ConsoleColor.Yellow;
+    Console.WriteLine();
+    Console.WriteLine("============================================================");
+    Console.WriteLine("APPROVAL REQUIRED");
+    Console.WriteLine("============================================================");
+    Console.WriteLine($"Function: {fcc.Name}");
+
+    if (fcc.Arguments != null)
+    {
+        Console.WriteLine("Arguments:");
+        foreach (var arg in fcc.Arguments)
+        {
+            Console.WriteLine($"  {arg.Key} = {arg.Value}");
+        }
+    }
+
+    Console.WriteLine("============================================================");
+    Console.ResetColor();
+}
+#pragma warning restore MEAI001

dotnet/samples/02-agents/AGUI/Step04_HumanInLoop/Client/ServerFunctionApprovalClientAgent.cs

@@ -0,0 +1,265 @@
+// 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 server function approval requests and responses.
+/// Transforms between ToolApprovalRequestContent/ToolApprovalResponseContent
+/// and the server's request_approval tool call pattern.
+/// </summary>
+internal sealed class ServerFunctionApprovalClientAgent : DelegatingAIAgent
+{
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    public ServerFunctionApprovalClientAgent(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 approval messages, creating a new message list
+        var processedMessages = ProcessOutgoingServerFunctionApprovals(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 ProcessIncomingServerApprovalRequests(update, this._jsonSerializerOptions);
+        }
+    }
+
+#pragma warning disable MEAI001 // Type is for evaluation purposes only
+    private static FunctionResultContent ConvertApprovalResponseToToolResult(ToolApprovalResponseContent approvalResponse, JsonSerializerOptions jsonOptions)
+    {
+        return new FunctionResultContent(
+            callId: approvalResponse.RequestId,
+            result: JsonSerializer.SerializeToElement(
+                new ApprovalResponse
+                {
+                    ApprovalId = approvalResponse.RequestId,
+                    Approved = approvalResponse.Approved
+                },
+                jsonOptions));
+    }
+
+    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> ProcessOutgoingServerFunctionApprovals(
+        List<ChatMessage> messages,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        List<ChatMessage>? result = null;
+
+        Dictionary<string, ToolApprovalRequestContent> approvalRequests = [];
+        for (var messageIndex = 0; messageIndex < messages.Count; messageIndex++)
+        {
+            var message = messages[messageIndex];
+            List<AIContent>? transformedContents = null;
+
+            // Process each content item in the message
+            HashSet<string> approvalCalls = [];
+            for (var contentIndex = 0; contentIndex < message.Contents.Count; contentIndex++)
+            {
+                var content = message.Contents[contentIndex];
+
+                // Handle pending approval requests (transform to tool call)
+                if (content is ToolApprovalRequestContent approvalRequest &&
+                    approvalRequest.AdditionalProperties?.TryGetValue("original_function", out var originalFunction) == true &&
+                    originalFunction is FunctionCallContent original)
+                {
+                    approvalRequests[approvalRequest.RequestId] = approvalRequest;
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, contentIndex);
+                    transformedContents.Add(original);
+                }
+                // Handle pending approval responses (transform to tool result)
+                else if (content is ToolApprovalResponseContent approvalResponse &&
+                    approvalRequests.TryGetValue(approvalResponse.RequestId, out var correspondingRequest))
+                {
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, contentIndex);
+                    transformedContents.Add(ConvertApprovalResponseToToolResult(approvalResponse, jsonSerializerOptions));
+                    approvalRequests.Remove(approvalResponse.RequestId);
+                    correspondingRequest.AdditionalProperties?.Remove("original_function");
+                }
+                // Skip historical approval content
+                else if (content is FunctionCallContent { Name: "request_approval" } approvalCall)
+                {
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, contentIndex);
+                    approvalCalls.Add(approvalCall.CallId);
+                }
+                else if (content is FunctionResultContent functionResult &&
+                         approvalCalls.Contains(functionResult.CallId))
+                {
+                    transformedContents ??= CopyContentsUpToIndex(message.Contents, contentIndex);
+                    approvalCalls.Remove(functionResult.CallId);
+                }
+                else
+                {
+                    transformedContents?.Add(content);
+                }
+            }
+
+            if (transformedContents?.Count == 0)
+            {
+                continue;
+            }
+            else if (transformedContents != null)
+            {
+                // We made changes to contents, so use transformedContents
+                var newMessage = new ChatMessage(message.Role, transformedContents)
+                {
+                    AuthorName = message.AuthorName,
+                    MessageId = message.MessageId,
+                    CreatedAt = message.CreatedAt,
+                    RawRepresentation = message.RawRepresentation,
+                    AdditionalProperties = message.AdditionalProperties
+                };
+                result ??= CopyMessagesUpToIndex(messages, messageIndex);
+                result.Add(newMessage);
+            }
+            else
+            {
+                // We're already copying messages, so copy this unchanged message too
+                result?.Add(message);
+            }
+            // If result is null, we haven't made any changes yet, so keep processing
+        }
+
+        return result ?? messages;
+    }
+
+    private static AgentResponseUpdate ProcessIncomingServerApprovalRequests(
+        AgentResponseUpdate update,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        IList<AIContent>? updatedContents = null;
+        for (var i = 0; i < update.Contents.Count; i++)
+        {
+            var content = update.Contents[i];
+            if (content is FunctionCallContent { Name: "request_approval" } request)
+            {
+                updatedContents ??= [.. update.Contents];
+
+                // Serialize the function arguments as JsonElement
+                ApprovalRequest? approvalRequest;
+                if (request.Arguments?.TryGetValue("request", out var reqObj) == true &&
+                    reqObj is JsonElement je)
+                {
+                    approvalRequest = (ApprovalRequest?)je.Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(ApprovalRequest)));
+                }
+                else
+                {
+                    approvalRequest = null;
+                }
+
+                if (approvalRequest == null)
+                {
+                    throw new InvalidOperationException("Failed to deserialize approval request.");
+                }
+
+                var functionCallArgs = (Dictionary<string, object?>?)approvalRequest.FunctionArguments?
+                    .Deserialize(jsonSerializerOptions.GetTypeInfo(typeof(Dictionary<string, object?>)));
+
+                var approvalRequestContent = new ToolApprovalRequestContent(
+                    requestId: approvalRequest.ApprovalId,
+                    new FunctionCallContent(
+                        callId: approvalRequest.ApprovalId,
+                        name: approvalRequest.FunctionName,
+                        arguments: functionCallArgs));
+
+                approvalRequestContent.AdditionalProperties ??= [];
+                approvalRequestContent.AdditionalProperties["original_function"] = content;
+
+                updatedContents[i] = approvalRequestContent;
+            }
+        }
+
+        if (updatedContents is not null)
+        {
+            var chatUpdate = update.AsChatResponseUpdate();
+            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;
+    }
+}
+#pragma warning restore MEAI001
+
+namespace ServerFunctionApproval
+{
+    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 JsonElement? 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; }
+    }
+}