microsoft/autogen · error · 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

GrpcWorkerAgentRuntime's module imports grpc.aio at load time; without the optional grpcio dependency the module raises ImportError with GRPC_IMPORT_ERROR_STR pointing to `pip install autogen-core[grpc]`. This guard fires on the first import of autogen_ext.runtimes.grpc._worker_runtime, before any runtime behavior runs.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py:69

from autogen_core._serialization import (
    SerializationRegistry,
)
from autogen_core._telemetry import MessageRuntimeTracingConfig, TraceHelper, get_telemetry_grpc_metadata
from google.protobuf import any_pb2
from opentelemetry.trace import TracerProvider
from typing_extensions import Self

from autogen_ext.runtimes.grpc._utils import subscription_to_proto

from . import _constants
from ._constants import GRPC_IMPORT_ERROR_STR
from ._type_helpers import ChannelArgumentType
from .protos import agent_worker_pb2, agent_worker_pb2_grpc, cloudevent_pb2

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

if TYPE_CHECKING:
    from .protos.agent_worker_pb2_grpc import AgentRpcAsyncStub

logger = logging.getLogger("autogen_core")
event_logger = logging.getLogger("autogen_core.events")

P = ParamSpec("P")
T = TypeVar("T", bound=Agent)


type_func_alias = type


class QueueAsyncIterable(AsyncIterator[Any], AsyncIterable[Any]):
    def __init__(self, queue: asyncio.Queue[Any]) -> None:
        self._queue = queue

View on GitHub (pinned to 027ecf0a37)

Solutions

Install the extra: `pip install autogen-core[grpc]` (and/or autogen-ext[grpc])
Pin the extras in your dependency manifest so fresh environments get grpcio automatically
Guard the import in code that optionally supports gRPC: wrap in try/except ImportError and fall back to a local runtime

Example fix

# before
from autogen_ext.runtimes.grpc import GrpcWorkerAgentRuntime  # ImportError

# after (install first: pip install autogen-core[grpc])
from autogen_ext.runtimes.grpc import GrpcWorkerAgentRuntime

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("grpc.aio") is None:
    raise SystemExit("Missing dependency: pip install autogen-core[grpc]")

from autogen_ext.runtimes.grpc import GrpcWorkerAgentRuntime

Try / catch

try:
    from autogen_ext.runtimes.grpc._worker_runtime import GrpcWorkerAgentRuntime
except ImportError as e:
    if "grpc extra" in str(e):
        subprocess.check_call([sys.executable, "-m", "pip", "install", "autogen-core[grpc]"])
    raise

Prevention

Install extras via the documented pip extra names
Verify environments with a startup dependency check
Avoid deep imports of private modules in user code; import from the package root

When it happens

Trigger: Importing GrpcWorkerAgentRuntime (usually via `from autogen_ext.runtimes.grpc import GrpcWorkerAgentRuntime`) or the module _worker_runtime in an environment lacking the grpc extra.

Common situations: Same class of issue as the package-level guard but hit when the submodule is imported directly; deploying to environments where only autogen-core (not the [grpc] extra) was installed; documentation samples that assume the extra.

Related errors

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