headroomlabs-ai/headroom · error · ImportError

CrewAI is required for this integration. Install with: pip i

Error message

CrewAI is required for this integration. Install with: pip install crewai

What it means

Raised by _check_crewai_available() in the CrewAI integration when the crewai package import failed at module load (CREWAI_AVAILABLE=False, BaseTool stubbed to object). The headroom core is importable without CrewAI; the guard converts usage of the integration into an ImportError that names the exact pip package, instead of leaking the object-stub base classes into user code where they would fail confusingly.

Source

Thrown at headroom/integrations/crewai/agents.py:48

from typing import Any

try:
    from crewai.tools.base_tool import BaseTool

    CREWAI_AVAILABLE = True
except ImportError:
    CREWAI_AVAILABLE = False
    BaseTool = object  # type: ignore[misc,assignment]

from headroom.integrations.mcp import compress_tool_result

logger = logging.getLogger(__name__)


def _check_crewai_available() -> None:
    """Raise ImportError if CrewAI is not installed."""
    if not CREWAI_AVAILABLE:
        raise ImportError(
            "CrewAI is required for this integration. Install with: pip install crewai"
        )


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

    Attributes:
        tool_name: Name of the tool that was invoked.
        timestamp: When the compression occurred.
        chars_before: Character count of the original output.
        chars_after: Character count after compression.
        chars_saved: Characters removed by compression.
        compression_ratio: Ratio of compressed to original size.
        was_compressed: Whether compression was actually applied.
    """

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install crewai in the environment your app/notebook kernel actually uses.
2. If it was installed and broke, reinstall cleanly: pip install --force-reinstall crewai (its strict pins make dependency conflicts the top cause of the import failing).
3. Use the exposed CREWAI_AVAILABLE/crewai_available-style flag to gate feature code.
4. Verify: python -c "import crewai; print(crewai.__version__)".

Example fix

# before
from headroom.integrations.crewai.agents import HeadroomTool  # fails at use

# after
from headroom.integrations.crewai import agents as hr_crewai
hr_crewai._check_crewai_available()   # fail fast at startup with clear message
HeadroomTool = hr_crewai.HeadroomTool

import importlib.util

if importlib.util.find_spec("crewai") is None:
    raise SystemExit("CrewAI integration unavailable — pip install crewai")

import importlib.util

def crewai_integration_ready() -> bool:
    """True when the crewai SDK is importable in this interpreter."""
    return importlib.util.find_spec("crewai") is not None

try:
    from headroom.integrations.crewai.agents import create_compressed_tool
except ImportError as e:
    if "CrewAI is required" in str(e):
        sys.exit("pip install crewai (watch its strict dependency pins)")
    raise

When it happens

Trigger: Building CrewAI agents with headroom's compressed tool wrappers without 'pip install crewai'; crewai installed but broken by a transitive dependency conflict (common, since crewai pins strictly); wrong interpreter/venv.

Common situations: Fresh projects that add headroom but not crewai; pip resolver downgrading/breaking crewai deps after adding other packages; notebooks whose kernel env differs from the shell env where crewai was installed.

Related errors

• Agno is required for this integration. Install with: pip ins
• AutoGen is required for this integration. Install with: pip
• 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/979ae465d576206d. Report an issue: GitHub.