Verdichting

Compressie werkt op een MessageIndex — een gestructureerde weergave van de platte berichtenlijst die berichten groepeert in atomische eenheden, genaamd MessageGroup exemplaren. Elke groep houdt het aantal berichten, het aantal byte en het geschatte aantal tokens bij.

Berichtgroepen

A MessageGroup vertegenwoordigt logisch gerelateerde berichten die samen moeten worden bewaard of verwijderd. Een assistentbericht met hulpprogrammaaanroepen en de bijbehorende berichten over het resultaat van het hulpprogramma vormen bijvoorbeeld een atomische groep. Als u een bericht verwijdert zonder de andere, zou dat fouten met de LLM-API veroorzaken.

Elke groep heeft een MessageGroupKind:

Triggers

A CompactionTrigger is een gemachtigde die evalueert of compressie moet worden voortgezet op basis van de huidige MessageIndex metrische gegevens:

public delegate bool CompactionTrigger(MessageIndex index);

De CompactionTriggers klasse biedt veelgebruikte factorymethoden:

Triggers combineren met CompactionTriggers.All(...) (logische AND) of CompactionTriggers.Any(...) (logische OF):

// Compact only when there are tool calls AND tokens exceed 2000
CompactionTrigger trigger = CompactionTriggers.All(
    CompactionTriggers.HasToolCalls(),
    CompactionTriggers.TokensExceed(2000));

Trigger versus doel

Elke strategie heeft twee predicaten:

• Trigger : hiermee bepaalt u wanneer de compressie begint. Als de trigger false retourneert, wordt de strategie volledig overgeslagen.
• Doel — Regelt wanneer compacte stopt. Strategieën sluiten incrementeel groepen uit en evalueren het doel na elke stap opnieuw, stoppen zodra het doel retourneert true.

Wanneer er geen doel is opgegeven, wordt standaard de inverse van de triggerconditie gebruikt. Compactie stopt zodra de triggervoorwaarde niet meer wordt geactiveerd.

Compressie werkt op een platte lijst Message met objecten. Berichten worden geannoteerd met lichtgewicht groepsmetagegevens en strategieën muteren deze aantekeningen om groepen te markeren als uitgesloten voordat de berichtenlijst naar het model wordt geprojecteerd.

Berichtgroepen

Berichten worden gegroepeerd in atomische eenheden. Aan elke groep wordt een GroupKind:

Compressiestrategieën

A CompactionStrategy is een protocol: elk async aanroepbaar dat een list[Message] accepteert en het ter plekke muteert, retourneert True wanneer het iets wijzigt:

class CompactionStrategy(Protocol):
    async def __call__(self, messages: list[Message]) -> bool: ...

Tokenizer

Tokenbewuste strategieën accepteren een TokenizerProtocol implementatie. De ingebouwde CharacterEstimatorTokenizer maakt gebruik van een heuristiek van 4 tekens per token:

from agent_framework._compaction import CharacterEstimatorTokenizer

tokenizer = CharacterEstimatorTokenizer()

Geef een aangepaste tokenizer door wanneer u nauwkeurige tokenaantallen nodig hebt voor de codering van een specifiek model.

Alle strategieën nemen over van de abstracte CompactionStrategy basisklasse. Elke strategie behoudt systeemberichten en respecteert een MinimumPreserved vloer die de meest recente niet-systeemgroepen beschermt tegen verwijdering.

Compressiestrategieën worden geïmporteerd uit agent_framework._compaction.

TruncationCompactionStrategy

TruncationStrategy

• MinimumPreserved wordt standaard ingesteld op 32.

// Drop oldest groups when tokens exceed 32K, keeping at least 10 recent groups
TruncationCompactionStrategy truncation = new(
    trigger: CompactionTriggers.TokensExceed(0x8000),
    minimumPreserved: 10);

• Wanneer er een tokenizer wordt opgegeven, wordt het aantal tokens als metriek gebruikt; anders wordt het aantal berichten meegeteld.
• preserve_system wordt standaard ingesteld op True.

from agent_framework._compaction import CharacterEstimatorTokenizer, TruncationStrategy

# Exclude oldest groups when tokens exceed 32 000, trimming to 16 000
truncation = TruncationStrategy(
    max_n=32_000,
    compact_to=16_000,
    tokenizer=CharacterEstimatorTokenizer(),
)

