huggingface/smolagents · error · ValueError

Unknown model class '{model_info['class']}'. Supported model

Error message

Unknown model class '{model_info['class']}'. Supported models: {', '.join(sorted(MODEL_REGISTRY.keys()))}

What it means

Raised by MultiStepAgent.from_dict when the serialized agent's 'model' entry names a class that is not in MODEL_REGISTRY. from_dict reconstructs an agent from a dict produced by to_dict, and it looks up the model class by name before calling model_class.from_dict. If the class string doesn't exactly match a registered model (e.g. due to a typo, rename, or a custom model that was never registered via MODEL_REGISTRY), deserialization fails.

Source

Thrown at src/smolagents/agents.py:1025

        }
        return agent_dict

    @classmethod
    def from_dict(cls, agent_dict: dict[str, Any], **kwargs) -> "MultiStepAgent":
        """Create agent from a dictionary representation.

        Args:
            agent_dict (`dict[str, Any]`): Dictionary representation of the agent.
            **kwargs: Additional keyword arguments that will override agent_dict values.

        Returns:
            `MultiStepAgent`: Instance of the agent class.
        """
        # 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)

View on GitHub (pinned to 30bb116109)

Solutions

Print sorted(MODEL_REGISTRY.keys()) and correct the 'class' string in the dict to exactly match a registered model class name.
If the dict came from a custom model, register that class with MODEL_REGISTRY (MODEL_REGISTRY['MyModel'] = MyModel) before calling from_dict.
Re-serialize the agent with agent.to_dict() using the same smolagents version you load it with to avoid name drift.

Example fix

# before
agent = MultiStepAgent.from_dict({'model': {'class': 'openai_model', 'data': {...}}, ...})

# after
from smolagents.models import MODEL_REGISTRY
print(sorted(MODEL_REGISTRY.keys()))  # e.g. ['InferenceClientModel', 'OpenAIServerModel', ...]
agent = MultiStepAgent.from_dict({'model': {'class': 'OpenAIServerModel', 'data': {...}}, ...})

Defensive patterns

Strategy: validation

Validate before calling

from smolagents.models import MODEL_REGISTRY

def agent_dict_is_loadable(agent_dict: dict) -> bool:
    return agent_dict['model']['class'] in MODEL_REGISTRY

Try / catch

try:
    agent = MultiStepAgent.from_dict(agent_dict)
except ValueError as e:
    if 'Unknown model class' in str(e):
        raise SystemExit(f"Fix model class: {e}")
    raise

Prevention

Always produce agent dicts via to_dict() in the same smolagents version used for loading.
Register custom model classes in MODEL_REGISTRY before deserializing.
Assert the class key exists in MODEL_REGISTRY before calling from_dict.

When it happens

Trigger: Calling MultiStepAgent.from_dict(agent_dict) (directly or via from_folder/from_hub) where agent_dict['model']['class'] is not a key in MODEL_REGISTRY, e.g. {'model': {'class': 'OpenAIServerModelX', 'data': {...}}} or a custom model class that wasn't added to MODEL_REGISTRY before serialization.

Common situations: Hand-edited or programmatically generated agent dicts; smolagents version drift where model class names changed; loading a pickled/dict agent built around a custom Model subclass without registering it first.

Related errors

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