# How to Integrate Headroom with the Agno Framework: Complete Setup Guide

> Integrate Headroom with the Agno framework easily. Learn how to wrap Agno models with HeadroomAgnoModel for automatic context compression and token-saving optimizations before LLM calls.

- Repository: [Tejas Chopra/headroom](https://github.com/chopratejas/headroom)
- Tags: how-to-guide
- Published: 2026-06-14

---

**Integrate Headroom with the Agno framework by wrapping any Agno model with `HeadroomAgnoModel`, which automatically applies context compression and token-saving optimizations before each LLM call.**

The **chopratejas/headroom** repository provides a first-class integration for the Agno AI-agent framework (formerly Phidata). This integration allows you to add Headroom’s context compression and reversible CCR (Complete Context Retrieval) capabilities to any Agno agent without modifying your existing agent logic. According to the Headroom source code, the integration intercepts LLM calls through a model wrapper, converts Agno `Message` objects to OpenAI-style format for processing, then returns them to Agno’s native format for seamless compatibility.

## Installation and Prerequisites

Before integrating Headroom with Agno, install the required packages using pip:

```bash

# Install Headroom with Agno support

pip install "headroom-ai[agno]"

# Install the Agno framework

pip install agno

```

The `[agno]` extras include all necessary dependencies for the integration, including provider detection utilities and message conversion handlers.

## Core Architecture Components

The Headroom-Agno integration consists of three primary components that work together to optimize token usage while maintaining full compatibility with Agno’s agent lifecycle.

### Model Wrapper (`HeadroomAgnoModel`)

The **`HeadroomAgnoModel`** class in [`headroom/integrations/agno/model.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/agno/model.py) inherits from `agno.models.base.Model` and serves as the primary integration point. This wrapper forwards all Agno-specific methods—including `invoke`, `ainvoke`, and `invoke_stream`—after applying Headroom’s `TransformPipeline` to compress context windows.

The wrapper maintains thread-safe metrics history and tracks a running total of tokens saved via the `total_tokens_saved` attribute. It handles the conversion of Agno `Message` objects to OpenAI-style dictionaries required by Headroom’s optimization engine, then converts the optimized results back to Agno `Message` objects. Extended-thinking blocks used by Claude are preserved untouched and sent to the provider unmodified.

### Provider Detection (`get_headroom_provider`)

Located in [`headroom/integrations/agno/providers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/agno/providers.py), the **`get_headroom_provider`** function inspects the wrapped Agno model’s class name, module path, or model ID to automatically select the appropriate Headroom token-counting provider. This supports major providers including OpenAI, Anthropic, Google, and Cohere, ensuring accurate token estimation regardless of which underlying model your Agno agent uses.

### Observability Hooks (`HeadroomPreHook` and `HeadroomPostHook`)

The optional pre- and post-hooks in [`headroom/integrations/agno/hooks.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/agno/hooks.py) expose detailed token-saving metrics and can emit alerts when requests exceed configurable thresholds. The **`HeadroomPreHook`** runs before optimization, while the **`HeadroomPostHook`** captures metrics after the LLM call completes. These hooks integrate with Agno’s native hook system, allowing you to monitor performance without altering agent logic.

## Basic Integration Example

Wrap any Agno model with `HeadroomAgnoModel` to immediately enable context compression:

```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from headroom.integrations.agno import HeadroomAgnoModel

# Wrap any Agno model

model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))

# Use the wrapped model with a normal Agno agent

agent = Agent(model=model)
response = agent.run("What is the capital of France?")
print(response)
print(f"Tokens saved: {model.total_tokens_saved}")

```

This example demonstrates the zero-code-change approach—your existing Agno agents work unchanged while Headroom automatically compresses context windows and tracks token savings.

## Advanced Usage Patterns

### Adding Observability Hooks

Monitor token usage and set alerts using the pre- and post-hook system:

```python
from headroom.integrations.agno import (
    HeadroomAgnoModel,
    HeadroomPreHook,
    HeadroomPostHook,
    create_headroom_hooks,
)

# Create a model with default config

model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))

# Option 1: Instantiate hooks manually

pre_hook = HeadroomPreHook()
post_hook = HeadroomPostHook(token_alert_threshold=10_000)

# Option 2: Use the convenience factory

pre_hook, post_hook = create_headroom_hooks(
    token_alert_threshold=5_000,
    log_level="DEBUG",
)

agent = Agent(
    model=model,
    pre_hooks=[pre_hook],
    post_hooks=[post_hook],
)

