.NET: ADR: Supporting user approvals

dotnet/Directory.Packages.props

@@ -31,7 +31,7 @@
     <PackageVersion Include="Swashbuckle.AspNetCore.SwaggerUI" Version="9.0.3" />
     <!-- System.* -->
     <PackageVersion Include="System.Linq.Async" Version="6.0.3" />
-    <PackageVersion Include="System.Net.ServerSentEvents" Version="9.0.7" />
+    <PackageVersion Include="System.Net.ServerSentEvents" Version="10.0.0-preview.6.25358.103" />
     <PackageVersion Include="System.Text.Json" Version="9.0.7" />
     <PackageVersion Include="System.Diagnostics.DiagnosticSource" Version="9.0.7" />
     <PackageVersion Include="System.Threading.Channels" Version="9.0.7" />
@@ -43,7 +43,7 @@
     <PackageVersion Include="OpenTelemetry.Extensions.Hosting" Version="1.12.0" />
     <!-- Microsoft.Extensions.* -->
     <PackageVersion Include="Microsoft.Bcl.HashCode" Version="6.0.0" />
-    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="9.0.7" />
+    <PackageVersion Include="Microsoft.Bcl.AsyncInterfaces" Version="10.0.0-preview.6.25358.103" />
     <PackageVersion Include="Microsoft.Extensions.AI" Version="9.7.1" />
     <PackageVersion Include="Microsoft.Extensions.AI.OpenAI" Version="9.7.1-preview.1.25365.4" />
     <PackageVersion Include="Microsoft.Extensions.AI.Abstractions" Version="9.7.1" />
@@ -65,6 +65,8 @@
     <PackageVersion Include="Microsoft.Agents.CopilotStudio.Client" Version="1.1.151" />
     <!-- Identity -->
     <PackageVersion Include="Microsoft.Identity.Client.Extensions.Msal" Version="4.74.1" />
+    <!-- Other -->
+    <PackageVersion Include="ModelContextProtocol" Version="0.3.0-preview.2" />
     <!-- Test -->
     <PackageVersion Include="FluentAssertions" Version="8.5.0" />
     <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.14.1" />

dotnet/agent-framework-dotnet.slnx

@@ -125,6 +125,9 @@
     <Project Path="src/Microsoft.Extensions.AI.Agents.Runtime.Storage.CosmosDB/Microsoft.Extensions.AI.Agents.Runtime.Storage.CosmosDB.csproj" />
     <Project Path="src/Microsoft.Extensions.AI.Agents.Runtime/Microsoft.Extensions.AI.Agents.Runtime.csproj" />
     <Project Path="src/Microsoft.Extensions.AI.Agents/Microsoft.Extensions.AI.Agents.csproj" />
+    <Project Path="src/Microsoft.Extensions.AI.ModelContextProtocol/Microsoft.Extensions.AI.ModelContextProtocol.csproj" Id="4859a869-0c6b-417d-b6d8-6ccbcb60786c">
+      <BuildType Solution="Publish|*" Project="Release" />
+    </Project>
   </Folder>
   <Folder Name="/UnitTests/">
     <Project Path="tests/Microsoft.Agents.Orchestration.UnitTests/Microsoft.Agents.Orchestration.UnitTests.csproj" />

dotnet/samples/GettingStarted/GettingStarted.csproj

@@ -45,6 +45,7 @@
     <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.Agents.AzureAI\Microsoft.Extensions.AI.Agents.AzureAI.csproj" />
     <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.Agents.OpenAI\Microsoft.Extensions.AI.Agents.OpenAI.csproj" />
     <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.Agents\Microsoft.Extensions.AI.Agents.csproj" />
+    <ProjectReference Include="..\..\src\Microsoft.Extensions.AI.ModelContextProtocol\Microsoft.Extensions.AI.ModelContextProtocol.csproj" />
   </ItemGroup>
 
   <ItemGroup>

dotnet/samples/GettingStarted/Steps/Step02_ChatClientAgent_UsingFunctionTools.cs

@@ -3,6 +3,8 @@
 using System.ComponentModel;
 using Microsoft.Extensions.AI;
 using Microsoft.Extensions.AI.Agents;
