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

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:

# 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 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, 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 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:

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:

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:

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:

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 – Re-exports the public API including HeadroomAgnoModel, hooks, and utility functions.
• headroom/integrations/agno/model.py – Contains the core wrapper class, metrics handling, and message conversion logic.
• headroom/integrations/agno/providers.py – Implements provider auto-detection for token-counting backends.
• headroom/integrations/agno/hooks.py – Defines pre- and post-hooks for observability and alerting.
• 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 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 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, 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}