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

_worker_runtime_host_servicer.py, the gRPC servicer backing GrpcWorkerAgentRuntimeHost, imports grpc under try/except and re-raises ImportError with GRPC_IMPORT_ERROR_STR when grpcio is absent. Because GrpcWorkerAgentRuntimeHost imports this servicer module at package load, any use of the host in an environment without the [grpc] extra fails at import time with 'Distributed runtime features require additional dependencies. Install them with: pip install autogen-core[grpc]'.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime_host_servicer.py:19

from __future__ import annotations

import asyncio
import logging
from abc import ABC, abstractmethod
from asyncio import Future, Task
from typing import Any, AsyncIterator, Awaitable, Callable, Dict, Generic, Sequence, Set, Tuple, TypeVar

from autogen_core import TopicId
from autogen_core._agent_id import AgentId
from autogen_core._runtime_impl_helpers import SubscriptionManager

from ._constants import GRPC_IMPORT_ERROR_STR
from ._utils import subscription_from_proto, subscription_to_proto

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

from .protos import agent_worker_pb2, agent_worker_pb2_grpc, cloudevent_pb2

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

ClientConnectionId = str


def metadata_to_dict(metadata: Sequence[Tuple[str, str]] | None) -> Dict[str, str]:
    if metadata is None:
        return {}
    return {key: value for key, value in metadata}


async def get_client_id_or_abort(context: grpc.aio.ServicerContext[Any, Any]) -> str:  # type: ignore
    # The type hint on context.invocation_metadata() is incorrect.
    metadata = metadata_to_dict(context.invocation_metadata())  # type: ignore

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Install the extra in the running environment: pip install 'autogen-core[grpc]' (and typically 'autogen-ext[grpc]')
2. Pin the extra in pyproject/requirements (autogen-ext[grpc]==X.Y.Z) so every environment gets grpcio
3. Confirm the right interpreter: python -m pip install 'autogen-core[grpc]' inside the venv that executes the app
4. If gRPC is unwanted, switch to autogen_core's SingleThreadedAgentRuntime and remove grpc imports

Example fix

# before
$ pip install autogen-ext
$ python -m my_worker  # ImportError: Distributed runtime features require...

# after
$ python -m pip install 'autogen-core[grpc]' 'autogen-ext[grpc]'
$ python -m my_worker

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._worker_runtime_host_servicer import GrpcWorkerAgentRuntimeHostServicer
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: Importing autogen_ext.runtimes.grpc (or instantiating GrpcWorkerAgentRuntimeHost / GrpcWorkerAgentRuntime) in a venv where autogen-ext was installed without the [grpc] extra and grpcio was never installed separately; fresh clones where only base requirements were installed; environments where a resolver dropped grpcio.

Common situations: Bare 'pip install autogen-ext' in tutorials/docs that assume the extra; slim production images pruning 'optional' packages; CI matrices that install minimal deps; conda/mix environments where grpcio exists for a different interpreter.

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/bcf5df6be58d2da1. Report an issue: GitHub.