MCP/Approvals stabilization

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

@@ -18,18 +18,16 @@ namespace Microsoft.Extensions.AI;
 [JsonDerivedType(typeof(TextReasoningContent), typeDiscriminator: "reasoning")]
 [JsonDerivedType(typeof(UriContent), typeDiscriminator: "uri")]
 [JsonDerivedType(typeof(UsageContent), typeDiscriminator: "usage")]
+[JsonDerivedType(typeof(FunctionApprovalRequestContent), typeDiscriminator: "functionApprovalRequest")]
+[JsonDerivedType(typeof(FunctionApprovalResponseContent), typeDiscriminator: "functionApprovalResponse")]
+[JsonDerivedType(typeof(McpServerToolCallContent), typeDiscriminator: "mcpServerToolCall")]
+[JsonDerivedType(typeof(McpServerToolResultContent), typeDiscriminator: "mcpServerToolResult")]
 
 // 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. When [Experimental] is removed from these types,
 // these lines should be uncommented and the corresponding lines in AIJsonUtilities.CreateDefaultOptions
 // as well as the [JsonSerializable] attributes for them on the JsonContext should be removed.
-// [JsonDerivedType(typeof(FunctionApprovalRequestContent), typeDiscriminator: "functionApprovalRequest")]
-// [JsonDerivedType(typeof(FunctionApprovalResponseContent), typeDiscriminator: "functionApprovalResponse")]
-// [JsonDerivedType(typeof(McpServerToolCallContent), typeDiscriminator: "mcpServerToolCall")]
-// [JsonDerivedType(typeof(McpServerToolResultContent), typeDiscriminator: "mcpServerToolResult")]
-// [JsonDerivedType(typeof(McpServerToolApprovalRequestContent), typeDiscriminator: "mcpServerToolApprovalRequest")]
-// [JsonDerivedType(typeof(McpServerToolApprovalResponseContent), typeDiscriminator: "mcpServerToolApprovalResponse")]
 // [JsonDerivedType(typeof(CodeInterpreterToolCallContent), typeDiscriminator: "codeInterpreterToolCall")]
 // [JsonDerivedType(typeof(CodeInterpreterToolResultContent), typeDiscriminator: "codeInterpreterToolResult")]
 

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

@@ -2,42 +2,39 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
-/// Represents a request for user approval of a function call.
+/// Represents a request for approval before invoking a function call.
 /// </summary>
-[Experimental(DiagnosticIds.Experiments.AIFunctionApprovals, UrlFormat = DiagnosticIds.UrlFormat)]
-public sealed class FunctionApprovalRequestContent : UserInputRequestContent
+public sealed class FunctionApprovalRequestContent : InputRequestContent
 {
     /// <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>
+    /// <param name="requestId">The unique identifier that correlates this request with its corresponding response. This may differ from the <see cref="FunctionCallContent.CallId"/> of the specified <paramref name="functionCall"/>.</param>
+    /// <param name="functionCall">The function call that requires approval before execution.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="requestId"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="requestId"/> 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)
+    public FunctionApprovalRequestContent(string requestId, FunctionCallContent functionCall)
+        : base(requestId)
     {
         FunctionCall = Throw.IfNull(functionCall);
     }
 
     /// <summary>
-    /// Gets the function call that pre-invoke approval is required for.
+    /// Gets the function call that requires approval before execution.
     /// </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"/>.
+    /// Creates a <see cref="FunctionApprovalResponseContent"/> indicating whether the function call is approved or rejected.
     /// </summary>
     /// <param name="approved"><see langword="true"/> if the function call is approved; otherwise, <see langword="false"/>.</param>
     /// <param name="reason">An optional reason for the approval or rejection.</param>
-    /// <returns>The <see cref="FunctionApprovalResponseContent"/> representing the approval response.</returns>
-    public FunctionApprovalResponseContent CreateResponse(bool approved, string? reason = null) => new(Id, approved, FunctionCall) { Reason = reason };
+    /// <returns>The <see cref="FunctionApprovalResponseContent"/> correlated with this request.</returns>
+    public FunctionApprovalResponseContent CreateResponse(bool approved, string? reason = null) => new(RequestId, approved, FunctionCall) { Reason = reason };
 }

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