+using Microsoft.Extensions.AI.ModelContextProtocol;
+using Microsoft.Extensions.DependencyInjection;
 
 namespace Steps;
 
@@ -114,6 +116,96 @@ async Task RunAgentAsync(string input)
         await base.AgentCleanUpAsync(provider, agent, thread);
     }
 
+    [Theory]
+    [InlineData(ChatClientProviders.AzureOpenAI)]
+    [InlineData(ChatClientProviders.AzureAIAgentsPersistent)]
+    [InlineData(ChatClientProviders.OpenAIAssistant)]
+    [InlineData(ChatClientProviders.OpenAIChatCompletion)]
+    [InlineData(ChatClientProviders.OpenAIResponses)]
+    public async Task ApprovalsWithTools(ChatClientProviders provider)
+    {
+        // Creating a MenuTools instance to be used by the agent.
+        var menuTools = new MenuTools();
+
+        // Define the options for the chat client agent.
+        var agentOptions = new ChatClientAgentOptions(
+            name: "Host",
+            instructions: "Answer questions about the menu",
+            tools: [
+                AIFunctionFactory.Create(menuTools.GetMenu),
+                new ApprovalRequiredAIFunction(AIFunctionFactory.Create(menuTools.GetSpecials)),
+                AIFunctionFactory.Create(menuTools.GetItemPrice),
+                new HostedMcpServerTool("MyService", new Uri("https://mcp-server.example.com"))
+                {
+                    AllowedTools = ["add"],
+                    ApprovalMode = HostedMcpServerToolApprovalMode.AlwaysRequire,
+                }
+            ]);
+
+        // Create the server-side agent Id when applicable (depending on the provider).
+        agentOptions.Id = await base.AgentCreateAsync(provider, agentOptions);
+
+        // Get the chat client to use for the agent.
+        using var chatClient = base.GetChatClient(provider, agentOptions);
+
+        var chatBuilder = chatClient.AsBuilder();
+        if (chatClient.GetService<HostedMCPChatClient>() is null)
+        {
+            chatBuilder.Use((IChatClient innerClient, IServiceProvider services) =>
+            {
+                return new HostedMCPChatClient(innerClient);
+            });
+        }
+        if (chatClient.GetService<FunctionInvokingChatClientWithBuiltInApprovals>() is null)
+        {
+            chatBuilder.Use((IChatClient innerClient, IServiceProvider services) =>
+            {
+                return new FunctionInvokingChatClientWithBuiltInApprovals(innerClient, null, services);
+            });
+        }
+        using var chatClientWithMCPAndApprovals = chatBuilder.Build();
+
+        // Define the agent
+        var agent = new ChatClientAgent(chatClientWithMCPAndApprovals, agentOptions);
+
+        // Create the chat history thread to capture the agent interaction.
+        var thread = agent.GetNewThread();
+
+        // Respond to user input, invoking functions where appropriate.
+        await RunAgentAsync("What is the special soup and its price?");
+        await RunAgentAsync("What is the special drink?");
+        await RunAgentAsync("What is 2 + 2?");
+
+        async Task RunAgentAsync(string input)
+        {
+            this.WriteUserMessage(input);
+            var response = await agent.RunAsync(input, thread);
+            this.WriteResponseOutput(response);
+
+            var userInputRequests = response.UserInputRequests.ToList();
+
+            // Loop until all user input requests are handled.
+            while (userInputRequests.Count > 0)
+            {
+                List<ChatMessage> nextIterationMessages = userInputRequests?.Select((request) => request switch
+                {
+                    FunctionApprovalRequestContent functionApprovalRequest when functionApprovalRequest.FunctionCall.Name == "GetSpecials" || functionApprovalRequest.FunctionCall.Name == "add" => functionApprovalRequest.Approve(),
+                    FunctionApprovalRequestContent functionApprovalRequest => functionApprovalRequest.Reject(),
+                    _ => throw new NotSupportedException($"Unsupported request type: {request.GetType().Name}")
+                })?.ToList() ?? [];
+
+                nextIterationMessages.ForEach(x => Console.WriteLine($"Approval for the {(x.Contents[0] as FunctionApprovalResponseContent)?.FunctionCall.Name} function call is set to {(x.Contents[0] as FunctionApprovalResponseContent)?.Approved}."));
+
+                response = await agent.RunAsync(nextIterationMessages, thread);
+                this.WriteResponseOutput(response);
+                userInputRequests = response.UserInputRequests.ToList();
+            }
+        }
+
+        // Clean up the server-side agent after use when applicable (depending on the provider).
+        await base.AgentCleanUpAsync(provider, agent, thread);
+    }
+
     private sealed class MenuTools
     {
         [Description("Get the full menu items.")]

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/AgentRunResponse.cs

@@ -6,6 +6,8 @@
 #endif
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+
 #if NET9_0_OR_GREATER
 using System.Text;
 #endif
@@ -82,6 +84,13 @@ public IList<ChatMessage> Messages
     [JsonIgnore]
     public string Text => this._messages?.ConcatText() ?? string.Empty;
 
+    /// <summary>Gets or sets the user input requests associated with the response.</summary>
+    /// <remarks>
+    /// This property concatenates all <see cref="UserInputRequestContent"/> instances in the response.
+    /// </remarks>
+    [JsonIgnore]
+    public IEnumerable<UserInputRequestContent> UserInputRequests => this._messages?.SelectMany(x => x.Contents).OfType<UserInputRequestContent>() ?? Array.Empty<UserInputRequestContent>();
+
     /// <summary>Gets or sets the ID of the agent that produced the response.</summary>
     public string? AgentId { get; set; }
 

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/AgentRunResponseUpdate.cs

@@ -4,6 +4,7 @@
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.Diagnostics.CodeAnalysis;
+using System.Linq;
 using System.Text.Json.Serialization;
 using Microsoft.Shared.Diagnostics;
 
@@ -92,6 +93,13 @@ public string? AuthorName
     [JsonIgnore]
     public string Text => this._contents is not null ? this._contents.ConcatText() : string.Empty;
 
+    /// <summary>Gets or sets the user input requests associated with the response.</summary>
+    /// <remarks>
+    /// This property concatenates all <see cref="UserInputRequestContent"/> instances in the response.
+    /// </remarks>
+    [JsonIgnore]
+    public IEnumerable<UserInputRequestContent> UserInputRequests => this._contents?.OfType<UserInputRequestContent>() ?? Array.Empty<UserInputRequestContent>();
+
     /// <summary>Gets or sets the agent run response update content items.</summary>
     [AllowNull]
     public IList<AIContent> Contents

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI.Contents/FunctionApprovalRequestContent.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a request for user approval of a function call.
+/// </summary>
+public class FunctionApprovalRequestContent : UserInputRequestContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FunctionApprovalRequestContent"/> class.
+    /// </summary>
+    /// <param name="approvalId">The ID to uniquely identify the user input request/response pair.</param>
+    /// <param name="functionCall">The function call that requires user approval.</param>
+    public FunctionApprovalRequestContent(string approvalId, FunctionCallContent functionCall)
+        : base(approvalId)
+    {
+        this.FunctionCall = Throw.IfNull(functionCall);
+    }
+
+    /// <summary>
+    /// Gets or sets the function call that pre-invoke approval is required for.
+    /// </summary>
+    public FunctionCallContent FunctionCall { get; }
+
+    /// <summary>
+    /// Creates a <see cref="ChatMessage"/> representing an approval response.
+    /// </summary>
+    /// <returns>The <see cref="ChatMessage"/> representing the approval response.</returns>
+    public ChatMessage Approve()
+    {
+        return new ChatMessage(ChatRole.User, [new FunctionApprovalResponseContent(this.Id, true, this.FunctionCall)]);
+    }
+
+    /// <summary>
+    /// Creates a <see cref="ChatMessage"/> representing a rejection response.
+    /// </summary>
+    /// <returns>The <see cref="ChatMessage"/> representing the rejection response.</returns>
+    public ChatMessage Reject()
+    {
+        return new ChatMessage(ChatRole.User, [new FunctionApprovalResponseContent(this.Id, false, this.FunctionCall)]);
+    }
+}

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI.Contents/FunctionApprovalResponseContent.cs

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a response to a function approval request.
+/// </summary>
+public class FunctionApprovalResponseContent : UserInputResponseContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FunctionApprovalResponseContent"/> class.
+    /// </summary>
+    /// <param name="approvalId">The ID to uniquely identify the user input request/response pair.</param>
+    /// <param name="approved">Indicates whether the request was approved.</param>
+    /// <param name="functionCall">The function call that requires user approval.</param>
+    public FunctionApprovalResponseContent(string approvalId, bool approved, FunctionCallContent functionCall)
+        : base(approvalId)
+    {
+        this.Approved = approved;
+        this.FunctionCall = Throw.IfNull(functionCall);
+    }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the user approved the request.
+    /// </summary>
+    public bool Approved { get; set; }
+
+    /// <summary>
+    /// Gets or sets the function call that pre-invoke approval is required for.
+    /// </summary>
+    public FunctionCallContent FunctionCall { get; }
+}

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI.Contents/UserInputRequestContent.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Base class for user input request content.
+/// </summary>
+public abstract class UserInputRequestContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserInputRequestContent"/> class.
+    /// </summary>
+    /// <param name="id">The ID to uniquely identify the user input request/response pair.</param>
+    protected UserInputRequestContent(string id)
+    {
+        Id = Throw.IfNullOrWhitespace(id);
+    }
+
+    /// <summary>
+    /// Gets the ID to uniquely identify the user input request/response pair.
+    /// </summary>
+    public string Id { get; }
+}

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI.Contents/UserInputResponseContent.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Base class for user input response content.
+/// </summary>
+public abstract class UserInputResponseContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserInputRequestContent"/> class.
+    /// </summary>
+    /// <param name="id">The ID to uniquely identify the user input request/response pair.</param>
+    protected UserInputResponseContent(string id)
+    {
+        Id = Throw.IfNullOrWhitespace(id);
+    }
+
+    /// <summary>
+    /// Gets the ID to uniquely identify the user input request/response pair.
+    /// </summary>
+    public string Id { get; }
+}

