Add function approvals support (#6745)

- Adding an ApprovalRequiredAIFunction that can be used to decorate an AIFunction.
- Adding UserInputRequestContent and UserInputResponseContent base types to represent all user input.
- Adding FunctionApprovalRequestContent and FunctionApprovalResponseContent for function approvals.
- Updated FunctionInvokingChatClient with approval generation handling.

All new types are currently [Experimental].

Co-authored-by: Stephen Toub <stoub@microsoft.com>

Author: westey-m

src/Libraries/Microsoft.Extensions.AI.Abstractions/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## NOT YET RELEASED
 
 - Added non-invocable `AIFunctionDeclaration` (base class for `AIFunction`), `AIFunctionFactory.CreateDeclaration`, and `AIFunction.AsDeclarationOnly`.
+- Added `[Experimental]` support for user approval of function invocations via `ApprovalRequiredAIFunction`, `FunctionApprovalRequestContent`, and friends.
 
 ## 9.8.0
 

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/AIContent.cs

@@ -18,6 +18,13 @@ namespace Microsoft.Extensions.AI;
 [JsonDerivedType(typeof(TextReasoningContent), typeDiscriminator: "reasoning")]
 [JsonDerivedType(typeof(UriContent), typeDiscriminator: "uri")]
 [JsonDerivedType(typeof(UsageContent), typeDiscriminator: "usage")]
+
+// These should be added in once they're no longer [Experimental]. If they're included while still
+// experimental, any JsonSerializerContext that includes AIContent will incur errors about using
+// experimental types in its source generated files.
+// [JsonDerivedType(typeof(FunctionApprovalRequestContent), typeDiscriminator: "functionApprovalRequest")]
+// [JsonDerivedType(typeof(FunctionApprovalResponseContent), typeDiscriminator: "functionApprovalResponse")]
+
 public class AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/FunctionApprovalRequestContent.cs

@@ -0,0 +1,41 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a request for user approval of a function call.
+/// </summary>
+[Experimental("MEAI001")]
+public sealed class FunctionApprovalRequestContent : UserInputRequestContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FunctionApprovalRequestContent"/> class.
+    /// </summary>
+    /// <param name="id">The ID that uniquely identifies the function approval request/response pair.</param>
+    /// <param name="functionCall">The function call that requires user approval.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="id"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="id"/> is empty or composed entirely of whitespace.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="functionCall"/> is <see langword="null"/>.</exception>
+    public FunctionApprovalRequestContent(string id, FunctionCallContent functionCall)
+        : base(id)
+    {
+        FunctionCall = Throw.IfNull(functionCall);
+    }
+
+    /// <summary>
+    /// Gets the function call that pre-invoke approval is required for.
+    /// </summary>
+    public FunctionCallContent FunctionCall { get; }
+
+    /// <summary>
+    /// Creates a <see cref="FunctionApprovalResponseContent"/> to indicate whether the function call is approved or rejected based on the value of <paramref name="approved"/>.
+    /// </summary>
+    /// <param name="approved"><see langword="true"/> if the function call is approved; otherwise, <see langword="false"/>.</param>
+    /// <returns>The <see cref="FunctionApprovalResponseContent"/> representing the approval response.</returns>
+    public FunctionApprovalResponseContent CreateResponse(bool approved) => new(Id, approved, FunctionCall);
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/FunctionApprovalResponseContent.cs

@@ -0,0 +1,41 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a response to a function approval request.
+/// </summary>
+[Experimental("MEAI001")]
+public sealed class FunctionApprovalResponseContent : UserInputResponseContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FunctionApprovalResponseContent"/> class.
+    /// </summary>
+    /// <param name="id">The ID that uniquely identifies the function approval request/response pair.</param>
+    /// <param name="approved"><see langword="true"/> if the function call is approved; otherwise, <see langword="false"/>.</param>
+    /// <param name="functionCall">The function call that requires user approval.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="id"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="id"/> is empty or composed entirely of whitespace.</exception>
+    /// <exception cref="ArgumentNullException"><paramref name="functionCall"/> is <see langword="null"/>.</exception>
+    public FunctionApprovalResponseContent(string id, bool approved, FunctionCallContent functionCall)
+        : base(id)
+    {
+        Approved = approved;
+        FunctionCall = Throw.IfNull(functionCall);
+    }
+
+    /// <summary>
+    /// Gets a value indicating whether the user approved the request.
+    /// </summary>
+    public bool Approved { get; }
+
+    /// <summary>
+    /// Gets the function call for which approval was requested.
+    /// </summary>
+    public FunctionCallContent FunctionCall { get; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/UserInputRequestContent.cs

@@ -0,0 +1,31 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a request for user input.
+/// </summary>
+[Experimental("MEAI001")]
+public class UserInputRequestContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserInputRequestContent"/> class.
+    /// </summary>
+    /// <param name="id">The ID that uniquely identifies the user input request/response pair.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="id"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="id"/> is empty or composed entirely of whitespace.</exception>
+    protected UserInputRequestContent(string id)
+    {
+        Id = Throw.IfNullOrWhitespace(id);
+    }
+
+    /// <summary>
+    /// Gets the ID that uniquely identifies the user input request/response pair.
+    /// </summary>
+    public string Id { get; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/UserInputResponseContent.cs

@@ -0,0 +1,31 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents the response to a request for user input.
+/// </summary>
+[Experimental("MEAI001")]
+public class UserInputResponseContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UserInputResponseContent"/> class.
+    /// </summary>
+    /// <param name="id">The ID that uniquely identifies the user input request/response pair.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="id"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="id"/> is empty or composed entirely of whitespace.</exception>
+    protected UserInputResponseContent(string id)
+    {
+        Id = Throw.IfNullOrWhitespace(id);
+    }
+
+    /// <summary>
+    /// Gets the ID that uniquely identifies the user input request/response pair.
+    /// </summary>
+    public string Id { get; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Functions/ApprovalRequiredAIFunction.cs

@@ -0,0 +1,29 @@
+// Licensed to the .NET Foundation under one or more agreements.
+// The .NET Foundation licenses this file to you under the MIT license.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents an <see cref="AIFunction"/> that can be described to an AI service and invoked, but for which
+/// the invoker should obtain user approval before the function is actually invoked.
+/// </summary>
+/// <remarks>
+/// This class simply augments an <see cref="AIFunction"/> with an indication that approval is required before invocation.
+/// It does not enforce the requirement for user approval; it is the responsibility of the invoker to obtain that approval before invoking the function.
+/// </remarks>
+[Experimental("MEAI001")]
+public sealed class ApprovalRequiredAIFunction : DelegatingAIFunction
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ApprovalRequiredAIFunction"/> class.
+    /// </summary>
+    /// <param name="innerFunction">The <see cref="AIFunction"/> represented by this instance.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="innerFunction"/> is <see langword="null"/>.</exception>
+    public ApprovalRequiredAIFunction(AIFunction innerFunction)
+        : base(innerFunction)
+    {
+    }
+}

src/Libraries/Microsoft.Extensions.AI/CHANGELOG.md

@@ -3,6 +3,7 @@
 ## NOT YET RELEASED
 
 - Added `FunctionInvokingChatClient` support for non-invocable tools and `TerminateOnUnknownCalls` property.
+- Added support to `FunctionInvokingChatClient` for user approval of function invocations.
 - Updated the Open Telemetry instrumentation to conform to the latest 1.37.0 draft specification of the Semantic Conventions for Generative AI systems.
 - Fixed `GetResponseAsync<T>` to only look at the contents of the last message in the response.