Context Compression

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

v2.2.3

Context Compression allows you to manage your agent context while it is running, helping the agent stay within its context window and avoid rate limits or decreases in response quality.

Think of it like a research assistant who reads lengthy reports and gives you the key bullet points instead of the full documents.

The Problem: Verbose Tool Results

If you are using tools with large response sizes, without compression, tool results quickly consume your context window:

Component	Cumulative Token Count	Notes
System Prompt	1,200 tokens
User Message	1,300 tokens
LLM Response	1,500 tokens
Tool Call 1	2,500 tokens
Tool Call 2	5,700 tokens	2,500 + 3,200 new
Tool Call 3	8,500 tokens	5,700 + 2,800 new
Tool Call 4	12,000 tokens	8,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)

Benefits:

• Dramatically reduced token costs
• Stay within context window limits
• Preserve critical facts and data
• Automatic compression

How It Works

Context compression follows a simple pattern:

1. 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.

2. Threshold Reached

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

3. Intelligent Summarization

   The compression model preserves key facts (numbers, dates, entities, URLs) while removing boilerplate, redundancy, and filler text.

4. The LLM loop continues

   The compressed tool results are used in the next LLM executions, reducing token usage and extending the life of your context window.

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

Enable Compression

Turn on compress_tool_results=True to automatically compress tool results. This comes with a default threshold of 3 tool calls.

For example:

Agent

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")

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

web_agent = Agent(
    name="HackerNews Researcher",
    tools=[HackerNewsTools()],
)

team = Team(
    model=OpenAIResponses(id="gpt-5.2"),
    members=[web_agent],
    compress_tool_results=True,
)

team.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:

Agent

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"),  # Use a faster model for compression
    compress_tool_results_limit=2,  # Compress after 2 tool calls (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")

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

compression_manager = CompressionManager(
    model=OpenAIResponses(id="gpt-5.2"),  # Use a faster model for compression
    compress_tool_results_limit=2,  # Compress after 2 tool calls (default: 3)
    compress_tool_call_instructions="Your custom compression prompt here...",
)

web_agent = Agent(
    name="HackerNews Researcher",
    tools=[HackerNewsTools()],
)

team = Team(
    model=OpenAIResponses(id="gpt-5.2"),
    members=[web_agent],
    compression_manager=compression_manager,
)

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

Use a faster, cheaper model like gpt-4o-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:

Mode	Parameter	Use Case
Count-Based	compress_tool_results_limit	Predictable tool call patterns. Triggers after N uncompressed tool results.
Token-Based	compress_token_limit	Variable result sizes or strict context limits. Triggers when context exceeds a token threshold.

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 when you need precise control over context size, especially when tool results vary significantly in size:

Agent

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")

from agno.agent import Agent
from agno.compression.manager import CompressionManager
from agno.models.openai import OpenAIResponses
from agno.team import Team
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
)

web_agent = Agent(
    name="HackerNews Researcher",
    tools=[HackerNewsTools()],
)

team = Team(
    model=OpenAIResponses(id="gpt-5.2"),
    members=[web_agent],
    compression_manager=compression_manager,
)

team.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

Perfect 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

• CompressionManager Reference - Full CompressionManager documentation
• Agent Reference - Agent parameter documentation
• Team Reference - Team parameter documentation