.NET Compaction - "MessageProvider" approach (#3)

[crickman]

Motivation and Context

Context management (compaction) is one of the key features in the "dev-harness" effort. This change introduces structured handling of long-running AI chat conversations by compacting historical context while preserving key decisions and intent. By reducing token growth and context drift, it improves response quality, performance, and cost predictability over extended sessions. The implementation is designed to be extensible and transparent, making context lifecycle management a first‑class concern for agent development.

[Spec]

Description

The goal of this approach is inject compaction as part of the IChatClient architecture. This approach maintains an index that allows for presenting a compacted version of the conversation without modifying the source "chat history".

Features

• Built-in compaction strategies
• Supports pipeline strategy
• Supports direct invocation
• Supports IChatReducer
• State retained with session serialization
• Incremental message processing
• Atomic tool-call grouping
• Includes tool loops
• Retains original chat history

Details

Compaction occurs via a CompactionStrategy. A set of strategies are incuded as part of this initial release, including a pipeline strategy that is able to sequentially apply one or more strategies:

Strategy	Aggressiveness	Preserves context	Requires LLM	Best for
ToolResultCompactionStrategy	Low	High — only collapses tool results	No	Reclaiming space from verbose tool output
SummarizationCompactionStrategy	Medium	Medium — replaces history with a summary	Yes	Long conversations where context matters
SlidingWindowCompactionStrategy	High	Low — drops entire turns	No	Hard turn-count limits
TruncationCompactionStrategy	High	Low — drops oldest groups	No	Emergency token-budget backstops
PipelineCompactionStrategy	Configurable	Depends on child strategies	Depends	Layered compaction with multiple fallbacks
ChatReducerCompactionStrategy	Configurable	Depends on the IChatReducer	Depends	Compact using an existing IChatReducer

Code

// Setup a chat client for summarization
IChatClient summarizingChatClient = ...;

// Configure the compaction pipeline with one of each strategy, ordered least to most aggressive.
PipelineCompactionStrategy compactionPipeline =
    new(// 1. Gentle: collapse old tool-call groups into short summaries like "[Tool calls: LookupPrice]"
        new ToolResultCompactionStrategy(CompactionTriggers.TokensExceed(0x200)),

        // 2. Moderate: use an LLM to summarize older conversation spans into a concise message
        new SummarizationCompactionStrategy(summarizingChatClient, CompactionTriggers.TokensExceed(0x8000)),

        // 3. Aggressive: keep only the last N user turns and their responses
        new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(4)),

        // 4. Emergency: drop oldest groups until under the token budget
        new TruncationCompactionStrategy(CompactionTriggers.GroupsExceed(0x1000)));

AIAgent agent =
    agentChatClient.AsAIAgent(
        new ChatClientAgentOptions
        {
            Name = "ShoppingAssistant",
            ChatOptions = new()
            {
                Instructions = "...",
                Tools = [...],
            },
            AIContextProviders = [new MessageCompactionContextProvider(compactionPipeline)],
        });

or

AIAgent agent =
    agentChatClient
        .AsBuilder()
        .UseAIContextProviders(new MessageCompactionContextProvider(compactionPipeline))
        .BuildAIAgent(
            new ChatClientAgentOptions
            {
                Name = "ShoppingAssistant",
                ChatOptions = new()
                {
                    Instructions = "...",
                    Tools = [...],
                }
            });

or

AIAgent agent =
    agentChatClient
        .AsAIAgent(
            new ChatClientAgentOptions
            {
                Name = "ShoppingAssistant",
                ChatOptions = new()
                {
                    Instructions = "...",
                    Tools = [...],
                }
            })
        .AsBuilder()
        .UseAIContextProviders(new MessageCompactionContextProvider(compactionPipeline))
        .Build();

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[Copilot]

Pull request overview

Introduces a new .NET “MessageProvider” compaction approach that groups chat history into atomic message groups (system/user/assistant/tool-call/summary) and applies configurable compaction strategies (including pipeline composition) before agent invocations, with supporting tests and a sample.

Changes:

• Added compaction core types (MessageIndex/MessageGroup) and multiple built-in compaction strategies (tool-result collapse, summarization, sliding-window, truncation, chat-reducer bridge, and pipeline composition).
• Added MessageCompactionContextProvider for in-run compaction via the agent context provider pipeline.
• Added unit tests, a new Step 18 sample, and introduced Microsoft.ML.Tokenizers dependency for token counting.

