huggingface/smolagents · error · ValueError

Unknown agent class '{managed_agent_class_name}'. Supported

Error message

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

What it means

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.

Source

Thrown at src/smolagents/agents.py:1140

        Args:
            folder (`str` or `Path`): The folder where the agent is saved.
            **kwargs: Additional keyword arguments that will be passed to the agent's init.
        """
        # Load agent.json
        folder = Path(folder)
        agent_dict = json.loads((folder / "agent.json").read_text())
        # Handle HfApiModel -> InferenceClientModel rename for old agents
        if agent_dict.get("model", {}).get("class") == "HfApiModel":
            agent_dict["model"]["class"] = "InferenceClientModel"
            logger.warning(
                "The agent you're loading uses the deprecated 'HfApiModel' class: it was automatically updated to 'InferenceClientModel'."
            )
        # Load managed agents from their respective folders, recursively
        managed_agents = []
        for managed_agent_name, managed_agent_class_name in agent_dict["managed_agents"].items():
            agent_cls = AGENT_REGISTRY.get(managed_agent_class_name)
            if agent_cls is None:
                raise ValueError(
                    f"Unknown agent class '{managed_agent_class_name}'. "
                    f"Supported agents: {', '.join(sorted(AGENT_REGISTRY.keys()))}"
                )
            managed_agents.append(agent_cls.from_folder(folder / "managed_agents" / managed_agent_name))
        agent_dict["managed_agents"] = {}

        # Load tools
        tools = []
        for tool_name in agent_dict["tools"]:
            tool_code = (folder / "tools" / f"{tool_name}.py").read_text()
            tools.append({"name": tool_name, "code": tool_code})
        agent_dict["tools"] = tools

        # Add managed agents to kwargs to override the empty list in from_dict
        if managed_agents:
            kwargs["managed_agents"] = managed_agents

        return cls.from_dict(agent_dict, **kwargs)

View on GitHub (pinned to 30bb116109)

Solutions

1. Inspect agent.json under the folder's managed_agents entries and compare against sorted(AGENT_REGISTRY.keys()); fix the class name string.
2. Register your custom agent classes in AGENT_REGISTRY before from_folder.
3. Re-save the agent with to_folder in the same environment/version used for loading.

Example fix

# before
# agent.json: {"managed_agents": {"coder": "MyCodeAgent"}}
agent = MultiStepAgent.from_folder('./saved_agent')

# after
from smolagents.agents import AGENT_REGISTRY, CodeAgent
class MyCodeAgent(CodeAgent): ...
AGENT_REGISTRY['MyCodeAgent'] = MyCodeAgent
agent = MultiStepAgent.from_folder('./saved_agent')

import json
from smolagents.agents import AGENT_REGISTRY

with open(folder / 'agent.json') as f:
    meta = json.load(f)
assert all(cls in AGENT_REGISTRY for cls in meta.get('managed_agents', {}).values())

try:
    agent = MultiStepAgent.from_folder(folder)
except ValueError as e:
    if 'Unknown agent class' in str(e):
        # register missing class or fix agent.json, then retry
        ...
    raise

When it happens

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

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

Related errors

• Unknown agent class '{managed_agent_dict['class']}'. Support
• Managed agents are not yet supported with remote code execut
• Error during jinja template rendering: {type(e).__name__}: {
• Cannot specify both 'messages' and 'steps' parameters. Use '
• The 'system_prompt' property is read-only. Use 'self.prompt_

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