.NET: Introduce ToolResultReductionStrategy

Author: arjendev

dotnet/src/Microsoft.Agents.AI/Compaction/ToolResultCompactionStrategy.cs

@@ -3,10 +3,7 @@
 using System;
 using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
-using System.Threading;
-using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
-using Microsoft.Extensions.Logging;
 using Microsoft.Shared.DiagnosticIds;
 
 namespace Microsoft.Agents.AI.Compaction;
@@ -37,16 +34,17 @@ namespace Microsoft.Agents.AI.Compaction;
 /// built-in default and can be reused inside a custom formatter when needed.
 /// </para>
 /// <para>
-/// <see cref="MinimumPreservedGroups"/> is a hard floor: even if the <see cref="CompactionStrategy.Target"/>
-/// has not been reached, compaction will not touch the last <see cref="MinimumPreservedGroups"/> non-system groups.
+/// <see cref="ToolResultStrategyBase.MinimumPreservedGroups"/> is a hard floor: even if the
+/// <see cref="CompactionStrategy.Target"/> has not been reached, compaction will not touch the last
+/// <see cref="ToolResultStrategyBase.MinimumPreservedGroups"/> non-system groups.
 /// </para>
 /// <para>
 /// The <see cref="CompactionTrigger"/> predicate controls when compaction proceeds. Use
 /// <see cref="CompactionTriggers"/> for common trigger conditions such as token thresholds.
 /// </para>
 /// </remarks>
 [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
-public sealed class ToolResultCompactionStrategy : CompactionStrategy
+public sealed class ToolResultCompactionStrategy : ToolResultStrategyBase
 {
     /// <summary>
     /// The default minimum number of most-recent non-system groups to preserve.
@@ -73,17 +71,10 @@ public ToolResultCompactionStrategy(
         CompactionTrigger trigger,
         int minimumPreservedGroups = DefaultMinimumPreserved,
         CompactionTrigger? target = null)
-        : base(trigger, target)
+        : base(trigger, minimumPreservedGroups, target)
     {
-        this.MinimumPreservedGroups = EnsureNonNegative(minimumPreservedGroups);
     }
 
-    /// <summary>
-    /// Gets the minimum number of most-recent non-system groups that are always preserved.
-    /// This is a hard floor that compaction cannot exceed, regardless of the target condition.
-    /// </summary>
-    public int MinimumPreservedGroups { get; }
-
     /// <summary>
     /// An optional custom formatter that converts a <see cref="CompactionMessageGroup"/> into a summary string.
     /// When <see langword="null"/>, <see cref="DefaultToolCallFormatter"/> is used, which produces a YAML-like
@@ -92,73 +83,15 @@ public ToolResultCompactionStrategy(
     public Func<CompactionMessageGroup, string>? ToolCallFormatter { get; init; }
 
     /// <inheritdoc/>
-    protected override ValueTask<bool> CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken)
+    protected override (CompactionGroupKind Kind, List<ChatMessage> Messages, string ExcludeReason)
+        TransformToolGroup(CompactionMessageGroup group)
     {
-        // Identify protected groups: the N most-recent non-system, non-excluded groups
-        List<int> nonSystemIncludedIndices = [];
-        for (int i = 0; i < index.Groups.Count; i++)
-        {
-            CompactionMessageGroup group = index.Groups[i];
-            if (!group.IsExcluded && group.Kind != CompactionGroupKind.System)
-            {
-                nonSystemIncludedIndices.Add(i);
-            }
-        }
-
-        int protectedStart = EnsureNonNegative(nonSystemIncludedIndices.Count - this.MinimumPreservedGroups);
-        HashSet<int> protectedGroupIndices = [];
-        for (int i = protectedStart; i < nonSystemIncludedIndices.Count; i++)
-        {
-            protectedGroupIndices.Add(nonSystemIncludedIndices[i]);
-        }
-
-        // Collect eligible tool groups in order (oldest first)
-        List<int> eligibleIndices = [];
-        for (int i = 0; i < index.Groups.Count; i++)
-        {
-            CompactionMessageGroup group = index.Groups[i];
-            if (!group.IsExcluded && group.Kind == CompactionGroupKind.ToolCall && !protectedGroupIndices.Contains(i))
-            {
-                eligibleIndices.Add(i);
-            }
-        }
-
-        if (eligibleIndices.Count == 0)
-        {
-            return new ValueTask<bool>(false);
-        }
-
-        // Collapse one tool group at a time from oldest, re-checking target after each
-        bool compacted = false;
-        int offset = 0;
-
-        for (int e = 0; e < eligibleIndices.Count; e++)
-        {
-            int idx = eligibleIndices[e] + offset;
-            CompactionMessageGroup group = index.Groups[idx];
-
-            string summary = (this.ToolCallFormatter ?? DefaultToolCallFormatter).Invoke(group);
+        string summary = (this.ToolCallFormatter ?? DefaultToolCallFormatter).Invoke(group);
 
-            // Exclude the original group and insert a collapsed replacement
-            group.IsExcluded = true;
-            group.ExcludeReason = $"Collapsed by {nameof(ToolResultCompactionStrategy)}";
+        ChatMessage summaryMessage = new(ChatRole.Assistant, summary);
+        (summaryMessage.AdditionalProperties ??= [])[CompactionMessageGroup.SummaryPropertyKey] = true;
 
-            ChatMessage summaryMessage = new(ChatRole.Assistant, summary);
-            (summaryMessage.AdditionalProperties ??= [])[CompactionMessageGroup.SummaryPropertyKey] = true;
-
-            index.InsertGroup(idx + 1, CompactionGroupKind.Summary, [summaryMessage], group.TurnIndex);
-            offset++; // Each insertion shifts subsequent indices by 1
-
-            compacted = true;
-
-            // Stop when target condition is met
-            if (this.Target(index))
-            {
-                break;
-            }
-        }
-
-        return new ValueTask<bool>(compacted);
+        return (CompactionGroupKind.Summary, [summaryMessage], $"Collapsed by {nameof(ToolResultCompactionStrategy)}");
     }
 
     /// <summary>
@@ -171,38 +104,7 @@ protected override ValueTask<bool> CompactCoreAsync(CompactionMessageIndex index
     /// </remarks>
     public static string DefaultToolCallFormatter(CompactionMessageGroup group)
     {
-        // Collect function calls (callId, name) and results (callId → result text)
-        List<(string CallId, string Name)> functionCalls = [];
-        Dictionary<string, string> resultsByCallId = [];
-        List<string> plainTextResults = [];
-
-        foreach (ChatMessage message in group.Messages)
-        {
-            if (message.Contents is null)
-            {
-                continue;
-            }
-
-            bool hasFunctionResult = false;
-            foreach (AIContent content in message.Contents)
-            {
-                if (content is FunctionCallContent fcc)
-                {
-                    functionCalls.Add((fcc.CallId, fcc.Name));
-                }
-                else if (content is FunctionResultContent frc && frc.CallId is not null)
-                {
-                    resultsByCallId[frc.CallId] = frc.Result?.ToString() ?? string.Empty;
-                    hasFunctionResult = true;
-                }
-            }
-
-            // Collect plain text from Tool-role messages that lack FunctionResultContent
-            if (!hasFunctionResult && message.Role == ChatRole.Tool && message.Text is string text)
-            {
-                plainTextResults.Add(text);
-            }
-        }
+        var (functionCalls, resultsByCallId, plainTextResults) = ExtractToolCallsAndResults(group);
 
         // Match function calls to their results using CallId or positional fallback,
         // grouping by tool name while preserving first-seen order.

dotnet/src/Microsoft.Agents.AI/Compaction/ToolResultReductionStrategy.cs

@@ -0,0 +1,174 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Compaction;
+
+/// <summary>
+/// A compaction strategy that applies per-tool reducers to individual tool results,
+/// preserving the original message structure (assistant tool calls + tool result messages)
+/// while transforming the result content.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Unlike <see cref="ToolResultCompactionStrategy"/> which collapses entire tool call groups
+/// into a single YAML-like summary, this strategy keeps the tool call/result message pairing
+/// intact. Each <see cref="FunctionResultContent"/> is passed through its tool's registered
+/// reducer, and the group is replaced with a structurally identical group containing the
+/// reduced results.
+/// </para>
+/// <para>
+/// This is useful when a tool returns very large results (e.g., a retrieval API returning
+/// hundreds of thousands of tokens with relevance scores) that should be reduced before
+/// the model sees them — even on the current turn. The reducer can deserialize the result,
+/// filter, sort, and re-serialize it. These steps happen outside the framework; the framework
+/// only invokes the <c>Func&lt;string, string&gt;</c> delegate.
+/// </para>
+/// <para>
+/// Only <see cref="CompactionGroupKind.ToolCall"/> groups that contain at least one tool name
+/// registered in <see cref="ToolResultReducers"/> are eligible. Groups with no registered tools
+/// are left untouched for other strategies to handle.
+/// </para>
+/// <para>
+/// For tools not registered in the dictionary within an otherwise eligible group, the raw
+/// result text is preserved as-is.
+/// </para>
+/// <para>
+/// <see cref="ToolResultStrategyBase.MinimumPreservedGroups"/> defaults to <c>0</c> so that
+/// reducers apply to all tool results, including the current turn. Set a higher value to
+/// preserve recent results at full fidelity.
+/// </para>
+/// <para>
+/// This strategy composes naturally in a <see cref="PipelineCompactionStrategy"/>. A common
+/// pattern is to place it before <see cref="ToolResultCompactionStrategy"/> — this strategy
+/// reduces result content while preserving structure, then the compaction strategy collapses
+/// older groups into concise summaries.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class ToolResultReductionStrategy : ToolResultStrategyBase
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ToolResultReductionStrategy"/> class.
+    /// </summary>
+    /// <param name="toolResultReducers">
+    /// A dictionary mapping tool names to per-tool result reducers. Each reducer receives the
+    /// raw result text for a single tool invocation and returns the transformed text.
+    /// </param>
+    /// <param name="trigger">
+    /// The <see cref="CompactionTrigger"/> that controls when reduction proceeds.
+    /// </param>
+    /// <param name="minimumPreservedGroups">
+    /// The minimum number of most-recent non-system message groups to preserve.
+    /// Defaults to <c>0</c> so that reducers apply to all tool results including the current turn.
+    /// </param>
+    /// <param name="target">
+    /// An optional target condition that controls when reduction stops. When <see langword="null"/>,
+    /// defaults to the inverse of the <paramref name="trigger"/>.
+    /// </param>
+    public ToolResultReductionStrategy(
+        IReadOnlyDictionary<string, Func<string, string>> toolResultReducers,
+        CompactionTrigger trigger,
+        int minimumPreservedGroups = 0,
+        CompactionTrigger? target = null)
+        : base(trigger, minimumPreservedGroups, target)
+    {
+        this.ToolResultReducers = Throw.IfNull(toolResultReducers);
+    }
+
+    /// <summary>
+    /// Gets the dictionary mapping tool names to per-tool result reducers.
+    /// Each reducer receives the raw result text for a single tool invocation and returns
+    /// the transformed text.
+    /// </summary>
+    public IReadOnlyDictionary<string, Func<string, string>> ToolResultReducers { get; }
+
+    /// <inheritdoc/>
+    protected override bool IsToolGroupEligible(CompactionMessageGroup group)
+    {
+        if (this.ToolResultReducers.Count == 0)
+        {
+            return false;
+        }
+
+        foreach (ChatMessage message in group.Messages)
+        {
+            if (message.Contents is null)
+            {
+                continue;
+            }
+
+            foreach (AIContent content in message.Contents)
+            {
+                if (content is FunctionCallContent fcc && this.ToolResultReducers.ContainsKey(fcc.Name))
+                {
+                    return true;
+                }
+            }
+        }
+
+        return false;
+    }
+
+    /// <inheritdoc/>
+    protected override (CompactionGroupKind Kind, List<ChatMessage> Messages, string ExcludeReason)
+        TransformToolGroup(CompactionMessageGroup group)
+    {
+        // Build a CallId → tool name mapping from the shared extraction helper
+        var (functionCalls, _, _) = ExtractToolCallsAndResults(group);
+
+        Dictionary<string, string> callIdToName = [];
+        foreach ((string callId, string name) in functionCalls)
+        {
+            callIdToName[callId] = name;
+        }
+
+        // Rebuild messages with reduced FunctionResultContent
+        List<ChatMessage> reducedMessages = [];
+        foreach (ChatMessage message in group.Messages)
+        {
+            if (message.Contents is null || message.Contents.Count == 0)
+            {
+                reducedMessages.Add(message);
+                continue;
+            }
+
+            bool hasReduction = false;
+            List<AIContent> newContents = [];
+
+            foreach (AIContent content in message.Contents)
+            {
+                if (content is FunctionResultContent frc
+                    && frc.CallId is not null
+                    && callIdToName.TryGetValue(frc.CallId, out string? toolName)
+                    && this.ToolResultReducers.TryGetValue(toolName, out Func<string, string>? reducer))
+                {
+                    string original = frc.Result?.ToString() ?? string.Empty;
+                    string reduced = reducer(original);
+                    newContents.Add(new FunctionResultContent(frc.CallId, reduced));
+                    hasReduction = true;
+                }
+                else
+                {
+                    newContents.Add(content);
+                }
+            }
+
+            if (hasReduction)
+            {
+                reducedMessages.Add(new ChatMessage(message.Role, newContents));
+            }
+            else
+            {
+                reducedMessages.Add(message);
+            }
+        }
+
+        return (CompactionGroupKind.ToolCall, reducedMessages, $"Reduced by {nameof(ToolResultReductionStrategy)}");
+    }
+}