Update PersistentAgentsChatClient to M.E.AI.Abstractions 9.10.0 (Azure#52852)

* Update PersistentAgentsChatClient to M.E.AI.Abstractions 9.9.1

- Expand AIFunction support to also include any AIFunctionDeclaration (AIFunction's base type)
- Add an extension AsAITool method that makes it easy to add any persistent ToolDefinition to ChatOptions.Tools.
- Add HostedMcpServerTool support.

* Update M.E.AI.Abstractions to 9.10.0

Author: stephentoub

eng/Packages.Data.props

@@ -214,7 +214,7 @@
   </ItemGroup>
 
   <ItemGroup Condition="$(MSBuildProjectName.Contains('Azure.AI.Agents.Persistent'))">
-    <PackageReference Update="Microsoft.Extensions.AI.Abstractions" Version="9.8.0"/>
+    <PackageReference Update="Microsoft.Extensions.AI.Abstractions" Version="9.10.1"/>
   </ItemGroup>
 
   <ItemGroup Condition="$(MSBuildProjectName.Contains('Azure.Projects'))">

sdk/ai/Azure.AI.Agents.Persistent/api/Azure.AI.Agents.Persistent.net8.0.cs

@@ -1596,6 +1596,7 @@ public PersistentAgentsClient(string endpoint, Azure.Core.TokenCredential creden
     }
     public static partial class PersistentAgentsClientExtensions
     {
+        public static Microsoft.Extensions.AI.AITool AsAITool(this Azure.AI.Agents.Persistent.ToolDefinition tool) { throw null; }
         public static Microsoft.Extensions.AI.IChatClient AsIChatClient(this Azure.AI.Agents.Persistent.PersistentAgentsClient client, string agentId, string? defaultThreadId = null) { throw null; }
     }
     public static partial class PersistentAgentsExtensions

sdk/ai/Azure.AI.Agents.Persistent/api/Azure.AI.Agents.Persistent.netstandard2.0.cs

@@ -1596,6 +1596,7 @@ public PersistentAgentsClient(string endpoint, Azure.Core.TokenCredential creden
     }
     public static partial class PersistentAgentsClientExtensions
     {
+        public static Microsoft.Extensions.AI.AITool AsAITool(this Azure.AI.Agents.Persistent.ToolDefinition tool) { throw null; }
         public static Microsoft.Extensions.AI.IChatClient AsIChatClient(this Azure.AI.Agents.Persistent.PersistentAgentsClient client, string agentId, string? defaultThreadId = null) { throw null; }
     }
     public static partial class PersistentAgentsExtensions

sdk/ai/Azure.AI.Agents.Persistent/src/Custom/PersistentAgentsChatClient.cs

@@ -15,6 +15,8 @@
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
 
+#pragma warning disable MEAI001 // MCP-related types are currently marked as [Experimental]
+
 namespace Azure.AI.Agents.Persistent
 {
     /// <summary>Represents an <see cref="IChatClient"/> for an Azure.AI.Agents.Persistent <see cref="PersistentAgentsClient"/>.</summary>
@@ -74,7 +76,7 @@ public virtual async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAs
             Argument.AssertNotNull(messages, nameof(messages));
 
             // Extract necessary state from messages and options.
-            (ThreadAndRunOptions runOptions, List<FunctionResultContent>? toolResults) =
+            (ThreadAndRunOptions runOptions, List<FunctionResultContent>? toolResults, List<McpServerToolApprovalResponseContent>? approvalResults) =
                 await CreateRunOptionsAsync(messages, options, cancellationToken).ConfigureAwait(false);
 
             // Get the thread ID.
@@ -100,15 +102,15 @@ public virtual async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAs
 
             // Submit the request.
             IAsyncEnumerable<StreamingUpdate> updates;
-            if (toolResults is not null &&
+            if ((toolResults is not null || approvalResults is not null) &&
                 threadRun is not null &&
-                ConvertFunctionResultsToToolOutput(toolResults, out List<ToolOutput>? toolOutputs) is { } toolRunId &&
+                ConvertFunctionResultsToToolOutput(toolResults, approvalResults, out List<ToolOutput> toolOutputs, out List<ToolApproval> toolApprovals) is { } toolRunId &&
                 toolRunId == threadRun.Id)
             {
                 // There's an active run and we have tool results to submit, so submit the results and continue streaming.
                 // This is going to ignore any additional messages in the run options, as we are only submitting tool outputs,
                 // but there doesn't appear to be a way to submit additional messages, and having such additional messages is rare.
-                updates = _client!.Runs.SubmitToolOutputsToStreamAsync(threadRun, toolOutputs, cancellationToken);
+                updates = _client!.Runs.SubmitToolOutputsToStreamAsync(threadRun, toolOutputs, toolApprovals, cancellationToken);
             }
             else
             {
@@ -191,13 +193,23 @@ threadRun is not null &&
                             }));
                         }
 
-                        if (ru is RequiredActionUpdate rau && rau.ToolCallId is string toolCallId && rau.FunctionName is string functionName)
+                        switch (ru)
                         {
-                            ruUpdate.Contents.Add(
-                                new FunctionCallContent(
+                            case RequiredActionUpdate rau when rau.ToolCallId is string toolCallId && rau.FunctionName is string functionName:
+                                ruUpdate.Contents.Add(new FunctionCallContent(
                                     JsonSerializer.Serialize([ru.Value.Id, toolCallId], AgentsChatClientJsonContext.Default.StringArray),
                                     functionName,
                                     JsonSerializer.Deserialize(rau.FunctionArguments, AgentsChatClientJsonContext.Default.IDictionaryStringObject)!));
+                                break;
+
+                            case SubmitToolApprovalUpdate stau:
+                                ruUpdate.Contents.Add(new McpServerToolApprovalRequestContent(
+                                    JsonSerializer.Serialize([stau.Value.Id, stau.ToolCallId], AgentsChatClientJsonContext.Default.StringArray),
+                                    new McpServerToolCallContent(stau.ToolCallId, stau.Name, stau.ServerLabel)
+                                    {
+                                        Arguments = JsonSerializer.Deserialize(stau.Arguments, AgentsChatClientJsonContext.Default.IReadOnlyDictionaryStringObject)!,
+                                    }));
+                                break;
                         }
 
                         yield return ruUpdate;
@@ -274,7 +286,7 @@ public void Dispose() { }
         /// Creates the <see cref="ThreadAndRunOptions"/> to use for the request and extracts any function result contents
         /// that need to be submitted as tool results.
         /// </summary>
-        private async ValueTask<(ThreadAndRunOptions RunOptions, List<FunctionResultContent>? ToolResults)> CreateRunOptionsAsync(
+        private async ValueTask<(ThreadAndRunOptions RunOptions, List<FunctionResultContent>? ToolResults, List<McpServerToolApprovalResponseContent>? ApprovalResults)> CreateRunOptionsAsync(
             IEnumerable<ChatMessage> messages, ChatOptions? options, CancellationToken cancellationToken)
         {
             // Create the options instance to populate, either a fresh or using one the caller provides.
@@ -324,7 +336,11 @@ public void Dispose() { }
                     {
                         switch (tool)
                         {
-                            case AIFunction aiFunction:
+                            case ToolDefinitionAITool rawTool:
+                                toolDefinitions.Add(rawTool.Tool);
+                                break;
+
+                            case AIFunctionDeclaration aiFunction:
                                 toolDefinitions.Add(new FunctionToolDefinition(
                                     aiFunction.Name,
                                     aiFunction.Description,
@@ -372,6 +388,44 @@ public void Dispose() { }
                             case HostedWebSearchTool webSearch when webSearch.AdditionalProperties?.TryGetValue("connectionId", out object? connectionId) is true:
                                 toolDefinitions.Add(new BingGroundingToolDefinition(new BingGroundingSearchToolParameters([new BingGroundingSearchConfiguration(connectionId!.ToString())])));
                                 break;
+
+                            case HostedMcpServerTool mcpTool:
+                                MCPToolDefinition mcp = new(mcpTool.ServerName, mcpTool.ServerAddress);
+
+                                if (mcpTool.AllowedTools is { Count: > 0 })
+                                {
+                                    foreach (string toolName in mcpTool.AllowedTools)
+                                    {
+                                        mcp.AllowedTools.Add(toolName);
+                                    }
+                                }
+
+                                MCPToolResource mcpResource = !string.IsNullOrEmpty(mcpTool.AuthorizationToken) ?
+                                    new(mcpTool.ServerName, new Dictionary<string, string>() { ["Authorization"] = $"Bearer {mcpTool.AuthorizationToken}" }) :
+                                    new(mcpTool.ServerName);
+
+                                switch (mcpTool.ApprovalMode)
+                                {
+                                    case HostedMcpServerToolAlwaysRequireApprovalMode:
+                                        mcpResource.RequireApproval = new MCPApproval("always");
+                                        break;
+
+                                    case HostedMcpServerToolNeverRequireApprovalMode:
+                                        mcpResource.RequireApproval = new MCPApproval("never");
+                                        break;
+
+                                    case HostedMcpServerToolRequireSpecificApprovalMode requireSpecific:
+                                        mcpResource.RequireApproval = new MCPApproval(new MCPApprovalPerTool()
+                                        {
+                                            Always = requireSpecific.AlwaysRequireApprovalToolNames is { Count: > 0 } alwaysRequireNames ? new(alwaysRequireNames) : null,
+                                            Never = requireSpecific.NeverRequireApprovalToolNames is { Count: > 0 } neverRequireNames ? new(neverRequireNames) : null,
+                                        });
+                                        break;
+                                }
+
+                                (toolResources ??= new()).Mcp.Add(mcpResource);
+                                toolDefinitions.Add(mcp);
+                                break;
                         }
                     }
 
@@ -453,6 +507,7 @@ public void Dispose() { }
             // and everything else as user messages.
             StringBuilder? instructions = null;
             List<FunctionResultContent>? functionResults = null;
+            List<McpServerToolApprovalResponseContent>? approvalResults = null;
 
             runOptions.ThreadOptions ??= new();
 
@@ -504,6 +559,10 @@ public void Dispose() { }
                             (functionResults ??= []).Add(result);
                             break;
 
+                        case McpServerToolApprovalResponseContent mcpApproval:
+                            (approvalResults ??= []).Add(mcpApproval);
+                            break;
+
                         default:
                             if (content.RawRepresentation is MessageInputContentBlock rawContent)
                             {
@@ -534,56 +593,104 @@ public void Dispose() { }
                 runOptions.OverrideInstructions = instructions.ToString();
             }
 
-            return (runOptions, functionResults);
+            return (runOptions, functionResults, approvalResults);
         }
 
         /// <summary>Convert <see cref="FunctionResultContent"/> instances to <see cref="ToolOutput"/> instances.</summary>
-        /// <param name="toolResults">The tool results to process.</param>
+        /// <param name="functionResults">The function results to process.</param>
+        /// <param name="approvalResults">The MCP tool approval results to process.</param>
         /// <param name="toolOutputs">The generated list of tool outputs, if any could be created.</param>
+        /// <param name="toolApprovals">The generated list of tool approvals, if any could be created.</param>
         /// <returns>The run ID associated with the corresponding function call requests.</returns>
-        private static string? ConvertFunctionResultsToToolOutput(List<FunctionResultContent>? toolResults, out List<ToolOutput>? toolOutputs)
+        private static string? ConvertFunctionResultsToToolOutput(
+            List<FunctionResultContent>? functionResults,
+            List<McpServerToolApprovalResponseContent>? approvalResults,
+            out List<ToolOutput> toolOutputs,
+            out List<ToolApproval> toolApprovals)
         {
             string? runId = null;
-            toolOutputs = null;
-            if (toolResults?.Count > 0)
+            toolOutputs = [];
+            toolApprovals = [];
+
+            if (functionResults?.Count > 0)
             {
-                foreach (FunctionResultContent frc in toolResults)
+                foreach (FunctionResultContent frc in functionResults)
                 {
-                    // When creating the FunctionCallContext, we created it with a CallId == [runId, callId].
-                    // We need to extract the run ID and ensure that the ToolOutput we send back to Azure
-                    // is only the call ID.
-                    string[]? runAndCallIDs;
-                    try
-                    {
-                        runAndCallIDs = JsonSerializer.Deserialize(frc.CallId, AgentsChatClientJsonContext.Default.StringArray);
-                    }
-                    catch
+                    if (TryParseRunAndCallIds(frc.CallId, out string? parsedRunId, out string? callId) &&
+                        (runId is null || runId == parsedRunId))
                     {
-                        continue;
+                        runId = parsedRunId;
+                        toolOutputs.Add(new(callId, frc.Result?.ToString() ?? string.Empty));
                     }
+                }
+            }
 
-                    if (runAndCallIDs is null ||
-                        runAndCallIDs.Length != 2 ||
-                        string.IsNullOrWhiteSpace(runAndCallIDs[0]) || // run ID
-                        string.IsNullOrWhiteSpace(runAndCallIDs[1]) || // call ID
-                        (runId is not null && runId != runAndCallIDs[0]))
+            if (approvalResults?.Count > 0)
+            {
+                foreach (McpServerToolApprovalResponseContent trc in approvalResults)
+                {
+                    if (TryParseRunAndCallIds(trc.Id, out string? parsedRunId, out string? callId) &&
+                        (runId is null || runId == parsedRunId))
                     {
-                        continue;
+                        runId = parsedRunId;
+                        toolApprovals.Add(new(callId, trc.Approved));
                     }
-
-                    runId = runAndCallIDs[0];
-                    (toolOutputs ??= []).Add(new(runAndCallIDs[1], frc.Result?.ToString() ?? string.Empty));
                 }
             }
 
             return runId;
+
+            static bool TryParseRunAndCallIds(string id, out string? runId, out string? callId)
+            {
+                // When creating the AIContent instances, we created it with a CallId == [runId, callId].
+                // We need to extract the run ID and ensure that the ToolOutput we send back to Azure
+                // is only the call ID.
+                runId = null;
+                callId = null;
+
+                string[]? runAndCallIDs;
+                try
+                {
+                    runAndCallIDs = JsonSerializer.Deserialize(id, AgentsChatClientJsonContext.Default.StringArray);
+                }
+                catch
+                {
+                    return false;
+                }
+
+                if (runAndCallIDs is null ||
+                    runAndCallIDs.Length != 2 ||
+                    string.IsNullOrWhiteSpace(runAndCallIDs[0]) || // run ID
+                    string.IsNullOrWhiteSpace(runAndCallIDs[1]))   // call ID
+                {
+                    return false;
+                }
+
+                runId = runAndCallIDs[0];
+                callId = runAndCallIDs[1];
+                return true;
+            }
+        }
+
+        /// <summary>
+        /// <see cref="AITool"/> type that allows for any <see cref="ToolDefinition"/> to be
+        /// passed into the <see cref="IChatClient"/> via <see cref="ChatOptions.Tools"/>.
+        /// </summary>
+        internal sealed class ToolDefinitionAITool(ToolDefinition tool) : AITool
+        {
+            public override string Name => tool.GetType().Name;
+            public ToolDefinition Tool => tool;
+            public override object? GetService(Type serviceType, object? serviceKey) =>
+                serviceKey is null && serviceType?.IsInstanceOfType(Tool) is true ? Tool :
+                base.GetService(serviceType!, serviceKey);
         }
 
         [JsonSerializable(typeof(JsonElement))]
         [JsonSerializable(typeof(JsonNode))]
         [JsonSerializable(typeof(JsonObject))]
         [JsonSerializable(typeof(string[]))]
         [JsonSerializable(typeof(IDictionary<string, object>))]
+        [JsonSerializable(typeof(IReadOnlyDictionary<string, object>))]
         private sealed partial class AgentsChatClientJsonContext : JsonSerializerContext;
     }
 }

sdk/ai/Azure.AI.Agents.Persistent/src/Custom/PersistentAgentsClientExtensions.cs

@@ -25,5 +25,31 @@ public static class PersistentAgentsClientExtensions
         /// <returns>An <see cref="IChatClient"/> instance configured to interact with the specified agent and thread.</returns>
         public static IChatClient AsIChatClient(this PersistentAgentsClient client, string agentId, string? defaultThreadId = null) =>
             new PersistentAgentsChatClient(client, agentId, defaultThreadId);
+
+        /// <summary>Creates an <see cref="AITool"/> to represent a <see cref="ToolDefinition"/>.</summary>
+        /// <param name="tool">The tool to wrap as an <see cref="AITool"/>.</param>
+        /// <returns>The <paramref name="tool"/> wrapped as an <see cref="AITool"/>.</returns>
+        /// <remarks>
+        /// <para>
+        /// The returned tool is only suitable for use with the <see cref="IChatClient"/> returned by
+        /// <see cref="AsIChatClient"/> (or <see cref="IChatClient"/>s that delegate
+        /// to such an instance). It is likely to be ignored by any other <see cref="IChatClient"/> implementation.
+        /// </para>
+        /// <para>
+        /// When a tool has a corresponding <see cref="AITool"/>-derived type already defined in Microsoft.Extensions.AI,
+        /// such as <see cref="AIFunction"/>, <see cref="HostedWebSearchTool"/>, or <see cref="HostedFileSearchTool"/>,
+        /// those types should be preferred instead of this method, as they are more portable,
+        /// capable of being respected by any <see cref="IChatClient"/> implementation. This method does not attempt to
+        /// map the supplied <see cref="ToolDefinition"/> to any of those types, it simply wraps it as-is:
+        /// the <see cref="IChatClient"/> returned by <see cref="AsIChatClient"/> will be able to unwrap the
+        /// <see cref="ToolDefinition"/> when it processes the list of tools.
+        /// </para>
+        /// </remarks>
+        public static AITool AsAITool(this ToolDefinition tool)
+        {
+            Argument.AssertNotNull(tool, nameof(tool));
+
+            return new PersistentAgentsChatClient.ToolDefinitionAITool(tool);
+        }
     }
 }