dotnet/src/Microsoft.Extensions.AI.Agents.Abstractions/MEAI/HostedMcpServerTool.cs

@@ -0,0 +1,61 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a hosted MCP server tool that can be specified to an AI service.
+/// </summary>
+public class HostedMcpServerTool : AITool
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="HostedMcpServerTool"/> class.
+    /// </summary>
+    /// <param name="serverName">The name of the remote MCP server.</param>
+    /// <param name="url">The URL of the remote MCP server.</param>
+    public HostedMcpServerTool(string serverName, Uri url)
+    {
+        ServerName = Throw.IfNullOrWhitespace(serverName);
+        Url = Throw.IfNull(url);
+    }
+
+    /// <summary>
+    /// Gets the name of the remote MCP server that is used to identify it.
+    /// </summary>
+    public string ServerName { get; }
+
+    /// <summary>
+    /// Gets the URL of the remote MCP server.
+    /// </summary>
+    public Uri Url { get; }
+
+    /// <summary>
+    /// Gets or sets the description of the remote MCP server, used to provide more context to the AI service.
+    /// </summary>
+    public string? ServerDescription { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of tools allowed to be used by the AI service.
+    /// </summary>
+    public IList<string>? AllowedTools { get; set; }
+
+    /// <summary>
+    /// Gets or sets the approval mode that indicates when the AI service should require user approval for tool calls to the remote MCP server.
+    /// </summary>
+    /// <remarks>
+    /// You can set this property to <see cref="HostedMcpServerToolApprovalMode.AlwaysRequire"/> to require approval for all tool calls,
+    /// or to <see cref="HostedMcpServerToolApprovalMode.NeverRequire"/> to never require approval.
+    /// </remarks>
+    public HostedMcpServerToolApprovalMode? ApprovalMode { get; set; }
+
+    /// <summary>
+    /// Gets or sets the HTTP headers that the AI service should use when making tool calls to the remote MCP server.
+    /// </summary>
+    /// <remarks>
+    /// This property is useful for specifying the authentication header or other headers required by the MCP server.
+    /// </remarks>
+    public IDictionary<string, string>? Headers { get; set; }
+}