{"record":{"id":"8527502992bcea19","repo":"headroomlabs-ai/headroom","slug":"strands-sdk-is-required-for-this-integration-inst","errorCode":null,"errorMessage":"Strands SDK is required for this integration. Install with: pip install strands-agents","messagePattern":"Strands SDK is required for this integration\\. Install with: pip install strands-agents","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/integrations/strands/hooks.py","lineNumber":62,"sourceCode":"    HookProvider = object  # type: ignore[misc,assignment]\n    HookRegistry = object  # type: ignore[misc,assignment]\n    AfterToolCallEvent = object  # type: ignore[misc,assignment]\n    BeforeToolCallEvent = object  # type: ignore[misc,assignment]\n    ToolResult = dict  # type: ignore[misc,assignment]\n\nfrom headroom import HeadroomConfig\nfrom headroom.ccr.tool_injection import CCR_TOOL_NAME\nfrom headroom.config import is_tool_excluded\nfrom headroom.telemetry.session import BeaconCompressionObserver\nfrom headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig\n\nlogger = logging.getLogger(__name__)\n\n\ndef _check_strands_available() -> None:\n    \"\"\"Raise ImportError if Strands is not installed.\"\"\"\n    if not STRANDS_AVAILABLE:\n        raise ImportError(\n            \"Strands SDK is required for this integration. Install with: pip install strands-agents\"\n        )\n\n\ndef strands_available() -> bool:\n    \"\"\"Check if Strands SDK is installed.\n\n    Returns:\n        True if strands-agents package is available.\n    \"\"\"\n    return STRANDS_AVAILABLE\n\n\n@dataclass\nclass CompressionMetrics:\n    \"\"\"Metrics from a single tool output compression.\"\"\"\n\n    request_id: str","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/strands/hooks.py#L44-L80","documentation":"Raised by _check_strands_available() in headroom/integrations/strands/hooks.py when the module-level STRANDS_AVAILABLE flag is False, i.e. `import strands...` failed at load time. It guards the Strands Agents hooks integration (CCR tool injection via CCR_TOOL_NAME, SmartCrusher compression, BeaconCompressionObserver telemetry) for AWS's strands-agents SDK.","triggerScenarios":"Calling any function on the Strands hooks integration — applying headroom hooks to a Strands agent/tool registry — in an environment where the strands-agents package is not installed; the public strands_available() helper exists so callers can probe first.","commonSituations":"Plain `pip install headroom` without the [strands] extra; prototyping Strands integrations locally but deploying a minimal image; a renamed/moved strands-agents package version whose import path changed, silently flipping STRANDS_AVAILABLE to False.","solutions":["Install the SDK: `pip install strands-agents` (or headroom's [strands] extra if declared)","Gate usage with `from headroom.integrations.strands.hooks import strands_available; if strands_available(): ...`","If strands-agents IS installed, verify its version still exposes the imported symbols and check the module's try/except import block"],"exampleFix":"# before\nfrom headroom.integrations.strands.hooks import apply_headroom_hooks\napply_headroom_hooks(agent)  # ImportError\n\n# after\n# pip install strands-agents\nfrom headroom.integrations.strands.hooks import apply_headroom_hooks, strands_available\nassert strands_available(), 'install strands-agents'\napply_headroom_hooks(agent)","handlingStrategy":"validation","validationCode":"import importlib.util\nassert importlib.util.find_spec('strands'), 'pip install strands-agents before applying headroom hooks'","typeGuard":"from headroom.integrations.strands.hooks import strands_available\nif strands_available():\n    apply_headroom_hooks(agent)","tryCatchPattern":"try:\n    apply_headroom_hooks(agent)\nexcept ImportError as e:\n    logger.warning('Running Strands agent without headroom hooks: %s', e)","preventionTips":["Use the module's own strands_available() probe before wiring hooks","Include strands-agents in the deploy spec when the integration is used","Fail fast at app start rather than at first tool call"],"tags":["strands","aws","import-error","optional-dependency"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}