Tool grouping

eng/packages/General.props

@@ -29,6 +29,7 @@
     <PackageVersion Include="System.CommandLine" Version="2.0.0-beta4.22272.1" />
     <PackageVersion Include="System.ComponentModel.Annotations" Version="5.0.0" />
     <PackageVersion Include="System.Memory" Version="4.5.5" />
+    <PackageVersion Include="System.Numerics.Tensors" Version="$(SystemNumericsTensorsVersion)" />
     <PackageVersion Include="System.Private.Uri" Version="4.3.2" />
     <PackageVersion Include="System.Runtime.Caching" Version="$(SystemRuntimeCachingVersion)" />
     <PackageVersion Include="System.Runtime.CompilerServices.Unsafe" Version="6.1.0" />

eng/packages/TestOnly.props

@@ -21,7 +21,6 @@
     <PackageVersion Include="Polly.Testing" Version="8.4.2" />
     <PackageVersion Include="StrongNamer" Version="0.2.5" />
     <PackageVersion Include="System.Configuration.ConfigurationManager" Version="$(SystemConfigurationConfigurationManagerVersion)" />
-    <PackageVersion Include="System.Numerics.Tensors" Version="$(SystemNumericsTensorsVersion)" />
     <PackageVersion Include="Verify.Xunit" Version="28.15.0" />
     <PackageVersion Include="Xunit.Combinatorial" Version="1.6.24" />
     <PackageVersion Include="xunit.extensibility.execution" Version="$(XUnitVersion)" />

src/Libraries/Microsoft.Extensions.AI.Abstractions/ToolReduction/IToolReductionStrategy.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.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a strategy capable of selecting a reduced set of tools for a chat request.
+/// </summary>
+/// <remarks>
+/// A tool reduction strategy is invoked prior to sending a request to an underlying <see cref="IChatClient"/>,
+/// enabling scenarios where a large tool catalog must be trimmed to fit provider limits or to improve model
+/// tool selection quality.
+/// <para>
+/// The implementation should return a non-<see langword="null"/> enumerable. Returning the original
+/// <see cref="ChatOptions.Tools"/> instance indicates no change. Returning a different enumerable indicates
+/// the caller may replace the existing tool list.
+/// </para>
+/// </remarks>
+[Experimental("MEAI001")]
+public interface IToolReductionStrategy
+{
+    /// <summary>
+    /// Selects the tools that should be included for a specific request.
+    /// </summary>
+    /// <param name="messages">The chat messages for the request. This is an <see cref="IEnumerable{T}"/> to avoid premature materialization.</param>
+    /// <param name="options">The chat options for the request (may be <see langword="null"/>).</param>
+    /// <param name="cancellationToken">A token to observe cancellation.</param>
+    /// <returns>
+    /// A (possibly reduced) enumerable of <see cref="AITool"/> instances. Must never be <see langword="null"/>.
+    /// Returning the same instance referenced by <paramref name="options"/>.<see cref="ChatOptions.Tools"/> signals no change.
+    /// </returns>
+    Task<IEnumerable<AITool>> SelectToolsForRequestAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options,
+        CancellationToken cancellationToken = default);
+}

src/Libraries/Microsoft.Extensions.AI/ChatCompletion/FunctionInvocationContext.cs

@@ -6,6 +6,8 @@
 using Microsoft.Shared.Collections;
 using Microsoft.Shared.Diagnostics;
 
+#pragma warning disable IDE0032 // Use auto property, suppressed until repo updates to C# 14
+
 namespace Microsoft.Extensions.AI;
 
 /// <summary>Provides context for an in-flight function invocation.</summary>

src/Libraries/Microsoft.Extensions.AI/ChatCompletion/FunctionInvokingChatClient.cs