SlidingWindowCompactionStrategy

SlidingWindowStrategy

Verwijdert de oudste dialoogbeurten en de bijbehorende antwoordgroepen, die werken op logische grenzen van beurten in plaats van afzonderlijke groepen.

• Een beurt begint met een gebruikersbericht en bevat alle volgende assistent- en hulpprogrammaoproepgroepen tot het volgende gebruikersbericht.
• MinimumPreserved standaard op 1 (behoudt ten minste de meest recente niet-systeemgroep).

// Keep only the last 4 user turns
SlidingWindowCompactionStrategy slidingWindow = new(
    trigger: CompactionTriggers.TurnsExceed(4));

Bewaart alleen de meest recente keep_last_groups niet-systeemgroepen, met uitzondering van alles wat ouder is.

• preserve_system wordt standaard ingesteld op True.

from agent_framework._compaction import SlidingWindowStrategy

# Keep only the last 20 non-system groups
sliding_window = SlidingWindowStrategy(keep_last_groups=20)

• Vervangt oproepgroepen met meerdere berichten (assistentgesprek + resultaten) door een korte samenvatting zoals [Tool calls: get_weather, search_docs].
• MinimumPreserved is standaard ingesteld op 2, zodat de interacties van de huidige beurt zichtbaar blijven.

// Collapse old tool results when tokens exceed 512
ToolResultCompactionStrategy toolCompaction = new(
    trigger: CompactionTriggers.TokensExceed(0x200));

• Wordt samengevouwen tot compacte samenvattingsberichten zoals [Tool results: get_weather: sunny, 18°C].
• De meest recente keep_last_tool_call_groups groepen voor het aanroepen van hulpprogramma's blijven ongewijzigd.

from agent_framework._compaction import ToolResultCompactionStrategy

# Collapse all but the newest tool-call group
tool_result = ToolResultCompactionStrategy(keep_last_tool_call_groups=1)

SummarizationCompactionStrategie

Samenvattingsstrategie

• Beveiligt systeemberichten en de meest recente MinimumPreserved niet-systeemgroepen (standaard: 4).
• Verzendt de oudere berichten naar een afzonderlijk IChatClient met een samenvattingsprompt en voegt vervolgens de samenvatting in als groep MessageGroupKind.Summary .

// Summarize older messages when tokens exceed 1280, keeping the last 4 groups
SummarizationCompactionStrategy summarization = new(
    chatClient: summarizerChatClient,
    trigger: CompactionTriggers.TokensExceed(0x500),
    minimumPreserved: 4);

U kunt een aangepaste samenvattingsprompt opgeven:

SummarizationCompactionStrategy summarization = new(
    chatClient: summarizerChatClient,
    trigger: CompactionTriggers.TokensExceed(0x500),
    summarizationPrompt: "Summarize the key decisions and user preferences only.");

• Wordt geactiveerd wanneer het aantal niet-systeemberichten groter is dan target_count + threshold.
• Behoudt de nieuwste target_count berichten; geeft een overzicht van alle oudere berichten.
• Hiervoor is een SupportsChatGetResponse client vereist.

from agent_framework._compaction import SummarizationStrategy

# Summarize when non-system message count exceeds 6, retaining the 4 newest
summarization = SummarizationStrategy(
    client=summarizer_client,
    target_count=4,
    threshold=2,
)

Geef een aangepaste samenvattingsprompt op:

summarization = SummarizationStrategy(
    client=summarizer_client,
    target_count=4,
    prompt="Summarize the key decisions and user preferences only.",
)

PipelineCompactionStrategy

Stelt meerdere strategieën samen in een sequentiële pijplijn. Elke strategie werkt op het resultaat van de vorige strategie, waardoor gelaagde compressie van zacht tot agressief mogelijk is.

• De eigen trigger van de pijplijn is CompactionTriggers.Always : elke onderliggende strategie evalueert een eigen trigger onafhankelijk.
• Strategieën worden op volgorde uitgevoerd, dus plaats eerst de zachtste strategieën.

PipelineCompactionStrategy pipeline = new(
    new ToolResultCompactionStrategy(CompactionTriggers.TokensExceed(0x200)),
    new SummarizationCompactionStrategy(summarizerChatClient, CompactionTriggers.TokensExceed(0x500)),
    new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(4)),
    new TruncationCompactionStrategy(CompactionTriggers.TokensExceed(0x8000)));

