{"record":{"id":"610893a6ba0f9581","repo":"microsoft/semantic-kernel","slug":"failed-to-preload-the-following-built-in-agent-mod","errorCode":null,"errorMessage":"Failed to preload the following built-in agent modules:\n{error_msgs}","messagePattern":"Failed to preload the following built-in agent modules:\n(.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/agent.py","lineNumber":697,"sourceCode":"\n    if _BUILTIN_AGENTS_LOADED:\n        return\n\n    with _BUILTIN_AGENTS_LOCK:\n        if _BUILTIN_AGENTS_LOADED:\n            return  # Double-checked locking\n\n        failed = []\n\n        for module_name in _BUILTIN_AGENT_MODULES:\n            try:\n                importlib.import_module(module_name)\n            except Exception as ex:\n                failed.append((module_name, ex))\n\n        if failed:\n            error_msgs = \"\\n\".join(f\"- {mod}: {err}\" for mod, err in failed)\n            raise RuntimeError(f\"Failed to preload the following built-in agent modules:\\n{error_msgs}\")\n\n        _BUILTIN_AGENTS_LOADED = True\n\n\nclass AgentRegistry:\n    \"\"\"Responsible for creating agents from YAML, dicts, or files.\"\"\"\n\n    @staticmethod\n    def register_type(agent_type: str, agent_cls: type[Agent]) -> None:\n        \"\"\"Register a new agent type at runtime.\n\n        Args:\n            agent_type: The string identifier representing the agent type (e.g., 'chat_completion_agent').\n            agent_cls: The class implementing the agent, inheriting from `Agent`.\n\n        Example:\n            AgentRegistry.register_type(\"my_custom_agent\", MyCustomAgent)\n        \"\"\"","sourceCodeStart":679,"sourceCodeEnd":715,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/agent.py#L679-L715","documentation":"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).","triggerScenarios":"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.","commonSituations":"Installing semantic-kernel without the needed extras; upgrading one package to an incompatible version; missing system libs for a connector.","solutions":["Read the inner per-module error in the message — it names the failing module and the underlying exception (usually ModuleNotFoundError).","Install the missing optional dependency the failing module needs (e.g. pip install 'semantic_kernel[openai]' or the specific third-party package).","Reinstall/repair the semantic_kernel package if the install is partial or corrupted.","Pin compatible versions of connector packages matching your semantic-kernel version."],"exampleFix":"# Message lists the failing module(s), e.g.:\n# - semantic_kernel.agents.azure_ai.azure_ai_agent: ModuleNotFoundError: No module named 'azure_ai'\n# Fix: install the missing extra\npip install 'semantic_kernel[azure]'  # or the specific package the error names","handlingStrategy":"try-catch","validationCode":"# Pre-check that the agent family's optional dependency is importable.\nimport importlib.util\nmods = ['openai', 'azure.ai.projects']  # adjust to the family you use\nmissing = [m for m in mods if importlib.util.find_spec(m) is None]\nassert not missing, f'Install missing extras: {missing}'","typeGuard":null,"tryCatchPattern":"try:\n    agent = await AgentRegistry.create_from_yaml(yaml_str, kernel=kernel)\nexcept RuntimeError as e:\n    if 'Failed to preload' in str(e):\n        # parse per-module errors, install missing deps, retry\n        print(e)\n    raise","preventionTips":["Install semantic-kernel with the extras for the agent families you use.","Read the inner per-module error to find the missing dependency.","Keep connector package versions compatible with your SDK.","Repair partial/corrupted installs before using the registry."],"tags":["agents","import","optional-dependencies","registry","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}