headroomlabs-ai/headroom · error · ImportError

AutoGen is required for this integration. Install with: pip

Error message

AutoGen is required for this integration. Install with: pip install autogen-agentchat

What it means

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.

Source

Thrown at headroom/integrations/autogen/agents.py:58

from typing import Any

try:
    from autogen_core.tools import FunctionTool

    AUTOGEN_AVAILABLE = True
except ImportError:
    AUTOGEN_AVAILABLE = False
    FunctionTool = object  # type: ignore[misc,assignment]

from headroom.integrations.mcp import compress_tool_result

logger = logging.getLogger(__name__)


def _check_autogen_available() -> None:
    """Raise ImportError if AutoGen is not installed."""
    if not AUTOGEN_AVAILABLE:
        raise ImportError(
            "AutoGen is required for this integration. Install with: pip install autogen-agentchat"
        )


@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 autogen-agentchat (the exact distribution named in the message — pyautogeneach/autogen are NOT it).
2. Install via headroom's integration extra if provided (e.g. headroom[autogen]).
3. Gate AutoGen-dependent code paths on the AUTOGEN_AVAILABLE flag / a guard call before use.
4. Confirm with: python -c "import autogen_agentchat; print('ok')".

Example fix

# before
from headroom.integrations.autogen.agents import wrap_tool  # ImportError at use

# after
from headroom.integrations.autogen import agents as hr_autogen
hr_autogen._check_autogen_available()  # fast, clear failure at startup, not mid-run
wrap_tool = hr_autogen.wrap_tool

import importlib.util

if importlib.util.find_spec("autogen_agentchat") is None:
    raise SystemExit("AutoGen integration needs autogen-agentchat (not pyautogen): pip install autogen-agentchat")

import importlib.util

def autogen_integration_ready() -> bool:
    """True when the modern autogen-agentchat distribution is importable."""
    return importlib.util.find_spec("autogen_agentchat") is not None

try:
    from headroom.integrations.autogen.agents import HeadroomAgentTools
except ImportError as e:
    if "AutoGen is required" in str(e):
        sys.exit("pip install autogen-agentchat")
    raise

When it happens

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

Common situations: Confusion between the legacy 'pyautogen' package and the newer 'autogen-agentchat' split packages; minimal headroom installs without integration extras; CI environments missing the extra.

Related errors

• Agno is required for this integration. Install with: pip ins
• CrewAI is required for this integration. Install with: pip i
• 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/0956efd432ffe307. Report an issue: GitHub.