Deze pijplijn:

1. Hiermee worden oude toolresultaten samengevouwen (zacht).
2. Geeft een overzicht van oudere gesprekken (gemiddeld).
3. Houdt alleen de laatste vier gebruikersbeurten bij (agressief).
4. De oudste groepen worden verwijderd als ze nog steeds boven het budget zijn (noodmaatregel).

SelectieveGereedschapsAanroepCompactieStrategie

Sluit volledig oudere tool-aanroepgroepen uit en houdt alleen de laatste keep_last_tool_call_groups.

• Raakt geen berichten van de gebruiker of platte assistent aan.
• Het beste wanneer toolchatter het tokengebruik overheerst en de volledige hulpprogrammageschiedenis niet nodig is.

from agent_framework._compaction import SelectiveToolCallCompactionStrategy

# Keep only the most recent tool-call group
selective_tool = SelectiveToolCallCompactionStrategy(keep_last_tool_call_groups=1)

TokenBudgetComposedStrategy

Stelt meerdere strategieën samen in een sequentiële pijplijn die wordt aangestuurd door een tokenbudget. Elke kindstrategie wordt in volgorde uitgevoerd en stopt vroeg zodra het budget is gevuld. Een ingebouwde terugval sluit de oudste groepen uit als de strategieën alleen het doel niet kunnen bereiken.

• Strategieën worden op volgorde uitgevoerd; plaats eerst de zachtste strategieën.
• early_stop=True (de standaardinstelling) stopt zodra aan het tokenbudget is voldaan.

from agent_framework._compaction import (
    CharacterEstimatorTokenizer,
    SelectiveToolCallCompactionStrategy,
    SlidingWindowStrategy,
    SummarizationStrategy,
    TokenBudgetComposedStrategy,
    ToolResultCompactionStrategy,
)

tokenizer = CharacterEstimatorTokenizer()

pipeline = TokenBudgetComposedStrategy(
    token_budget=16_000,
    tokenizer=tokenizer,
    strategies=[
        ToolResultCompactionStrategy(keep_last_tool_call_groups=1),
        SummarizationStrategy(client=summarizer_client, target_count=4, threshold=2),
        SlidingWindowStrategy(keep_last_groups=20),
    ],
)

Deze pijplijn:

1. Hiermee worden oude toolresultaten samengevouwen (zacht).
2. Geeft een overzicht van oudere gesprekken (gemiddeld).
3. Houdt alleen de laatste 20 groepen (agressief).
4. Valt terug op oudste uitsluiting als het budget nog steeds is overschreden (noodstop).

Verpakt een compressiestrategie in een CompactionProvider en registreer deze als een AIContextProvider. Geef één strategie of een PipelineCompactionStrategy door aan de constructor.

Registreren bij de builder-API

Registreer de provider op de ChatClientBuilder met behulp van UseAIContextProviders. De provider wordt uitgevoerd in de lus voor het aanroepen van hulpprogramma's, waarbij berichten vóór elke LLM-aanroep worden gecomprimeerd.

IChatClient agentChatClient = openAIClient.GetChatClient(deploymentName).AsIChatClient();
IChatClient summarizerChatClient = openAIClient.GetChatClient(deploymentName).AsIChatClient();

PipelineCompactionStrategy compactionPipeline =
    new(
        new ToolResultCompactionStrategy(CompactionTriggers.TokensExceed(0x200)),
        new SummarizationCompactionStrategy(summarizerChatClient, CompactionTriggers.TokensExceed(0x500)),
        new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(4)),
        new TruncationCompactionStrategy(CompactionTriggers.TokensExceed(0x8000)));

AIAgent agent =
    agentChatClient
        .AsBuilder()
        .UseAIContextProviders(new CompactionProvider(compactionPipeline))
        .BuildAIAgent(
            new ChatClientAgentOptions
            {
                Name = "ShoppingAssistant",
                ChatOptions = new()
                {
                    Instructions = "You are a helpful shopping assistant.",
                    Tools = [AIFunctionFactory.Create(LookupPrice)],
                },
            });

AgentSession session = await agent.CreateSessionAsync();
Console.WriteLine(await agent.RunAsync("What's the price of a laptop?", session));

