.NET Compaction - Introduce preconfigured CompactionStrategy pattern

[Copilot]

Developers shouldn't need to understand internal strategy parameters to get a well-tuned compaction pipeline. This adds a CompactionStrategy.Create(approach, size, chatClient?) factory that maps two intuitive axes to a pre-configured PipelineCompactionStrategy.

New types

• CompactionApproach — controls pipeline composition:

  • Gentle: tool-result collapsing + truncation backstop (no LLM required)
  • Balanced: tool-result collapsing + LLM summarization + truncation backstop
  • Aggressive: tool-result collapsing + LLM summarization + sliding window + truncation

• CompactionSize — scales all trigger thresholds to match model context capacity:

  • Compact ≈ 8 K tokens, Moderate ≈ 32 K tokens, Generous ≈ 64 K tokens

Factory logic

Within each pipeline, early stages trigger at a fraction of the size limit (⅔ for Balanced, ½ for Aggressive) so incremental compaction fires before reaching the emergency truncation backstop.

Usage

IChatClient summarizerClient = ...;

// Balanced pipeline for a mid-range model
CompactionStrategy strategy = CompactionStrategy.Create(
    CompactionApproach.Balanced,
    CompactionSize.Moderate,
    summarizerClient);

// Gentle pipeline — no LLM required
CompactionStrategy strategy = CompactionStrategy.Create(
    CompactionApproach.Gentle,
    CompactionSize.Compact);

chatClient is required (and validated) only when approach is Balanced or Aggressive.

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? No.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>.NET Compaction - Introduce preconfigured CompactionStrategy pattern</issue_title>
<issue_description>I expect many developers will ask: How do I configured my CompactionStrategy? ...which one do I use? ...what thresholds work best?

We can expose a factory that creates a pre-configured CompactionStrategy according to a set of options:

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

// Create a compaction strategy based on a menu selection of characteristics
CompactionStrategy tunedStrategy =
   CompactionStrategy.Create(
      Approach.Balanced,
      Size.Compact,
      summarizingChatClient);

In this example, "size" could be:

• Compact
• Moderate
• Generous

And "approach" could be:

• Aggressive
• Balanced
• Gentle

Perhaps the "size" parameter is informed by the maximum input tokens allowed by a given model, with a default based on a conservative estimate of the most common usage.

Behind the scenes the combination of these two axes map to a certain CompactionStrategy configuration. As we improve our configuration, developers using this pattern will automatically realize those improvements.</issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes .NET Compaction - Introduce preconfigured CompactionStrategy pattern #4603

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull request overview

This PR introduces a preconfigured compaction “menu” for the .NET Agent Framework, adding a CompactionStrategy.Create(approach, size, chatClient?) factory that maps high-level options to a tuned PipelineCompactionStrategy.

Changes:

• Added CompactionApproach and CompactionSize enums to represent the two configuration axes.
• Implemented CompactionStrategy.Create(...) factory to generate Gentle/Balanced/Aggressive pipelines with staged triggers.
• Added unit tests validating pipeline composition, argument validation, and (partially) size behavior.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
dotnet/src/Microsoft.Agents.AI/Compaction/CompactionStrategy.cs	Marks CompactionStrategy as partial to allow adding the factory in a separate file.
dotnet/src/Microsoft.Agents.AI/Compaction/CompactionStrategy.Factory.cs	Adds CompactionStrategy.Create(...) and internal size→threshold mappings for pipeline construction.
dotnet/src/Microsoft.Agents.AI/Compaction/CompactionApproach.cs	Adds the CompactionApproach enum describing pipeline composition choices.
dotnet/src/Microsoft.Agents.AI/Compaction/CompactionSize.cs	Adds the CompactionSize enum describing context-size profiles.
dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/CompactionStrategyCreateTests.cs	Adds unit tests for the new factory method and size differentiation behavior.

[westey-m]

Does the terms used here, e.g. "Gentle", "lightest", or "Aggressive" refer to the costliness (both time and resources) of the techniques used?
If so, would some reference to cost be appropriate, e.g. "Fast", "Balanced", "Slow" or "Cheap" , "Balanced", "Expensive"?

After all, I wouldn't necessarily consider Truncation a gentle technique. It's rather blunt and aggressive IMO 😄

[westey-m]

Should we explain what Compact, Moderate and Generous means here in actual numbers, so that users can more easily make a decision about which one fits their model?
Also, how does the chosen numbers match actual models in the real world. Do they align well with the maximum context window sizes typical of popular models out there?