microsoft/autogen · critical · ImportError

Distributed runtime features require additional dependencies

Error message

Distributed runtime features require additional dependencies. Install them with: pip install autogen-core[grpc]

What it means

The module _worker_runtime_host.py imports grpc at top level inside a try/except and re-raises ImportError with GRPC_IMPORT_ERROR_STR ('Distributed runtime features require additional dependencies. Install them with: pip install autogen-core[grpc]') when grpc is missing. Importing GrpcWorkerAgentRuntimeHost therefore fails immediately on any Python environment lacking the grpcio stack. The error is raised at import time, before any class is instantiated.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime_host.py:13

import asyncio
import logging
import signal
from typing import Optional, Sequence

from ._constants import GRPC_IMPORT_ERROR_STR
from ._type_helpers import ChannelArgumentType
from ._worker_runtime_host_servicer import GrpcWorkerAgentRuntimeHostServicer

try:
    import grpc
except ImportError as e:
    raise ImportError(GRPC_IMPORT_ERROR_STR) from e
from .protos import agent_worker_pb2_grpc

logger = logging.getLogger("autogen_core")


class GrpcWorkerAgentRuntimeHost:
    def __init__(self, address: str, extra_grpc_config: Optional[ChannelArgumentType] = None) -> None:
        self._server = grpc.aio.server(options=extra_grpc_config)
        self._servicer = GrpcWorkerAgentRuntimeHostServicer()
        agent_worker_pb2_grpc.add_AgentRpcServicer_to_server(self._servicer, self._server)
        self._server.add_insecure_port(address)
        self._address = address
        self._serve_task: asyncio.Task[None] | None = None

    async def _serve(self) -> None:
        await self._server.start()
        logger.info(f"Server started at {self._address}.")
        await self._server.wait_for_termination()

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Install the grpc extra: pip install 'autogen-core[grpc]' (as the message says), and/or 'autogen-ext[grpc]' for the full ext stack
2. Add the extra to your project's requirements/pyproject so environments always include it: autogen-ext[grpc]==<pinned>
3. If you don't need gRPC, import a different runtime (e.g. autogen_core SingleThreadedAgentRuntime) instead of the grpc modules
4. Verify with 'pip show grpcio' or 'python -c "import grpc"' in the exact environment/venv that runs the app

Example fix

# before
pip install autogen-ext
python app.py  # ImportError: Distributed runtime features require additional dependencies...

# after
pip install 'autogen-core[grpc]' 'autogen-ext[grpc]'
python app.py

import importlib.util
grpc_available = importlib.util.find_spec('grpc') is not None
if not grpc_available:
    raise SystemExit('Install dependencies: pip install "autogen-core[grpc]"')

import importlib.util
def grpc_deps_installed() -> bool:
    return importlib.util.find_spec('grpc') is not None

try:
    from autogen_ext.runtimes.grpc import GrpcWorkerAgentRuntimeHost
except ImportError as e:
    if 'autogen-core[grpc]' in str(e):
        raise SystemExit('Missing gRPC extra. Run: pip install "autogen-core[grpc]"') from e
    raise

When it happens

Trigger: Running 'from autogen_ext.runtimes.grpc import GrpcWorkerAgentRuntimeHost' (or anything that transitively imports this module, e.g. autogen_ext.runtimes.grpc.__init__) in an environment where grpcio/grpcio-tools are not installed — i.e. autogen-ext installed without the [grpc] extra and without a manual pip install of grpcio.

Common situations: Fresh environments installing bare 'autogen-ext' instead of 'autogen-ext[grpc]'; CI caches or slim Docker images that prune optional deps; dependency resolvers removing grpcio as 'unused'; upgrading autogen-ext without re-adding the extra.

Related errors

• Distributed runtime features require additional dependencies
• Dependencies for AzureAIAgent not found. Please install auto
• Dependencies for MagenticOneCoderAgent not found. Please ins
• Missing dependecies for DockerCommandLineCodeExecutor. Pleas
• Unauthorized

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/24f97c4cf65b48b1. Report an issue: GitHub.