@@ -2,41 +2,38 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
 
 /// <summary>
-/// Represents a response to a function approval request.
+/// Represents a response to a <see cref="FunctionApprovalRequestContent"/>, indicating whether the function call was approved.
 /// </summary>
-[Experimental(DiagnosticIds.Experiments.AIFunctionApprovals, UrlFormat = DiagnosticIds.UrlFormat)]
-public sealed class FunctionApprovalResponseContent : UserInputResponseContent
+public sealed class FunctionApprovalResponseContent : InputResponseContent
 {
     /// <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="requestId">The unique identifier of the <see cref="FunctionApprovalRequestContent"/> associated with this response.</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>
+    /// <param name="functionCall">The function call that was subject to approval.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="requestId"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="requestId"/> 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)
+    public FunctionApprovalResponseContent(string requestId, bool approved, FunctionCallContent functionCall)
+        : base(requestId)
     {
         Approved = approved;
         FunctionCall = Throw.IfNull(functionCall);
     }
 
     /// <summary>
-    /// Gets a value indicating whether the user approved the request.
+    /// Gets a value indicating whether the function call was approved for execution.
     /// </summary>
     public bool Approved { get; }
 
     /// <summary>
-    /// Gets the function call for which approval was requested.
+    /// Gets the function call that was subject to approval.
     /// </summary>
     public FunctionCallContent FunctionCall { get; }
 

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

@@ -14,6 +14,7 @@ namespace Microsoft.Extensions.AI;
 /// Represents a function call request.
 /// </summary>
 [DebuggerDisplay("{DebuggerDisplay,nq}")]
+[JsonDerivedType(typeof(McpServerToolCallContent), "mcpServerToolCall")]
 public class FunctionCallContent : AIContent
 {
     /// <summary>

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

@@ -13,6 +13,7 @@ namespace Microsoft.Extensions.AI;
 /// Represents the result of a function call.
 /// </summary>
 [DebuggerDisplay("{DebuggerDisplay,nq}")]
+[JsonDerivedType(typeof(McpServerToolResultContent), "mcpServerToolResult")]
 public class FunctionResultContent : AIContent
 {
     /// <summary>

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/InputRequestContent.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.Text.Json.Serialization;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a request for input from the user or application.
+/// </summary>
+[JsonDerivedType(typeof(FunctionApprovalRequestContent), "functionApprovalRequest")]
+public class InputRequestContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="InputRequestContent"/> class.
+    /// </summary>
+    /// <param name="requestId">The unique identifier that correlates this request with its corresponding response.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="requestId"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="requestId"/> is empty or composed entirely of whitespace.</exception>
+    protected InputRequestContent(string requestId)
+    {
+        RequestId = Throw.IfNullOrWhitespace(requestId);
+    }
+
+    /// <summary>
+    /// Gets the unique identifier that correlates this request with its corresponding <see cref="InputResponseContent"/>.
+    /// </summary>
+    public string RequestId { get; }
+}

src/Libraries/Microsoft.Extensions.AI.Abstractions/Contents/InputResponseContent.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.Text.Json.Serialization;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents the response to an <see cref="InputRequestContent"/>.
+/// </summary>
+[JsonDerivedType(typeof(FunctionApprovalResponseContent), "functionApprovalResponse")]
+public class InputResponseContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="InputResponseContent"/> class.
+    /// </summary>
+    /// <param name="requestId">The unique identifier that correlates this response with its corresponding request.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="requestId"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="requestId"/> is empty or composed entirely of whitespace.</exception>
+    protected InputResponseContent(string requestId)
+    {
+        RequestId = Throw.IfNullOrWhitespace(requestId);
+    }
+
+    /// <summary>
+    /// Gets the unique identifier that correlates this response with its corresponding <see cref="InputRequestContent"/>.
+    /// </summary>
+    public string RequestId { get; }
+}

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

@@ -2,9 +2,6 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
@@ -13,44 +10,35 @@ namespace Microsoft.Extensions.AI;
 /// Represents a tool call request to a MCP server.
 /// </summary>
 /// <remarks>
+/// <para>
 /// This content type is used to represent an invocation of an MCP server tool by a hosted service.
-/// It is informational only.
+/// It is informational only and may appear as part of an approval request
+/// to convey what is being approved, or as a record of which MCP server tool was invoked.
+/// </para>
 /// </remarks>
-[Experimental(DiagnosticIds.Experiments.AIMcpServers, UrlFormat = DiagnosticIds.UrlFormat)]
-public sealed class McpServerToolCallContent : AIContent
+public sealed class McpServerToolCallContent : FunctionCallContent
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="McpServerToolCallContent"/> class.
     /// </summary>
     /// <param name="callId">The tool call ID.</param>
-    /// <param name="toolName">The tool name.</param>
+    /// <param name="name">The tool name.</param>
     /// <param name="serverName">The MCP server name that hosts the tool.</param>
-    /// <exception cref="ArgumentNullException"><paramref name="callId"/> or <paramref name="toolName"/> is <see langword="null"/>.</exception>
-    /// <exception cref="ArgumentException"><paramref name="callId"/> or <paramref name="toolName"/> is empty or composed entirely of whitespace.</exception>
-    public McpServerToolCallContent(string callId, string toolName, string? serverName)
+    /// <exception cref="ArgumentNullException"><paramref name="callId"/> or <paramref name="name"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException"><paramref name="callId"/> or <paramref name="name"/> is empty or composed entirely of whitespace.</exception>
+    /// <remarks>
+    /// This content is informational only and may appear as part of an approval request
+    /// to convey what is being approved, or as a record of which MCP server tool was invoked.
+    /// </remarks>
+    public McpServerToolCallContent(string callId, string name, string? serverName)
+        : base(Throw.IfNullOrWhitespace(callId), Throw.IfNullOrWhitespace(name))
     {
-        CallId = Throw.IfNullOrWhitespace(callId);
-        ToolName = Throw.IfNullOrWhitespace(toolName);
         ServerName = serverName;
+        InformationalOnly = true;
     }
 
-    /// <summary>
-    /// Gets the tool call ID.
-    /// </summary>
-    public string CallId { get; }
-
-    /// <summary>
-    /// Gets the name of the tool called.
-    /// </summary>
-    public string ToolName { get; }
-
     /// <summary>
     /// Gets the name of the MCP server that hosts the tool.
     /// </summary>
     public string? ServerName { get; }
-
-    /// <summary>
-    /// Gets or sets the arguments used for the tool call.
-    /// </summary>
-    public IReadOnlyDictionary<string, object?>? Arguments { get; set; }
 }

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

