{"record":{"id":"9ef4d6986af95605","repo":"huggingface/smolagents","slug":"agent-name-name-must-be-a-valid-python-identif","errorCode":null,"errorMessage":"Agent name '{name}' must be a valid Python identifier and not a reserved keyword.","messagePattern":"Agent name '(.+?)' must be a valid Python identifier and not a reserved keyword\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"src/smolagents/agents.py","lineNumber":366,"sourceCode":"            self.logger = logger\n\n        self.monitor = Monitor(self.model, self.logger)\n        self._setup_step_callbacks(step_callbacks)\n        self.stream_outputs = False\n\n    @property\n    def system_prompt(self) -> str:\n        return self.initialize_system_prompt()\n\n    @system_prompt.setter\n    def system_prompt(self, value: str):\n        raise AttributeError(\n            \"\"\"The 'system_prompt' property is read-only. Use 'self.prompt_templates[\"system_prompt\"]' instead.\"\"\"\n        )\n\n    def _validate_name(self, name: str | None) -> str | None:\n        if name is not None and not is_valid_name(name):\n            raise ValueError(f\"Agent name '{name}' must be a valid Python identifier and not a reserved keyword.\")\n        return name\n\n    def _setup_managed_agents(self, managed_agents: list | None = None) -> None:\n        \"\"\"Setup managed agents with proper logging.\"\"\"\n        self.managed_agents = {}\n        if managed_agents:\n            assert all(agent.name and agent.description for agent in managed_agents), (\n                \"All managed agents need both a name and a description!\"\n            )\n            self.managed_agents = {agent.name: agent for agent in managed_agents}\n            # Ensure managed agents can be called as tools by the model: set their inputs and output_type\n            for agent in self.managed_agents.values():\n                agent.inputs = {\n                    \"task\": {\"type\": \"string\", \"description\": \"Long detailed description of the task.\"},\n                    \"additional_args\": {\n                        \"type\": \"object\",\n                        \"description\": \"Dictionary of extra inputs to pass to the managed agent, e.g. images, dataframes, or any other contextual data it may need.\",\n                        \"nullable\": True,","sourceCodeStart":348,"sourceCodeEnd":384,"githubUrl":"https://github.com/huggingface/smolagents/blob/30bb1161095dbae2271e6bc3cc4c219cc3897a57/src/smolagents/agents.py#L348-L384","documentation":"Agent names must be valid Python identifiers and not reserved keywords, because agent names are used to expose managed agents as callable tools inside generated code. _validate_name rejects anything else with a ValueError during __init__.","triggerScenarios":"Passing name='my agent', name='1agent', name='class', name='web-search', or a name with dashes/spaces/leading digits to MultiStepAgent/CodeAgent or a ManagedAgent; also non-ASCII or punctuation-containing names.","commonSituations":"Naming managed agents after domains like 'web-search' or 'text summarizer'; auto-generating names from task descriptions or file paths without sanitizing them.","solutions":["Use a valid Python identifier: letters/digits/underscores, not starting with a digit, e.g. 'web_search_agent'","Avoid Python keywords ('class', 'import', 'lambda', 'None', ...) as names","If names come from external input, sanitize: re.sub(r'\\W|^(?=\\d)', '_', name) and check against keyword.kwlist"],"exampleFix":"# before\nagent = WebSearchAgent(name=\"web-search\")\n\n# after\nagent = WebSearchAgent(name=\"web_search\")","handlingStrategy":"validation","validationCode":"import keyword, re\n\ndef safe_agent_name(name: str) -> str:\n    name = re.sub(r'\\W|^(?=\\d)', '_', name)\n    if keyword.iskeyword(name):\n        name += '_'\n    return name\n\nagent = MyAgent(name=safe_agent_name(raw_name))","typeGuard":"def is_valid_agent_name(name: str) -> bool:\n    return name.isidentifier() and not keyword.iskeyword(name)","tryCatchPattern":null,"preventionTips":["Sanitize auto-generated names (from filenames, domains, LLM output) before use","Use snake_case identifiers for tools and agents"],"tags":["smolagents","name-validation","python-identifier","valueerror"],"backgroundTag":"invalid-identifier-name","analyzedSha":"30bb1161095dbae2271e6bc3cc4c219cc3897a57","analyzedAt":"2026-08-28T18:52:54.169Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}