Reviewed changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
dotnet/tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj	Adds Tokenizers dependency for compaction-related tests.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/TruncationCompactionStrategyTests.cs	Tests truncation strategy behavior and edge cases.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/ToolResultCompactionStrategyTests.cs	Tests tool-result collapsing behavior and triggers/targets.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/SummarizationCompactionStrategyTests.cs	Tests LLM-based summarization strategy behavior and fallbacks.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/SlidingWindowCompactionStrategyTests.cs	Tests turn-based sliding window exclusions and preservation rules.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/PipelineCompactionStrategyTests.cs	Tests strategy pipeline composition and execution ordering.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/MessageIndexTests.cs	Tests grouping, metrics, incremental update, and token counting behavior.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/MessageCompactionContextProviderTests.cs	Tests session-state-backed context provider compaction behavior.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/CompactionTriggersTests.cs	Tests trigger predicates and combinators.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/CompactionStrategyTests.cs	Tests base strategy trigger/target semantics and short-circuiting.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/ChatReducerCompactionStrategyTests.cs	Tests reducer-bridging strategy behavior and rebuild semantics.
dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj	Adds Tokenizers dependency and fixes formatting for InternalsVisibleTo.
dotnet/src/Microsoft.Agents.AI/Compaction/TruncationCompactionStrategy.cs	Implements oldest-group truncation with minimum-preserved floor.
dotnet/src/Microsoft.Agents.AI/Compaction/ToolResultCompactionStrategy.cs	Implements collapsing older tool-call groups into concise assistant summaries.
dotnet/src/Microsoft.Agents.AI/Compaction/SummarizationCompactionStrategy.cs	Implements LLM summarization compaction into a summary group/message.
dotnet/src/Microsoft.Agents.AI/Compaction/SlidingWindowCompactionStrategy.cs	Implements turn-based sliding window compaction.
dotnet/src/Microsoft.Agents.AI/Compaction/PipelineCompactionStrategy.cs	Adds sequential composition of multiple compaction strategies.
dotnet/src/Microsoft.Agents.AI/Compaction/MessageIndex.cs	Adds grouping/indexing, metrics, and incremental update support for chat messages.
dotnet/src/Microsoft.Agents.AI/Compaction/MessageGroupKind.cs	Adds group-kind enum for compaction grouping.
dotnet/src/Microsoft.Agents.AI/Compaction/MessageGroup.cs	Adds message group model with metrics and exclusion semantics.
dotnet/src/Microsoft.Agents.AI/Compaction/MessageCompactionContextProvider.cs	Adds AIContextProvider that applies compaction per invocation with session state.
dotnet/src/Microsoft.Agents.AI/Compaction/CompactionTriggers.cs	Adds trigger helpers for token/message/turn/group thresholds and composition.
dotnet/src/Microsoft.Agents.AI/Compaction/CompactionTrigger.cs	Adds trigger delegate type.
dotnet/src/Microsoft.Agents.AI/Compaction/CompactionStrategy.cs	Adds strategy base class with trigger/target orchestration and metrics logging.
dotnet/src/Microsoft.Agents.AI/Compaction/ChatReducerCompactionStrategy.cs	Bridges IChatReducer into the compaction strategy model.
dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientExtensions.cs	Minor formatting adjustment in middleware setup.
dotnet/src/Microsoft.Agents.AI.Abstractions/InMemoryChatHistoryProvider.cs	Refactors reducer invocation path and introduces (currently stubbed) compaction hook.
dotnet/samples/02-agents/Agents/README.md	Adds new Step 18 compaction pipeline sample entry.
dotnet/samples/02-agents/Agents/Agent_Step18_CompactionPipeline/Program.cs	New sample demonstrating compaction pipeline usage with an agent/tool loop.
dotnet/samples/02-agents/Agents/Agent_Step18_CompactionPipeline/Agent_Step18_CompactionPipeline.csproj	New sample project wiring dependencies and project reference.
dotnet/agent-framework-dotnet.slnx	Adds new sample project to solution.
dotnet/Directory.Packages.props	Adds Microsoft.ML.Tokenizers package version.