# How to Use Context Compression in Agno to Optimize Token Usage

> Learn how to use context compression in Agno to optimize token usage. Agno automatically compresses tool results, reducing consumption and costs while preserving key information for AI reasoning.

- Repository: [Agno/agno](https://github.com/agno-agi/agno)
- Tags: how-to-guide
- Published: 2026-02-23

---

**Agno automatically compresses verbose tool results before adding them to the LLM context using `CompressionManager`, reducing token consumption and API costs while preserving essential information for reasoning.**

Context compression in Agno is a built-in optimization that shrinks oversized tool outputs before they reach the language model. The feature centers on the **`CompressionManager`** class and integrates seamlessly into the **Agent**, **Team**, and **Model** pipelines. This guide explains how to enable, configure, and monitor context compression using the actual implementation from the `agno-agi/agno` repository.

## How Context Compression Works in Agno

The compression pipeline hooks into every model execution cycle. When an Agno model produces a response via `Model._run` in [`libs/agno/agno/models/base.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/models/base.py), the system checks whether tool results should be compressed before the next LLM call.

### The Compression Decision

At lines 662–665 (synchronous) and 874–877 (asynchronous) in [`base.py`](https://github.com/agno-agi/agno/blob/main/base.py), the model consults the active `CompressionManager`:

```python
if _compression_manager is not None and _compression_manager.should_compress(messages):
    _compression_manager.compress(messages)

```

The **`should_compress`** method evaluates two criteria:

- **`compress_tool_results_limit`** – triggers compression when the count of un-compressed tool messages exceeds the threshold (default: `3`).
- **`compress_token_limit`** – optional hard ceiling that forces compression when token count exceeds the specified value.

### Compression Execution

When triggered, `CompressionManager.compress` (lines 28–53 in [`libs/agno/agno/compression/manager.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/compression/manager.py)) iterates over tool-role messages lacking `compressed_content`. It constructs a compression prompt—either the user-provided `compress_tool_call_instructions` or the built-in `DEFAULT_COMPRESSION_PROMPT`—and calls the configured LLM to generate a condensed summary.

The result is stored in `msg.compressed_content` while the original `msg.content` remains intact for auditability. Downstream token counting automatically uses the compressed version.

## Enabling and Configuring Context Compression

### Default Behavior

Both `Agent` and `Team` constructors automatically instantiate a `CompressionManager` when `compress_tool_results=True` (the default). Compression activates automatically once un-compressed tool messages exceed the default limit of `3`.

### Custom Configuration

For fine-grained control, instantiate `CompressionManager` explicitly and pass it to your Agent or Team:

```python
from agno.compression.manager import CompressionManager
from agno.agent import Agent

compression_mgr = CompressionManager(
    compress_tool_results=True,
    compress_tool_results_limit=1,      # Compress after every tool call

    compress_token_limit=2000,          # Force compression above 2000 tokens

)

agent = Agent(
    model="gpt-4o-mini",
    tools=[search_tool],
    compression_manager=compression_mgr,
)

```

The same pattern applies to `Team` configurations in [`libs/agno/agno/team/_init.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/team/_init.py) (lines 548–560):

```python
from agno.team import Team
from agno.compression.manager import CompressionManager

team = Team(
    members=[agent_a, agent_b],
    compress_tool_results=True,
    compression_manager=CompressionManager(compress_tool_results_limit=2),
)

```

### Custom Compression Prompts

Override the default summarization behavior by providing domain-specific instructions:

```python
custom_prompt = """
You are a financial analyst. Summarize the numeric data, keep all percentages, dates and ticker symbols.
Remove any narrative fluff.
"""

compression = CompressionManager(
    compress_tool_call_instructions=custom_prompt,
    compress_tool_results_limit=1,
)

```

## Accessing Compression Statistics

After execution, inspect `RunResponse.compression_stats` to verify token savings:

```python
response = agent.run("Summarize the latest research on quantum computing")

if response.compression_stats:
    stats = response.compression_stats
    print(f"Tool results compressed: {stats['tool_results_compressed']}")
    print(f"Original size: {stats['original_size']} tokens")
    print(f"Compressed size: {stats['compressed_size']} tokens")
    print(f"Tokens saved: {stats['original_size'] - stats['compressed_size']}")

```

The built-in CLI and HTML renderers in `libs/agno/agno/utils/print_response/` automatically display these statistics after each run (see [`team.py`](https://github.com/agno-agi/agno/blob/main/team.py) lines 280–287 and the corresponding agent utility).

## Summary

- **Context compression in Agno** automatically summarizes verbose tool outputs before they enter the LLM context, reducing token usage and API costs.
- The **`CompressionManager`** class in [`libs/agno/agno/compression/manager.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/compression/manager.py) orchestrates compression based on message count thresholds (`compress_tool_results_limit`) or token limits (`compress_token_limit`).
- Compression triggers inside `Model._run` ([`libs/agno/agno/models/base.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/models/base.py)) at lines 662–665 (sync) and 874–877 (async), ensuring every tool result is evaluated before the next LLM call.
- Configure compression by passing a custom `CompressionManager` to `Agent` or `Team`, or rely on the default settings (`compress_tool_results=True`, limit of `3`).
- Access runtime statistics via `response.compression_stats` to measure original versus compressed token counts.

## Frequently Asked Questions

### What is the default compression threshold in Agno?

By default, Agno compresses tool results when the number of un-compressed tool messages exceeds **3**. This is controlled by the `compress_tool_results_limit` parameter in `CompressionManager`, which defaults to `3` when `compress_tool_results` is enabled.

### Can I use a custom LLM prompt for compression?

Yes. Pass a custom string to the `compress_tool_call_instructions` parameter when instantiating `CompressionManager`. This prompt overrides the built-in `DEFAULT_COMPRESSION_PROMPT` and allows domain-specific summarization rules—for example, preserving financial metrics while removing narrative text.

### How do I disable context compression entirely?

Set `compress_tool_results=False` in your `Agent` or `Team` constructor. This prevents the automatic instantiation of `CompressionManager` and ensures all tool outputs are passed to the LLM in their original form, regardless of length.

### Does compression work with asynchronous agents?

Yes. The compression check runs in both synchronous and asynchronous execution paths. In [`libs/agno/agno/models/base.py`](https://github.com/agno-agi/agno/blob/main/libs/agno/agno/models/base.py), the asynchronous `run` method includes the same compression logic at lines 874–877 as the synchronous path at lines 662–665, ensuring consistent behavior across async agents and teams.