{"record":{"id":"0956efd432ffe307","repo":"headroomlabs-ai/headroom","slug":"autogen-is-required-for-this-integration-install","errorCode":null,"errorMessage":"AutoGen is required for this integration. Install with: pip install autogen-agentchat","messagePattern":"AutoGen is required for this integration\\. Install with: pip install autogen-agentchat","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"headroom/integrations/autogen/agents.py","lineNumber":58,"sourceCode":"from typing import Any\n\ntry:\n    from autogen_core.tools import FunctionTool\n\n    AUTOGEN_AVAILABLE = True\nexcept ImportError:\n    AUTOGEN_AVAILABLE = False\n    FunctionTool = object  # type: ignore[misc,assignment]\n\nfrom headroom.integrations.mcp import compress_tool_result\n\nlogger = logging.getLogger(__name__)\n\n\ndef _check_autogen_available() -> None:\n    \"\"\"Raise ImportError if AutoGen is not installed.\"\"\"\n    if not AUTOGEN_AVAILABLE:\n        raise ImportError(\n            \"AutoGen is required for this integration. Install with: pip install autogen-agentchat\"\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":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/headroomlabs-ai/headroom/blob/322425c43bffde1ed0b64fecf3cf5951565dd82b/headroom/integrations/autogen/agents.py#L40-L76","documentation":"Raised by _check_autogen_available() in the AutoGen integration when the autogen-agentchat package could not be imported at module load (AUTOGEN_AVAILABLE=False, with FunctionTool stubbed to object). All integration entry points call the guard so that a missing optional dependency surfaces as a clear ImportError with the exact pip package name (autogen-agentchat, not 'autogen') rather than obscure failures from stub base classes.","triggerScenarios":"Using headroom.integrations.autogen.agents' compressed tool wrappers / agent helpers without 'pip install autogen-agentchat'; or having old 'pyautogen' installed (different package) instead of the new autogen-agentchat distribution.","commonSituations":"Confusion between the legacy 'pyautogen' package and the newer 'autogen-agentchat' split packages; minimal headroom installs without integration extras; CI environments missing the extra.","solutions":["pip install autogen-agentchat (the exact distribution named in the message — pyautogeneach/autogen are NOT it).","Install via headroom's integration extra if provided (e.g. headroom[autogen]).","Gate AutoGen-dependent code paths on the AUTOGEN_AVAILABLE flag / a guard call before use.","Confirm with: python -c \"import autogen_agentchat; print('ok')\"."],"exampleFix":"# before\nfrom headroom.integrations.autogen.agents import wrap_tool  # ImportError at use\n\n# after\nfrom headroom.integrations.autogen import agents as hr_autogen\nhr_autogen._check_autogen_available()  # fast, clear failure at startup, not mid-run\nwrap_tool = hr_autogen.wrap_tool","handlingStrategy":"type-guard","validationCode":"import importlib.util\n\nif importlib.util.find_spec(\"autogen_agentchat\") is None:\n    raise SystemExit(\"AutoGen integration needs autogen-agentchat (not pyautogen): pip install autogen-agentchat\")","typeGuard":"import importlib.util\n\ndef autogen_integration_ready() -> bool:\n    \"\"\"True when the modern autogen-agentchat distribution is importable.\"\"\"\n    return importlib.util.find_spec(\"autogen_agentchat\") is not None","tryCatchPattern":"try:\n    from headroom.integrations.autogen.agents import HeadroomAgentTools\nexcept ImportError as e:\n    if \"AutoGen is required\" in str(e):\n        sys.exit(\"pip install autogen-agentchat\")\n    raise","preventionTips":["Use autogen-agentchat, not legacy pyautogen — the guard checks the new distribution.","Pin the integration extra in requirements so CI installs it with headroom.","Feature-detect at startup and disable AutoGen tooling gracefully when unavailable."],"tags":["autogen","import-error","optional-dependency","integration","package-naming"],"backgroundTag":null,"analyzedSha":"322425c43bffde1ed0b64fecf3cf5951565dd82b","analyzedAt":"2026-08-15T01:03:05.481Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}