@@ -2,9 +2,6 @@
 // The .NET Foundation licenses this file to you under the MIT license.
 
 using System;
-using System.Collections.Generic;
-using System.Diagnostics.CodeAnalysis;
-using Microsoft.Shared.DiagnosticIds;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Extensions.AI;
@@ -16,8 +13,7 @@ namespace Microsoft.Extensions.AI;
 /// This content type is used to represent the result of an invocation of an MCP server tool by a hosted service.
 /// It is informational only.
 /// </remarks>
-[Experimental(DiagnosticIds.Experiments.AIMcpServers, UrlFormat = DiagnosticIds.UrlFormat)]
-public sealed class McpServerToolResultContent : AIContent
+public sealed class McpServerToolResultContent : FunctionResultContent
 {
     /// <summary>
     /// Initializes a new instance of the <see cref="McpServerToolResultContent"/> class.
@@ -26,17 +22,7 @@ public sealed class McpServerToolResultContent : AIContent
     /// <exception cref="ArgumentNullException"><paramref name="callId"/> is <see langword="null"/>.</exception>
     /// <exception cref="ArgumentException"><paramref name="callId"/> is empty or composed entirely of whitespace.</exception>
     public McpServerToolResultContent(string callId)
+        : base(Throw.IfNullOrWhitespace(callId), result: null)
     {
-        CallId = Throw.IfNullOrWhitespace(callId);
     }
-
-    /// <summary>
-    /// Gets the tool call ID.
-    /// </summary>
-    public string CallId { get; }
-
-    /// <summary>
-    /// Gets or sets the output of the tool call.
-    /// </summary>
-    public IList<AIContent>? Output { get; set; }
 }