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/model.py when STRANDS_AVAILABLE is False. It guards the Strands model wrapper (Headroom model class that routes through get_headroom_provider/get_model_name_from_strands and emits OptimizationMetrics per optimization pass) — the Strands equivalent of the LangChain chat model.

Source

Thrown at headroom/integrations/strands/model.py:50

    ToolChoice = dict  # type: ignore[misc,assignment]
    ToolSpec = dict  # type: ignore[misc,assignment]
    SystemContentBlock = dict  # type: ignore[misc,assignment]

T = TypeVar("T")

from headroom import HeadroomConfig  # noqa: E402
from headroom.providers import OpenAIProvider  # noqa: E402
from headroom.transforms import TransformPipeline  # noqa: E402

from .providers import get_headroom_provider, get_model_name_from_strands  # noqa: E402

logger = logging.getLogger(__name__)


def _check_strands_available() -> None:
    """Raise ImportError if Strands SDK 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."""
    return STRANDS_AVAILABLE


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

    request_id: str
    timestamp: datetime
    tokens_before: int
    tokens_after: int
    tokens_saved: int

View on GitHub (pinned to 322425c43b)

Solutions

1. Install `pip install strands-agents`
2. Probe with strands_available() from this module before selecting the model at runtime
3. Add strands-agents to the deployment lockfile

Example fix

# before
from headroom.integrations.strands.model import HeadroomStrandsModel
model = HeadroomStrandsModel(...)  # ImportError

# after
# pip install strands-agents
from headroom.integrations.strands.model import HeadroomStrandsModel, strands_available
if strands_available():
    model = HeadroomStrandsModel(...)

import importlib.util
assert importlib.util.find_spec('strands'), 'pip install strands-agents before using the Headroom Strands model'

from headroom.integrations.strands.model import strands_available
model = HeadroomStrandsModel(...) if strands_available() else default_model

try:
    model = HeadroomStrandsModel(...)
except ImportError as e:
    logger.warning('Falling back to plain Strands model: %s', e)
    model = original_model

When it happens

Trigger: Instantiating the Headroom Strands model class or using it as a Strands LLM backend when the strands-agents package is not importable; the file even uses `# noqa: E402` on imports because it sits after a large conditional import block, underlining that availability is resolved at module load.

Common situations: Swapping a Strands agent's model to the headroom-optimized one before installing strands-agents; version drift in strands-agents breaking the import; CI matrix cells that only install core headroom.

Related errors

• Strands SDK is required for this integration. Install with:
• anthropic package required. Install with: pip install anthro
• openai package required. Install with: pip install openai
• ollama package required. Install with: pip install ollama
• Agno is required for this integration. Install with: pip ins

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