Als er slechts één strategie nodig is, kunt u deze rechtstreeks aan CompactionProvider doorgeven zonder deze in een PipelineCompactionStrategy:

agentChatClient
    .AsBuilder()
    .UseAIContextProviders(new CompactionProvider(
        new SlidingWindowCompactionStrategy(CompactionTriggers.TurnsExceed(20))))
    .BuildAIAgent(...);

Registreren via ChatClientAgentOptions

De provider kan ook rechtstreeks worden opgegeven op ChatClientAgentOptions.AIContextProviders:

AIAgent agent = agentChatClient
    .AsBuilder()
    .BuildAIAgent(new ChatClientAgentOptions
    {
        AIContextProviders = [new CompactionProvider(compactionPipeline)]
    });

Ad-hoc compressie

CompactionProvider.CompactAsync past een strategie toe op een willekeurige berichtenlijst zonder een actieve agentsessie:

IEnumerable<ChatMessage> compacted = await CompactionProvider.CompactAsync(
    new TruncationCompactionStrategy(CompactionTriggers.TokensExceed(8000)),
    existingMessages);

CompactionProvider is een contextprovider die compressiestrategieën toepast voor en na elke agentuitvoering. Voeg deze toe naast een geschiedenisprovider in de lijst van context_providers de agent.

• before_strategy — wordt uitgevoerd vóór de modeloproep, waarbij berichten die al in de context zijn geladen, worden gecomprimeerd.
• after_strategy — wordt uitgevoerd na de modelaanroep, waarbij de berichten die zijn opgeslagen door de geschiedenisprovider worden gecomprimeerd, zodat de volgende beurt kleiner wordt gestart.
• history_source_id — de source_id geschiedenisprovider waarvan de opgeslagen berichten after_strategy moeten worden gecomprimeerd (standaard ingesteld op "in_memory").

Registreren bij een agent

from agent_framework import Agent, CompactionProvider, InMemoryHistoryProvider
from agent_framework._compaction import (
    CharacterEstimatorTokenizer,
    SlidingWindowStrategy,
    SummarizationStrategy,
    TokenBudgetComposedStrategy,
    ToolResultCompactionStrategy,
)

tokenizer = CharacterEstimatorTokenizer()

pipeline = TokenBudgetComposedStrategy(
    token_budget=16_000,
    tokenizer=tokenizer,
    strategies=[
        ToolResultCompactionStrategy(keep_last_tool_call_groups=1),
        SummarizationStrategy(client=summarizer_client, target_count=4, threshold=2),
        SlidingWindowStrategy(keep_last_groups=20),
    ],
)

history = InMemoryHistoryProvider()
compaction = CompactionProvider(
    before_strategy=pipeline,
    history_source_id=history.source_id,
)

agent = Agent(
    client=client,
    name="ShoppingAssistant",
    instructions="You are a helpful shopping assistant.",
    context_providers=[history, compaction],
)

session = agent.create_session()
print(await agent.run("What's the price of a laptop?", session=session))

Als er slechts één strategie nodig is, geeft u deze rechtstreeks door als before_strategy:

compaction = CompactionProvider(
    before_strategy=SlidingWindowStrategy(keep_last_groups=20),
    history_source_id=history.source_id,
)

Opgeslagen geschiedenis comprimeren na elke uitvoering

Gebruik after_strategy dit om de berichten die zijn opgeslagen door de geschiedenisprovider te comprimeren, zodat toekomstige beurten beginnen met een beperkte context:

compaction = CompactionProvider(
    before_strategy=SlidingWindowStrategy(keep_last_groups=20),
    after_strategy=ToolResultCompactionStrategy(keep_last_tool_call_groups=1),
    history_source_id=history.source_id,
)

Ad-hoc compressie

apply_compaction past een strategie toe op een willekeurige berichtenlijst buiten een actieve agentsessie:

from agent_framework._compaction import apply_compaction, TruncationStrategy, CharacterEstimatorTokenizer

tokenizer = CharacterEstimatorTokenizer()

compacted = await apply_compaction(
    messages,
    strategy=TruncationStrategy(
        max_n=8_000,
        compact_to=4_000,
        tokenizer=tokenizer,
    ),
    tokenizer=tokenizer,
)