Context Compression

Compress tool call results to save context space while preserving critical information.

v2.2.14

Setup

In an activated virtual environment:

uv pip install -U agno openai
export OPENAI_API_KEY="your_openai_api_key"

Context compression summarizes eligible tool-result messages for subsequent model requests. It can reduce context size, but does not guarantee a smaller summary, complete preservation of facts, lower total cost, or fitting the model's context window.

The Problem: Verbose Tool Results

Large tool results can consume the context window. The following token counts illustrate a possible workload; they are not measured guarantees:

ComponentCumulative Token CountNotes
System Prompt1,200 tokens
User Message1,300 tokens
LLM Response1,500 tokens
Tool Call 12,500 tokens
Tool Call 25,700 tokens2,500 + 3,200 new
Tool Call 38,500 tokens5,700 + 2,800 new
Tool Call 412,000 tokens8,500 + 3,500 new

This quickly becomes expensive and hits context limits during complex workflows.

The Solution: Automatic Compression

Context compression summarizes tool results after a threshold:

Tool Call 1: 2,500 tokens
Tool Call 2: 5,700 tokens
Tool Call 3: 8,500 tokens
[Compression triggered]
Tool Call 4: 1,300 tokens (800 compressed + 500 new)

Compression adds summarization-model calls and latency. Measure savings and information loss on your workload. System and user messages are not shortened by tool-result compression.

How It Works

Context compression follows a simple pattern:

Enable Compression

Set compress_tool_results=True on your agent or team, or provide a CompressionManager. The system monitors tool call results as they come in.

Threshold Reached

After the threshold is reached, compression is triggered. Each uncompressed tool call result is individually summarized.

Intelligent Summarization

The compression prompt asks the model to retain key facts while removing boilerplate. Summaries can lose information or exceed the original length.

The LLM loop continues

The compressed tool results are used in the next LLM executions, using each message's compressed_content. The original content is retained, so this is not a storage-reduction guarantee.

When using arun on Agent or Team, compression is handled asynchronously and the uncompressed tool call results are summarized concurrently.

Compression and result offloading

Compression and tool-result offloading are alternative mechanisms for the same results. Agent and Team initialization reject enabling both. If a member inherits a Team's result store, set offload_tool_results=False on that member before enabling its compression. See tool result offloading.

Enable Compression

Turn on compress_tool_results=True to automatically compress tool results. This comes with a default threshold of 3 uncompressed tool-result messages.

For example:

from agno.agent import Agent
from agno.models.openai import OpenAIResponses
from agno.tools.hackernews import HackerNewsTools

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[HackerNewsTools()],
    compress_tool_results=True,
)

agent.print_response("Get the top stories on HackerNews about AI, ML, startups, and tech trends")

You can also enable compress_tool_results=True on individual team members to compress their tool results independently.

Custom Compression

Provide a CompressionManager to customize the compression behavior:

from agno.agent import Agent
from agno.compression.manager import CompressionManager
from agno.models.openai import OpenAIResponses
from agno.tools.hackernews import HackerNewsTools

compression_manager = CompressionManager(
    model=OpenAIResponses(id="gpt-5-mini"),  # Use a faster model for compression
    compress_tool_results_limit=2,  # Compress at 2 uncompressed tool-result messages (default: 3)
    compress_tool_call_instructions="Your custom compression prompt here...",
)

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[HackerNewsTools()],
    compression_manager=compression_manager,
)

agent.print_response("Find stories about AI startup funding on HackerNews")

Use a faster, cheaper model like gpt-5-mini for compression to reduce latency and cost while using a more capable model as your Agent's main model.

Compression Triggers

The CompressionManager supports two types of thresholds for triggering compression:

ModeParameterUse Case
Count-Basedcompress_tool_results_limitPredictable tool call patterns. Triggers after N uncompressed tool results.
Token-Basedcompress_token_limitVariable result sizes. Triggers when the estimated context token count reaches the threshold.

When both thresholds are set, reaching either triggers compression (OR). If neither threshold is set, compress_tool_results_limit defaults to 3.

Tool-Based Compression

Set compress_tool_results_limit when you have predictable tool call patterns and want compression to trigger after a fixed number of tool call results.

Token-Based Compression

Use compress_token_limit to trigger summarization based on estimated context size, especially when tool results vary significantly in size:

from agno.agent import Agent
from agno.compression.manager import CompressionManager
from agno.models.openai import OpenAIResponses
from agno.tools.hackernews import HackerNewsTools

compression_manager = CompressionManager(
    model=OpenAIResponses(id="gpt-5.2"),
    compress_tool_results=True,
    compress_token_limit=5000,  # or compress_tool_results_limit
)

agent = Agent(
    model=OpenAIResponses(id="gpt-5.2"),
    tools=[HackerNewsTools()],
    compression_manager=compression_manager,
)

agent.print_response("Find HackerNews discussions about OpenAI, Anthropic, Google DeepMind, and Meta AI")

Token counting includes messages, tool definitions, and output schemas. See Token Counting for details.

When to Use Context Compression

Best for:

  • Agents with tools that return verbose results (web search, APIs)
  • Multi-step workflows with many tool calls
  • Long-running sessions where context accumulates
  • Production systems where cost matters

Developer Resources