headroomlabs-ai/headroom · error · ImportError

Strands SDK is required for this integration. Install with:

Error message

Strands SDK is required for this integration. Install with: pip install strands-agents

What it means

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.

Source

Thrown at headroom/integrations/strands/hooks.py:62

    HookProvider = object  # type: ignore[misc,assignment]
    HookRegistry = object  # type: ignore[misc,assignment]
    AfterToolCallEvent = object  # type: ignore[misc,assignment]
    BeforeToolCallEvent = object  # type: ignore[misc,assignment]
    ToolResult = dict  # type: ignore[misc,assignment]

from headroom import HeadroomConfig
from headroom.ccr.tool_injection import CCR_TOOL_NAME
from headroom.config import is_tool_excluded
from headroom.telemetry.session import BeaconCompressionObserver
from headroom.transforms.smart_crusher import SmartCrusher, SmartCrusherConfig

logger = logging.getLogger(__name__)


def _check_strands_available() -> None:
    """Raise ImportError if Strands is not installed."""
    if not STRANDS_AVAILABLE:
        raise ImportError(
            "Strands SDK is required for this integration. Install with: pip install strands-agents"
        )


def strands_available() -> bool:
    """Check if Strands SDK is installed.

    Returns:
        True if strands-agents package is available.
    """
    return STRANDS_AVAILABLE


@dataclass
class CompressionMetrics:
    """Metrics from a single tool output compression."""

    request_id: str

View on GitHub (pinned to 322425c43b)

Solutions

1. Install the SDK: `pip install strands-agents` (or headroom's [strands] extra if declared)
2. Gate usage with `from headroom.integrations.strands.hooks import strands_available; if strands_available(): ...`
3. If strands-agents IS installed, verify its version still exposes the imported symbols and check the module's try/except import block

Example fix

# before
from headroom.integrations.strands.hooks import apply_headroom_hooks
apply_headroom_hooks(agent)  # ImportError

# after
# pip install strands-agents
from headroom.integrations.strands.hooks import apply_headroom_hooks, strands_available
assert strands_available(), 'install strands-agents'
apply_headroom_hooks(agent)

import importlib.util
assert importlib.util.find_spec('strands'), 'pip install strands-agents before applying headroom hooks'

from headroom.integrations.strands.hooks import strands_available
if strands_available():
    apply_headroom_hooks(agent)

try:
    apply_headroom_hooks(agent)
except ImportError as e:
    logger.warning('Running Strands agent without headroom hooks: %s', e)

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Strands SDK is required for this integration. Install with:
• Bedrock with temporary credentials (AWS_SESSION_TOKEN) requi
• anthropic package required. Install with: pip install anthro
• openai package required. Install with: pip install openai
• ollama package required. Install with: pip install ollama

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