{"record":{"id":"39f53f8701c6ee2f","repo":"huggingface/smolagents","slug":"unknown-agent-class-managed-agent-class-name","errorCode":null,"errorMessage":"Unknown agent class '{managed_agent_class_name}'. Supported agents: {', '.join(sorted(AGENT_REGISTRY.keys()))}","messagePattern":"Unknown agent class '(.+?)'\\. Supported agents: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/smolagents/agents.py","lineNumber":1140,"sourceCode":"        Args:\n            folder (`str` or `Path`): The folder where the agent is saved.\n            **kwargs: Additional keyword arguments that will be passed to the agent's init.\n        \"\"\"\n        # Load agent.json\n        folder = Path(folder)\n        agent_dict = json.loads((folder / \"agent.json\").read_text())\n        # Handle HfApiModel -> InferenceClientModel rename for old agents\n        if agent_dict.get(\"model\", {}).get(\"class\") == \"HfApiModel\":\n            agent_dict[\"model\"][\"class\"] = \"InferenceClientModel\"\n            logger.warning(\n                \"The agent you're loading uses the deprecated 'HfApiModel' class: it was automatically updated to 'InferenceClientModel'.\"\n            )\n        # Load managed agents from their respective folders, recursively\n        managed_agents = []\n        for managed_agent_name, managed_agent_class_name in agent_dict[\"managed_agents\"].items():\n            agent_cls = AGENT_REGISTRY.get(managed_agent_class_name)\n            if agent_cls is None:\n                raise ValueError(\n                    f\"Unknown agent class '{managed_agent_class_name}'. \"\n                    f\"Supported agents: {', '.join(sorted(AGENT_REGISTRY.keys()))}\"\n                )\n            managed_agents.append(agent_cls.from_folder(folder / \"managed_agents\" / managed_agent_name))\n        agent_dict[\"managed_agents\"] = {}\n\n        # Load tools\n        tools = []\n        for tool_name in agent_dict[\"tools\"]:\n            tool_code = (folder / \"tools\" / f\"{tool_name}.py\").read_text()\n            tools.append({\"name\": tool_name, \"code\": tool_code})\n        agent_dict[\"tools\"] = tools\n\n        # Add managed agents to kwargs to override the empty list in from_dict\n        if managed_agents:\n            kwargs[\"managed_agents\"] = managed_agents\n\n        return cls.from_dict(agent_dict, **kwargs)","sourceCodeStart":1122,"sourceCodeEnd":1158,"githubUrl":"https://github.com/huggingface/smolagents/blob/30bb1161095dbae2271e6bc3cc4c219cc3897a57/src/smolagents/agents.py#L1122-L1158","documentation":"Raised by from_folder when loading a saved multi-agent hierarchy: the saved agent.json lists managed agents with their class names, and each name must resolve through AGENT_REGISTRY. An unknown class string (typo, renamed class, unregistered custom subclass) stops recursive loading of the managed_agents subfolders.","triggerScenarios":"MultiStepAgent.from_folder(path) (directly or via from_hub) where path/agent.json contains a 'managed_agents' mapping whose value (class name) is not in AGENT_REGISTRY.","commonSituations":"Loading an agent saved with a different smolagents version where agent class names changed; hand-edited agent.json; custom agent classes not registered on the loading machine.","solutions":["Inspect agent.json under the folder's managed_agents entries and compare against sorted(AGENT_REGISTRY.keys()); fix the class name string.","Register your custom agent classes in AGENT_REGISTRY before from_folder.","Re-save the agent with to_folder in the same environment/version used for loading."],"exampleFix":"# before\n# agent.json: {\"managed_agents\": {\"coder\": \"MyCodeAgent\"}}\nagent = MultiStepAgent.from_folder('./saved_agent')\n\n# after\nfrom smolagents.agents import AGENT_REGISTRY, CodeAgent\nclass MyCodeAgent(CodeAgent): ...\nAGENT_REGISTRY['MyCodeAgent'] = MyCodeAgent\nagent = MultiStepAgent.from_folder('./saved_agent')","handlingStrategy":"validation","validationCode":"import json\nfrom smolagents.agents import AGENT_REGISTRY\n\nwith open(folder / 'agent.json') as f:\n    meta = json.load(f)\nassert all(cls in AGENT_REGISTRY for cls in meta.get('managed_agents', {}).values())","typeGuard":null,"tryCatchPattern":"try:\n    agent = MultiStepAgent.from_folder(folder)\nexcept ValueError as e:\n    if 'Unknown agent class' in str(e):\n        # register missing class or fix agent.json, then retry\n        ...\n    raise","preventionTips":["Save and load agents with the same smolagents version.","Register custom agent classes in AGENT_REGISTRY at app startup.","Keep saved agent folders under version control to detect manual edits."],"tags":["smolagents","from-folder","managed-agents","registry"],"backgroundTag":"unknown-class-in-registry","analyzedSha":"30bb1161095dbae2271e6bc3cc4c219cc3897a57","analyzedAt":"2026-08-28T18:52:54.169Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}