{"record":{"id":"979ae465d576206d","repo":"headroomlabs-ai/headroom","slug":"crewai-is-required-for-this-integration-install-w","errorCode":null,"errorMessage":"CrewAI is required for this integration. Install with: pip install crewai","messagePattern":"CrewAI is required for this integration\\. Install with: pip install crewai","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/integrations/crewai/agents.py","lineNumber":48,"sourceCode":"from typing import Any\n\ntry:\n    from crewai.tools.base_tool import BaseTool\n\n    CREWAI_AVAILABLE = True\nexcept ImportError:\n    CREWAI_AVAILABLE = False\n    BaseTool = object  # type: ignore[misc,assignment]\n\nfrom headroom.integrations.mcp import compress_tool_result\n\nlogger = logging.getLogger(__name__)\n\n\ndef _check_crewai_available() -> None:\n    \"\"\"Raise ImportError if CrewAI is not installed.\"\"\"\n    if not CREWAI_AVAILABLE:\n        raise ImportError(\n            \"CrewAI is required for this integration. Install with: pip install crewai\"\n        )\n\n\n@dataclass\nclass ToolCompressionMetrics:\n    \"\"\"Metrics from a single tool compression.\n\n    Attributes:\n        tool_name: Name of the tool that was invoked.\n        timestamp: When the compression occurred.\n        chars_before: Character count of the original output.\n        chars_after: Character count after compression.\n        chars_saved: Characters removed by compression.\n        compression_ratio: Ratio of compressed to original size.\n        was_compressed: Whether compression was actually applied.\n    \"\"\"\n","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/crewai/agents.py#L30-L66","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["pip install crewai in the environment your app/notebook kernel actually uses.","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).","Use the exposed CREWAI_AVAILABLE/crewai_available-style flag to gate feature code.","Verify: python -c \"import crewai; print(crewai.__version__)\"."],"exampleFix":"# before\nfrom headroom.integrations.crewai.agents import HeadroomTool  # fails at use\n\n# after\nfrom headroom.integrations.crewai import agents as hr_crewai\nhr_crewai._check_crewai_available()   # fail fast at startup with clear message\nHeadroomTool = hr_crewai.HeadroomTool","handlingStrategy":"type-guard","validationCode":"import importlib.util\n\nif importlib.util.find_spec(\"crewai\") is None:\n    raise SystemExit(\"CrewAI integration unavailable — pip install crewai\")","typeGuard":"import importlib.util\n\ndef crewai_integration_ready() -> bool:\n    \"\"\"True when the crewai SDK is importable in this interpreter.\"\"\"\n    return importlib.util.find_spec(\"crewai\") is not None","tryCatchPattern":"try:\n    from headroom.integrations.crewai.agents import create_compressed_tool\nexcept ImportError as e:\n    if \"CrewAI is required\" in str(e):\n        sys.exit(\"pip install crewai (watch its strict dependency pins)\")\n    raise","preventionTips":["Install crewai in the same env as headroom; its strict pins mean conflicts often break the import silently — verify with 'import crewai' after dependency changes.","Prefer fresh virtualenvs for CrewAI projects to dodge resolver downgrades.","Check availability before building agents so failures happen at startup."],"tags":["crewai","import-error","optional-dependency","integration","dependency-conflict"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}