huggingface/smolagents · error · ValueError

User-agent is required. Provide a meaningful identifier for

Error message

User-agent is required. Provide a meaningful identifier for your project.

What it means

Raised by WikipediaSearchTool.__init__ when user_agent is empty/None. The wikipedia-api library requires a meaningful User-Agent per Wikimedia's API policy, so smolagents enforces it at construction with a ValueError.

Source

Thrown at src/smolagents/default_tools.py:602

    }
    output_type = "string"

    def __init__(
        self,
        user_agent: str = "Smolagents (myemail@example.com)",
        language: str = "en",
        content_type: str = "text",
        extract_format: str = "WIKI",
    ):
        super().__init__()
        try:
            import wikipediaapi
        except ImportError as e:
            raise ImportError(
                "You must install `wikipedia-api` to run this tool: for instance run `pip install wikipedia-api`"
            ) from e
        if not user_agent:
            raise ValueError("User-agent is required. Provide a meaningful identifier for your project.")

        self.user_agent = user_agent
        self.language = language
        self.content_type = content_type

        # Map string format to wikipediaapi.ExtractFormat
        extract_format_map = {
            "WIKI": wikipediaapi.ExtractFormat.WIKI,
            "HTML": wikipediaapi.ExtractFormat.HTML,
        }

        if extract_format not in extract_format_map:
            raise ValueError("Invalid extract_format. Choose between 'WIKI' or 'HTML'.")

        self.extract_format = extract_format_map[extract_format]

        self.wiki = wikipediaapi.Wikipedia(
            user_agent=self.user_agent, language=self.language, extract_format=self.extract_format

View on GitHub (pinned to 30bb116109)

Solutions

1. Pass a descriptive user_agent identifying your project, e.g. WikipediaSearchTool(user_agent='my-agent (contact@example.com)').
2. Set the value from config/env so it is consistent across deployments.

Example fix

# before
tool = WikipediaSearchTool()  # ValueError
# after
tool = WikipediaSearchTool(user_agent='my-research-bot/1.0 (https://example.com; me@example.com)')

if not user_agent: raise ValueError('user_agent required')
tool = WikipediaSearchTool(user_agent=user_agent)

When it happens

Trigger: WikipediaSearchTool() with no user_agent argument (if no acceptable default applies) or explicitly passing user_agent='' / None.

Common situations: Copy-pasting quickstart code that omits user_agent, or assuming a generic default is used. Wikimedia may block default/empty agents, hence the strict check.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

• Invalid extract_format. Choose between 'WIKI' or 'HTML'.
• Only 'markdown' is supported for a string argument to `code_
• Unsupported model type: {model_type}
• Tool {tool_name} is not recognized either as a default tool
• Unsupported action type: {action_type}

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