huggingface/smolagents · error · ValueError

Unknown agent class '{managed_agent_dict['class']}'. Support

Error message

Unknown agent class '{managed_agent_dict['class']}'. Supported agents: {', '.join(sorted(AGENT_REGISTRY.keys()))}

What it means

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.

Source

Thrown at src/smolagents/agents.py:1039

        # Load model
        model_info = agent_dict["model"]
        model_class = MODEL_REGISTRY.get(model_info["class"])
        if model_class is None:
            raise ValueError(
                f"Unknown model class '{model_info['class']}'. "
                f"Supported models: {', '.join(sorted(MODEL_REGISTRY.keys()))}"
            )
        model = model_class.from_dict(model_info["data"])
        # Load tools
        tools = []
        for tool_info in agent_dict["tools"]:
            tools.append(Tool.from_code(tool_info["code"]))
        # Load managed agents
        managed_agents = []
        for managed_agent_dict in agent_dict["managed_agents"]:
            agent_class = AGENT_REGISTRY.get(managed_agent_dict["class"])
            if agent_class is None:
                raise ValueError(
                    f"Unknown agent class '{managed_agent_dict['class']}'. "
                    f"Supported agents: {', '.join(sorted(AGENT_REGISTRY.keys()))}"
                )
            managed_agent = agent_class.from_dict(managed_agent_dict, **kwargs)
            managed_agents.append(managed_agent)
        # Extract base agent parameters
        agent_args = {
            "model": model,
            "tools": tools,
            "managed_agents": managed_agents,
            "prompt_templates": agent_dict.get("prompt_templates"),
            "max_steps": agent_dict.get("max_steps"),
            "verbosity_level": agent_dict.get("verbosity_level"),
            "planning_interval": agent_dict.get("planning_interval"),
            "name": agent_dict.get("name"),
            "description": agent_dict.get("description"),
        }
        # Filter out None values to use defaults from __init__

View on GitHub (pinned to 30bb116109)

Solutions

1. Check sorted(AGENT_REGISTRY.keys()) and fix the managed agent 'class' string to match exactly.
2. Register custom agent classes in AGENT_REGISTRY before calling from_dict.
3. Reproduce the dict via agent.to_dict() in the same environment/version used for loading.

Example fix

# before
agent_dict['managed_agents'] = [{'class': 'codeagent', ...}]
agent = MultiStepAgent.from_dict(agent_dict)

# after
from smolagents.agents import AGENT_REGISTRY
print(sorted(AGENT_REGISTRY.keys()))  # ['CodeAgent', 'ToolCallingAgent', ...]
agent_dict['managed_agents'] = [{'class': 'CodeAgent', ...}]
agent = MultiStepAgent.from_dict(agent_dict)

from smolagents.agents import AGENT_REGISTRY

def managed_agents_loadable(agent_dict: dict) -> bool:
    return all(ma['class'] in AGENT_REGISTRY for ma in agent_dict.get('managed_agents', []))

try:
    agent = MultiStepAgent.from_dict(agent_dict)
except ValueError as e:
    if 'Unknown agent class' in str(e):
        # fix registry or class names, then retry
        ...
    raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Unknown agent class '{managed_agent_class_name}'. Supported
• Unknown model class '{model_info['class']}'. Supported model
• Managed agents are not yet supported with remote code execut
• Tool dictionary must contain 'code' key with the tool source
• Deserializing pickle data. This is a security risk if the da

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/bc1fe2b4e10b7ab1. Report an issue: GitHub.