microsoft/autogen · error · ImportError

To use the GRPC runtime the grpc extra must be installed. Ru

Error message

To use the GRPC runtime the grpc extra must be installed. Run `pip install autogen-ext[grpc]`

What it means

The autogen_ext.runtimes.grpc package lazily requires the grpcio library but does not declare it as a hard dependency; it is an optional extra. Importing the package without grpcio installed raises this ImportError with the exact pip extra to install.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/__init__.py:8

from ._worker_runtime import GrpcWorkerAgentRuntime
from ._worker_runtime_host import GrpcWorkerAgentRuntimeHost
from ._worker_runtime_host_servicer import GrpcWorkerAgentRuntimeHostServicer

try:
    import grpc  # type: ignore
except ImportError as e:
    raise ImportError(
        "To use the GRPC runtime the grpc extra must be installed. Run `pip install autogen-ext[grpc]`"
    ) from e

__all__ = [
    "GrpcWorkerAgentRuntime",
    "GrpcWorkerAgentRuntimeHost",
    "GrpcWorkerAgentRuntimeHostServicer",
]

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Install the extra: `pip install autogen-ext[grpc]`
2. Add `autogen-ext[grpc]` (pinned to the same version as autogen-core) to requirements.txt / pyproject.toml
3. If you do not need distributed agents, import a non-gRPC runtime (e.g. SingleThreadedAgentRuntime) instead

Example fix

# before
pip install autogen-ext

# after
pip install "autogen-ext[grpc]

import importlib.util

def grpc_extra_installed() -> bool:
    return importlib.util.find_spec("grpc") is not None

if not grpc_extra_installed():
    raise SystemExit("Missing dependency: pip install autogen-ext[grpc]")

try:
    from autogen_ext.runtimes.grpc import GrpcWorkerAgentRuntime
except ImportError as e:
    print("install with: pip install autogen-ext[grpc]", file=sys.stderr)
    raise SystemExit(1) from e

When it happens

Trigger: Running `import autogen_ext.runtimes.grpc` (or instantiating GrpcWorkerAgentRuntime / GrpcWorkerAgentRuntimeHost) in an environment where the `pip install autogen-ext[grpc]` extra was never installed.

Common situations: Installing plain `autogen-ext` instead of `autogen-ext[grpc]`; CI caches or slim Docker images that only install base deps; adding distributed-runtime code to a project whose requirements.txt was generated from a non-gRPC setup.

Related errors

• Distributed runtime features require additional dependencies
• Unsupported subscription type.
• Invalid subscription message.
• Connection is not open.
• Unsupported payload serialization format: {payload_serializa

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