microsoft/autogen · error · ValueError

The agent name must be a valid Python identifier.

Error message

The agent name must be a valid Python identifier.

What it means

BaseChatAgent validates in its constructor that the agent name passes str.isidentifier(): it must be a valid Python identifier (letters, digits, underscores, not starting with a digit). Names are used as unique team identifiers and must stay identifier-safe.

Source

Thrown at python/packages/autogen-agentchat/src/autogen_agentchat/agents/_base_chat_agent.py:49

    .. note::

        The caller should only pass the new messages to the agent on each call
        to the :meth:`on_messages` or :meth:`on_messages_stream` method.
        Do not pass the entire conversation history to the agent on each call.
        This design principle must be followed when creating a new agent.
    """

    component_type = "agent"

    def __init__(self, name: str, description: str) -> None:
        """Initialize the agent with a name and description."""
        with trace_create_agent_span(
            agent_name=name,
            agent_description=description,
        ):
            self._name = name
            if self._name.isidentifier() is False:
                raise ValueError("The agent name must be a valid Python identifier.")
            self._description = description

    @property
    def name(self) -> str:
        """The name of the agent. This is used by team to uniquely identify
        the agent. It should be unique within the team."""
        return self._name

    @property
    def description(self) -> str:
        """The description of the agent. This is used by team to
        make decisions about which agents to use. The description should
        describe the agent's capabilities and how to interact with it."""
        return self._description

    @property
    @abstractmethod
    def produced_message_types(self) -> Sequence[type[BaseChatMessage]]:

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Rename the agent to a valid identifier, e.g. "my_agent" instead of "my-agent".
2. Sanitize externally sourced names before construction: re.sub(r'\W|^(?=\d)', '_', name).
3. Keep a display label separate from the agent name if pretty names are needed.

Example fix

// before
agent = AssistantAgent(name="helpful-agent", model_client=client)

// after
agent = AssistantAgent(name="helpful_agent", model_client=client)

import re

def safe_agent_name(raw: str) -> str:
    name = re.sub(r'\W+', '_', raw).strip('_')
    if not name or name[0].isdigit():
        name = 'a' + name
    assert name.isidentifier()
    return name

agent = AssistantAgent(name=safe_agent_name(display_name), model_client=client)

def is_valid_agent_name(name: str) -> bool:
    return isinstance(name, str) and name.isidentifier()

try:
    agent = AssistantAgent(name=name, model_client=client)
except ValueError as e:
    if "valid Python identifier" in str(e):
        name = re.sub(r'\W+', '_', name).strip('_')
        agent = AssistantAgent(name=name, model_client=client)
    else:
        raise

When it happens

Trigger: Constructing any agent (AssistantAgent, UserProxyAgent, CodeExecutorAgent, custom BaseChatAgent subclasses) with a name containing spaces, hyphens, dots, or starting with a digit, e.g. "my-agent", "agent 1", "1writer".

Common situations: Loading agent names from config files, URLs, or user input where hyphens/spaces are natural; copying display names into the name parameter.

Related errors

• Module name must be a valid Python identifier
• Module name must be a valid Python identifier
• Unsupported config type {config.GetType()}
• Messages should not be provided in options
• model_client.model_info must be provided when max_retries_on

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/9a18f16403664852. Report an issue: GitHub.