headroomlabs-ai/headroom · error · ImportError

Agno is required for this integration. Install with: pip ins

Error message

Agno is required for this integration. Install with: pip install agno

What it means

Raised by _check_agno_available() in the Agno integration when the agno package failed to import at module load (AGNO_AVAILABLE=False). The integration module imports unconditionally (with a try/except setting the flag) so that headroom can be installed without Agno, but every Agno-facing entry point calls this guard first, converting the missing optional dependency into an actionable ImportError instead of a NameError from a stubbed base class.

Source

Thrown at headroom/integrations/agno/model.py:45

    AGNO_AVAILABLE = False
    Model = object  # type: ignore[misc,assignment]
    Message = dict  # type: ignore[misc,assignment]
    ModelResponse = dict  # type: ignore[misc,assignment]

from headroom import HeadroomConfig, HeadroomMode
from headroom.parser import _coerce_tool_call_to_dict
from headroom.providers import OpenAIProvider
from headroom.transforms import TransformPipeline

from .providers import get_headroom_provider, get_model_name_from_agno

logger = logging.getLogger(__name__)


def _check_agno_available() -> None:
    """Raise ImportError if Agno is not installed."""
    if not AGNO_AVAILABLE:
        raise ImportError("Agno is required for this integration. Install with: pip install agno")


def agno_available() -> bool:
    """Check if Agno is installed."""
    return AGNO_AVAILABLE


@dataclass
class OptimizationMetrics:
    """Metrics from a single optimization pass."""

    request_id: str
    timestamp: datetime
    tokens_before: int
    tokens_after: int
    tokens_saved: int
    savings_percent: float
    transforms_applied: list[str]

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install agno in the interpreter running your app.
2. If your project pins headroom extras, declare the agno extra (e.g. headroom[agno]) so it installs together.
3. Guard feature code with agno_available() before touching integration classes (the module exposes that helper).
4. If agno IS installed, debug why 'import agno' fails standalone: python -c "import agno".

Example fix

# before
from headroom.integrations.agno.model import HeadroomModel
m = HeadroomModel(...)  # ImportError: Agno is required

# after
from headroom.integrations.agno.model import HeadroomModel, agno_available
if not agno_available():
    raise SystemExit("install agno: pip install agno")
m = HeadroomModel(...)

from headroom.integrations.agno.model import agno_available

if not agno_available():
    raise SystemExit("Agno integration unavailable — pip install agno")

from headroom.integrations.agno.model import agno_available

def can_use_agno_integration() -> bool:
    """True when the agno SDK is importable and integration classes are real."""
    return agno_available()

try:
    from headroom.integrations.agno.model import HeadroomModel
    model = HeadroomModel(...)
except ImportError as e:
    if "Agno is required" in str(e):
        sys.exit("pip install agno to use the Agno integration")
    raise

When it happens

Trigger: Importing/using headroom.integrations.agno.model's HeadroomModel (or any integration entry point) in an environment without 'pip install agno'. Also when agno is installed but its own import fails (broken transitive deps), since the flag is set from a bare except ImportError at module top.

Common situations: Installing plain 'pip install headroom' without the agno extra; using the wrong virtualenv; agno installed but its pinned deps conflict/broken in the env.

Related errors

• AutoGen is required for this integration. Install with: pip
• CrewAI is required for this integration. Install with: pip i
• LangChain is required for this integration. Install with: pi
• anthropic package required. Install with: pip install anthro
• openai package required. Install with: pip install openai

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/731c088dea598370. Report an issue: GitHub.