microsoft/semantic-kernel · error · RuntimeError

Failed to preload the following built-in agent modules: {err

Error message

Failed to preload the following built-in agent modules:
{error_msgs}

What it means

Before creating agents from YAML/dict, _preload_builtin_agents imports all built-in agent modules so their @register_agent_type decorators run. If any of those modules raises during import, the collected failures are bundled into this RuntimeError. The root cause is in the inner ImportError/ModuleNotFoundError (e.g. a missing optional dependency for one agent family).

Source

Thrown at python/semantic_kernel/agents/agent.py:697

    if _BUILTIN_AGENTS_LOADED:
        return

    with _BUILTIN_AGENTS_LOCK:
        if _BUILTIN_AGENTS_LOADED:
            return  # Double-checked locking

        failed = []

        for module_name in _BUILTIN_AGENT_MODULES:
            try:
                importlib.import_module(module_name)
            except Exception as ex:
                failed.append((module_name, ex))

        if failed:
            error_msgs = "\n".join(f"- {mod}: {err}" for mod, err in failed)
            raise RuntimeError(f"Failed to preload the following built-in agent modules:\n{error_msgs}")

        _BUILTIN_AGENTS_LOADED = True


class AgentRegistry:
    """Responsible for creating agents from YAML, dicts, or files."""

    @staticmethod
    def register_type(agent_type: str, agent_cls: type[Agent]) -> None:
        """Register a new agent type at runtime.

        Args:
            agent_type: The string identifier representing the agent type (e.g., 'chat_completion_agent').
            agent_cls: The class implementing the agent, inheriting from `Agent`.

        Example:
            AgentRegistry.register_type("my_custom_agent", MyCustomAgent)
        """

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Read the inner per-module error in the message — it names the failing module and the underlying exception (usually ModuleNotFoundError).
2. Install the missing optional dependency the failing module needs (e.g. pip install 'semantic_kernel[openai]' or the specific third-party package).
3. Reinstall/repair the semantic_kernel package if the install is partial or corrupted.
4. Pin compatible versions of connector packages matching your semantic-kernel version.

Example fix

# Message lists the failing module(s), e.g.:
# - semantic_kernel.agents.azure_ai.azure_ai_agent: ModuleNotFoundError: No module named 'azure_ai'
# Fix: install the missing extra
pip install 'semantic_kernel[azure]'  # or the specific package the error names

# Pre-check that the agent family's optional dependency is importable.
import importlib.util
mods = ['openai', 'azure.ai.projects']  # adjust to the family you use
missing = [m for m in mods if importlib.util.find_spec(m) is None]
assert not missing, f'Install missing extras: {missing}'

try:
    agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)
except RuntimeError as e:
    if 'Failed to preload' in str(e):
        # parse per-module errors, install missing deps, retry
        print(e)
    raise

When it happens

Trigger: Calling AgentRegistry.create_from_yaml/dict/file when an optional dependency (e.g. openai, azure-ai, autogen, bedrock, copilotstudio packages) for a built-in agent module is not installed; a broken/partial install of semantic-kernel.

Common situations: Installing semantic-kernel without the needed extras; upgrading one package to an incompatible version; missing system libs for a connector.

Related errors

• module {__name__} has no attribute {name}
• Agent with name {agentId.Type} not found.
• Thread has been deleted; call `create()` to recreate it.
• Cannot create thread because it has already been deleted.
• Unable to get channel keys. Channel type not configured.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/610893a6ba0f9581. Report an issue: GitHub.