@@ -284,7 +284,7 @@ public override async Task<ChatResponse> GetResponseAsync(
         bool lastIterationHadConversationId = false; // whether the last iteration's response had a ConversationId set
         int consecutiveErrorCount = 0;
 
-        (Dictionary<string, AITool>? toolMap, bool anyToolsRequireApproval) = CreateToolsMap(AdditionalTools, options?.Tools); // all available tools, indexed by name
+        (Dictionary<string, AITool>? toolMap, bool anyToolsRequireApproval) = await CreateToolsMapAsync([AdditionalTools, options?.Tools], cancellationToken); // all available tools, indexed by name
 
         if (HasAnyApprovalContent(originalMessages))
         {
@@ -424,7 +424,7 @@ public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseA
         List<ChatResponseUpdate> updates = []; // updates from the current response
         int consecutiveErrorCount = 0;
 
-        (Dictionary<string, AITool>? toolMap, bool anyToolsRequireApproval) = CreateToolsMap(AdditionalTools, options?.Tools); // all available tools, indexed by name
+        (Dictionary<string, AITool>? toolMap, bool anyToolsRequireApproval) = await CreateToolsMapAsync([AdditionalTools, options?.Tools], cancellationToken); // all available tools, indexed by name
 
         // This is a synthetic ID since we're generating the tool messages instead of getting them from
         // the underlying provider. When emitting the streamed chunks, it's perfectly valid for us to
@@ -624,7 +624,13 @@ public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseA
         AddUsageTags(activity, totalUsage);
     }
 
-    private static ChatResponseUpdate ConvertToolResultMessageToUpdate(ChatMessage message, string? conversationId, string? messageId) =>
+    /// <summary>
+    /// Converts a tool result <see cref="ChatMessage"/> into a <see cref="ChatResponseUpdate"/> for streaming scenarios.
+    /// </summary>
+    /// <param name="message">The tool result message.</param>
+    /// <param name="conversationId">The conversation ID.</param>
+    /// <param name="messageId">The message ID.</param>
+    internal static ChatResponseUpdate ConvertToolResultMessageToUpdate(ChatMessage message, string? conversationId, string? messageId) =>
         new()
         {
             AdditionalProperties = message.AdditionalProperties,
@@ -662,7 +668,7 @@ private static void AddUsageTags(Activity? activity, UsageDetails? usage)
     /// <param name="response">The most recent response being handled.</param>
     /// <param name="allTurnsResponseMessages">A list of all response messages received up until this point.</param>
     /// <param name="lastIterationHadConversationId">Whether the previous iteration's response had a conversation ID.</param>
-    private static void FixupHistories(
+    internal static void FixupHistories(
         IEnumerable<ChatMessage> originalMessages,
         ref IEnumerable<ChatMessage> messages,
         [NotNull] ref List<ChatMessage>? augmentedHistory,
@@ -722,26 +728,51 @@ private static void FixupHistories(
     /// The lists of tools to combine into a single dictionary. Tools from later lists are preferred
     /// over tools from earlier lists if they have the same name.
     /// </param>
-    private static (Dictionary<string, AITool>? ToolMap, bool AnyRequireApproval) CreateToolsMap(params ReadOnlySpan<IList<AITool>?> toolLists)
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
+    private static async ValueTask<(Dictionary<string, AITool>? ToolMap, bool AnyRequireApproval)> CreateToolsMapAsync(IList<AITool>?[] toolLists, CancellationToken cancellationToken)
     {
         Dictionary<string, AITool>? map = null;
         bool anyRequireApproval = false;
 
         foreach (var toolList in toolLists)
         {
-            if (toolList?.Count is int count && count > 0)
+            if (toolList is not null)
+            {
+                map ??= [];
+                var anyInListRequireApproval = await AddToolListAsync(map, toolList, cancellationToken).ConfigureAwait(false);
+                anyRequireApproval |= anyInListRequireApproval;
+            }
+        }
+
+        return (map, anyRequireApproval);
+
+        static async ValueTask<bool> AddToolListAsync(Dictionary<string, AITool> map, IEnumerable<AITool> tools, CancellationToken cancellationToken)
+        {
+#if NET
+            if (tools.TryGetNonEnumeratedCount(out var count) && count == 0)
             {
-                map ??= new(StringComparer.Ordinal);
-                for (int i = 0; i < count; i++)
+                return false;
+            }
+#endif
+            var anyRequireApproval = false;
+
+            foreach (var tool in tools)
+            {
+                if (tool is AIToolGroup toolGroup)
+                {
+                    var nestedTools = await toolGroup.GetToolsAsync(cancellationToken).ConfigureAwait(false);
+                    var nestedToolsRequireApproval = await AddToolListAsync(map, nestedTools, cancellationToken).ConfigureAwait(false);
+                    anyRequireApproval |= nestedToolsRequireApproval;
+                }
+                else
                 {
-                    AITool tool = toolList[i];
                     anyRequireApproval |= tool.GetService<ApprovalRequiredAIFunction>() is not null;
                     map[tool.Name] = tool;
                 }
             }
-        }
 
-        return (map, anyRequireApproval);
+            return anyRequireApproval;
+        }
     }
 
     /// <summary>

src/Libraries/Microsoft.Extensions.AI/Microsoft.Extensions.AI.csproj

@@ -44,6 +44,7 @@
     <PackageReference Include="Microsoft.Extensions.Caching.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
+    <PackageReference Include="System.Numerics.Tensors" />
   </ItemGroup>
 
   <ItemGroup Condition="'$(TargetFrameworkIdentifier)' != '.NETCoreApp'">

src/Libraries/Microsoft.Extensions.AI/ToolGrouping/AIToolGroup.cs

@@ -0,0 +1,90 @@
+// 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.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Represents a logical grouping of tools that can be dynamically expanded.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A <see cref="AIToolGroup"/> is an <see cref="AITool"/> that supplies an ordered list of <see cref="AITool"/> instances
+/// via the <see cref="GetToolsAsync"/> method. This enables grouping tools together for organizational purposes
+/// and allows for dynamic tool selection based on context.
+/// </para>
+/// <para>
+/// Tool groups can be used independently or in conjunction with <see cref="ToolGroupingChatClient"/> to implement
+/// hierarchical tool selection, where groups are initially collapsed and can be expanded on demand.
+/// </para>
+/// </remarks>
+[Experimental("MEAI001")]
+public abstract class AIToolGroup : AITool
+{
+    private readonly string _name;
+    private readonly string _description;
+
+    /// <summary>Initializes a new instance of the <see cref="AIToolGroup"/> class.</summary>
+    /// <param name="name">Group name (identifier used by the expansion function).</param>
+    /// <param name="description">Human readable description of the group.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="name"/> is <see langword="null"/>.</exception>
+    protected AIToolGroup(string name, string description)
+    {
+        _name = Throw.IfNull(name);
+        _description = Throw.IfNull(description);
+    }
+
+    /// <summary>Gets the group name.</summary>
+    public override string Name => _name;
+
+    /// <summary>Gets the group description.</summary>
+    public override string Description => _description;
+
+    /// <summary>Creates a tool group with a static list of tools.</summary>
+    /// <param name="name">Group name (identifier used by the expansion function).</param>
+    /// <param name="description">Human readable description of the group.</param>
+    /// <param name="tools">Ordered tools contained in the group.</param>
+    /// <returns>An <see cref="AIToolGroup"/> instance containing the specified tools.</returns>
+    /// <exception cref="ArgumentNullException"><paramref name="name"/> or <paramref name="tools"/> is <see langword="null"/>.</exception>
+    public static AIToolGroup Create(string name, string description, IReadOnlyList<AITool> tools)
+    {
+        _ = Throw.IfNull(name);
+        _ = Throw.IfNull(tools);
+        return new StaticAIToolGroup(name, description, tools);
+    }
+
+    /// <summary>
+    /// Asynchronously retrieves the ordered list of tools belonging to this group.
+    /// </summary>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests.</param>
+    /// <returns>A <see cref="ValueTask{TResult}"/> representing the asynchronous operation, containing the ordered list of tools in the group.</returns>
+    /// <remarks>
+    /// The returned list may contain other <see cref="AIToolGroup"/> instances, enabling hierarchical tool organization.
+    /// Implementations should ensure the returned list is stable and deterministic for a given group instance.
+    /// </remarks>
+    public abstract ValueTask<IReadOnlyList<AITool>> GetToolsAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>A tool group implementation that returns a static list of tools.</summary>
+    private sealed class StaticAIToolGroup : AIToolGroup
+    {
+        private readonly IReadOnlyList<AITool> _tools;
+
+        public StaticAIToolGroup(string name, string description, IReadOnlyList<AITool> tools)
+            : base(name, description)
+        {
+            _tools = tools;
+        }
+
+        public override ValueTask<IReadOnlyList<AITool>> GetToolsAsync(CancellationToken cancellationToken = default)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+            return new ValueTask<IReadOnlyList<AITool>>(_tools);
+        }
+    }
+}

src/Libraries/Microsoft.Extensions.AI/ToolGrouping/ChatClientBuilderToolGroupingExtensions.cs

@@ -0,0 +1,26 @@
+// 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>Builder extensions for <see cref="ToolGroupingChatClient"/>.</summary>
+[Experimental("MEAI001")]
+public static class ChatClientBuilderToolGroupingExtensions
+{
+    /// <summary>Adds tool grouping middleware to the pipeline.</summary>
+    /// <param name="builder">Chat client builder.</param>
+    /// <param name="configure">Configuration delegate.</param>
+    /// <returns>The builder for chaining.</returns>
+    /// <remarks>Should appear before tool reduction and function invocation middleware.</remarks>
+    public static ChatClientBuilder UseToolGrouping(this ChatClientBuilder builder, Action<ToolGroupingOptions>? configure = null)
+    {
+        _ = Throw.IfNull(builder);
+        var options = new ToolGroupingOptions();
+        configure?.Invoke(options);
+        return builder.Use(inner => new ToolGroupingChatClient(inner, options));
+    }
+}