{"record":{"id":"bc1fe2b4e10b7ab1","repo":"huggingface/smolagents","slug":"unknown-agent-class-managed-agent-dict-class","errorCode":null,"errorMessage":"Unknown agent class '{managed_agent_dict['class']}'. 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":1039,"sourceCode":"        # Load model\n        model_info = agent_dict[\"model\"]\n        model_class = MODEL_REGISTRY.get(model_info[\"class\"])\n        if model_class is None:\n            raise ValueError(\n                f\"Unknown model class '{model_info['class']}'. \"\n                f\"Supported models: {', '.join(sorted(MODEL_REGISTRY.keys()))}\"\n            )\n        model = model_class.from_dict(model_info[\"data\"])\n        # Load tools\n        tools = []\n        for tool_info in agent_dict[\"tools\"]:\n            tools.append(Tool.from_code(tool_info[\"code\"]))\n        # Load managed agents\n        managed_agents = []\n        for managed_agent_dict in agent_dict[\"managed_agents\"]:\n            agent_class = AGENT_REGISTRY.get(managed_agent_dict[\"class\"])\n            if agent_class is None:\n                raise ValueError(\n                    f\"Unknown agent class '{managed_agent_dict['class']}'. \"\n                    f\"Supported agents: {', '.join(sorted(AGENT_REGISTRY.keys()))}\"\n                )\n            managed_agent = agent_class.from_dict(managed_agent_dict, **kwargs)\n            managed_agents.append(managed_agent)\n        # Extract base agent parameters\n        agent_args = {\n            \"model\": model,\n            \"tools\": tools,\n            \"managed_agents\": managed_agents,\n            \"prompt_templates\": agent_dict.get(\"prompt_templates\"),\n            \"max_steps\": agent_dict.get(\"max_steps\"),\n            \"verbosity_level\": agent_dict.get(\"verbosity_level\"),\n            \"planning_interval\": agent_dict.get(\"planning_interval\"),\n            \"name\": agent_dict.get(\"name\"),\n            \"description\": agent_dict.get(\"description\"),\n        }\n        # Filter out None values to use defaults from __init__","sourceCodeStart":1021,"sourceCodeEnd":1057,"githubUrl":"https://github.com/huggingface/smolagents/blob/30bb1161095dbae2271e6bc3cc4c219cc3897a57/src/smolagents/agents.py#L1021-L1057","documentation":"Raised by MultiStepAgent.from_dict when deserializing a multi-agent setup: each entry in agent_dict['managed_agents'] names an agent class that must exist in AGENT_REGISTRY. If the class string doesn't match a registered agent class, deserialization aborts before the recursive agent_class.from_dict call.","triggerScenarios":"MultiStepAgent.from_dict(agent_dict) where agent_dict['managed_agents'] contains {'class': 'ToolCallingAgentX', ...} — any string not present in AGENT_REGISTRY (typo, renamed class, unregistered custom agent subclass).","commonSituations":"Saving a manager agent with managed agents and loading it in another environment/version; custom MultiStepAgent subclasses that were never added to AGENT_REGISTRY; hand-crafted dicts from documentation examples.","solutions":["Check sorted(AGENT_REGISTRY.keys()) and fix the managed agent 'class' string to match exactly.","Register custom agent classes in AGENT_REGISTRY before calling from_dict.","Reproduce the dict via agent.to_dict() in the same environment/version used for loading."],"exampleFix":"# before\nagent_dict['managed_agents'] = [{'class': 'codeagent', ...}]\nagent = MultiStepAgent.from_dict(agent_dict)\n\n# after\nfrom smolagents.agents import AGENT_REGISTRY\nprint(sorted(AGENT_REGISTRY.keys()))  # ['CodeAgent', 'ToolCallingAgent', ...]\nagent_dict['managed_agents'] = [{'class': 'CodeAgent', ...}]\nagent = MultiStepAgent.from_dict(agent_dict)","handlingStrategy":"validation","validationCode":"from smolagents.agents import AGENT_REGISTRY\n\ndef managed_agents_loadable(agent_dict: dict) -> bool:\n    return all(ma['class'] in AGENT_REGISTRY for ma in agent_dict.get('managed_agents', []))","typeGuard":null,"tryCatchPattern":"try:\n    agent = MultiStepAgent.from_dict(agent_dict)\nexcept ValueError as e:\n    if 'Unknown agent class' in str(e):\n        # fix registry or class names, then retry\n        ...\n    raise","preventionTips":["Register custom agent subclasses in AGENT_REGISTRY in your package's import path.","Pin the smolagents version between save and load.","Validate managed agent class names against AGENT_REGISTRY before from_dict."],"tags":["smolagents","managed-agents","deserialization","registry"],"backgroundTag":"unknown-class-in-registry","analyzedSha":"30bb1161095dbae2271e6bc3cc4c219cc3897a57","analyzedAt":"2026-08-28T18:52:54.169Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}