# Run several requests

for q in ["Summarize the latest AI news.", "Write a short poem."]:
    agent.run(q)

print(f"Saved {model.total_tokens_saved} tokens in total")
print("Post-hook summary:", post_hook.get_summary())

```

The `create_headroom_hooks` factory function provides a convenient way to configure both hooks with consistent logging levels and alert thresholds.

### Async Usage for High-Throughput Applications

For asynchronous applications, use the async methods provided by the wrapper:

```python
import asyncio
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from headroom.integrations.agno import HeadroomAgnoModel

async def main() -> None:
    model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))
    agent = Agent(model=model)

    # Async response

    resp = await agent.aresponse(["user", "Explain quantum tunnelling."])
    print(resp)

    # Async streaming

    async for chunk in await agent.aresponse_stream(["user", "Give me a story."]):
        print(chunk, end="", flush=True)

asyncio.run(main())

```

The wrapper transparently handles `ainvoke`, `aresponse`, and `aresponse_stream` methods, ensuring token optimization works for both synchronous and asynchronous execution paths.

### Stand-Alone Optimization Without Agents

Use the `optimize_messages` utility directly when you need context compression without the full Agno agent:

```python
from headroom.integrations.agno import optimize_messages
from agno.models.openai import OpenAIChat

messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Analyse this huge JSON payload..."},
]

opt_msgs, metrics = optimize_messages(
    messages,
    model="gpt-4o",  # Model name for token estimation

)
print(f"Saved {metrics['tokens_saved']} tokens")

```

This approach is useful when preprocessing messages before sending them to external systems or when integrating Headroom’s optimization engine into custom workflows.

## Key Source Files

Understanding the source structure helps with debugging and extending the integration:

- **[`headroom/integrations/agno/__init__.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/agno/__init__.py)** – Re-exports the public API including `HeadroomAgnoModel`, hooks, and utility functions.
- **[`headroom/integrations/agno/model.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/agno/model.py)** – Contains the core wrapper class, metrics handling, and message conversion logic.
- **[`headroom/integrations/agno/providers.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/agno/providers.py)** – Implements provider auto-detection for token-counting backends.
- **[`headroom/integrations/agno/hooks.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/agno/hooks.py)** – Defines pre- and post-hooks for observability and alerting.
- **[`wiki/agno.md`](https://github.com/chopratejas/headroom/blob/main/wiki/agno.md)** – Official documentation with additional examples and configuration options.

## Summary

- **Wrap Agno models** with `HeadroomAgnoModel` to enable automatic context compression and token optimization.
- **Use `create_headroom_hooks`** to add observability and alerting without modifying agent logic.
- **Support async workflows** through `ainvoke`, `aresponse`, and `aresponse_stream` method forwarding.
- **Leverage provider auto-detection** in [`providers.py`](https://github.com/chopratejas/headroom/blob/main/providers.py) to ensure accurate token counting across OpenAI, Anthropic, Google, and Cohere models.
- **Preserve Agno compatibility** via automatic message format conversion and untouched extended-thinking blocks.

## Frequently Asked Questions

### How does HeadroomAgnoModel handle message format conversion?

The wrapper converts Agno `Message` objects to OpenAI-style dictionaries before processing through Headroom’s `TransformPipeline`, then converts the optimized results back to Agno `Message` objects. This ensures Agno’s logging, tool-loop machinery, and agent lifecycle continue to function normally while benefiting from context compression.

### Can I use Headroom with async Agno agents?

Yes. The `HeadroomAgnoModel` class in [`headroom/integrations/agno/model.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/agno/model.py) forwards async methods including `ainvoke`, `aresponse`, and `aresponse_stream`. The wrapper applies the same optimization pipeline to async calls, making it suitable for high-throughput applications requiring non-blocking execution.

### Does Headroom support Claude’s extended thinking blocks?

Yes. According to the source code in [`headroom/integrations/agno/model.py`](https://github.com/chopratejas/headroom/blob/main/headroom/integrations/agno/model.py), extended-thinking blocks used by Claude are preserved untouched and sent to the provider unmodified. This ensures that reasoning capabilities are not disrupted by the compression pipeline.

### How do I monitor token savings across multiple agent runs?

Access the `total_tokens_saved` attribute on your `HeadroomAgnoModel` instance after each run. For detailed per-request metrics, attach a `HeadroomPostHook` to your agent and configure it with a `token_alert_threshold` to receive alerts when specific usage limits are exceeded.