{"record":{"id":"731c088dea598370","repo":"headroomlabs-ai/headroom","slug":"agno-is-required-for-this-integration-install-wit","errorCode":null,"errorMessage":"Agno is required for this integration. Install with: pip install agno","messagePattern":"Agno is required for this integration\\. Install with: pip install agno","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/integrations/agno/model.py","lineNumber":45,"sourceCode":"    AGNO_AVAILABLE = False\n    Model = object  # type: ignore[misc,assignment]\n    Message = dict  # type: ignore[misc,assignment]\n    ModelResponse = dict  # type: ignore[misc,assignment]\n\nfrom headroom import HeadroomConfig, HeadroomMode\nfrom headroom.parser import _coerce_tool_call_to_dict\nfrom headroom.providers import OpenAIProvider\nfrom headroom.transforms import TransformPipeline\n\nfrom .providers import get_headroom_provider, get_model_name_from_agno\n\nlogger = logging.getLogger(__name__)\n\n\ndef _check_agno_available() -> None:\n    \"\"\"Raise ImportError if Agno is not installed.\"\"\"\n    if not AGNO_AVAILABLE:\n        raise ImportError(\"Agno is required for this integration. Install with: pip install agno\")\n\n\ndef agno_available() -> bool:\n    \"\"\"Check if Agno is installed.\"\"\"\n    return AGNO_AVAILABLE\n\n\n@dataclass\nclass OptimizationMetrics:\n    \"\"\"Metrics from a single optimization pass.\"\"\"\n\n    request_id: str\n    timestamp: datetime\n    tokens_before: int\n    tokens_after: int\n    tokens_saved: int\n    savings_percent: float\n    transforms_applied: list[str]","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/agno/model.py#L27-L63","documentation":"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.","triggerScenarios":"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.","commonSituations":"Installing plain 'pip install headroom' without the agno extra; using the wrong virtualenv; agno installed but its pinned deps conflict/broken in the env.","solutions":["pip install agno in the interpreter running your app.","If your project pins headroom extras, declare the agno extra (e.g. headroom[agno]) so it installs together.","Guard feature code with agno_available() before touching integration classes (the module exposes that helper).","If agno IS installed, debug why 'import agno' fails standalone: python -c \"import agno\"."],"exampleFix":"# before\nfrom headroom.integrations.agno.model import HeadroomModel\nm = HeadroomModel(...)  # ImportError: Agno is required\n\n# after\nfrom headroom.integrations.agno.model import HeadroomModel, agno_available\nif not agno_available():\n    raise SystemExit(\"install agno: pip install agno\")\nm = HeadroomModel(...)","handlingStrategy":"type-guard","validationCode":"from headroom.integrations.agno.model import agno_available\n\nif not agno_available():\n    raise SystemExit(\"Agno integration unavailable — pip install agno\")","typeGuard":"from headroom.integrations.agno.model import agno_available\n\ndef can_use_agno_integration() -> bool:\n    \"\"\"True when the agno SDK is importable and integration classes are real.\"\"\"\n    return agno_available()","tryCatchPattern":"try:\n    from headroom.integrations.agno.model import HeadroomModel\n    model = HeadroomModel(...)\nexcept ImportError as e:\n    if \"Agno is required\" in str(e):\n        sys.exit(\"pip install agno to use the Agno integration\")\n    raise","preventionTips":["Declare the agno dependency (or headroom extra) in projects that use the integration.","Gate imports of integration modules behind agno_available() so optional features degrade cleanly.","Fail fast at app startup, not on the first agent request."],"tags":["agno","import-error","optional-dependency","integration","feature-flag"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}