microsoft/autogen · error · ValueError

Invalid agent type: {type}. Allowed values MUST match the re

Error message

Invalid agent type: {type}. Allowed values MUST match the regex: `^[\w\-\.]+\Z`

What it means

autogen_core.AgentId.__init__ raises ValueError when the type string fails the regex ^[\w\-\.]+$ (word characters, hyphens, dots only). Agent types become topic/routing identifiers in the runtime, so characters like '/', ':', spaces, or '#' are rejected to keep addresses unambiguous (type/key are joined with '/').

Source

Thrown at python/packages/autogen-core/src/autogen_core/_agent_id.py:24


def is_valid_agent_type(value: str) -> bool:
    return bool(re.match(r"^[\w\-\.]+\Z", value))


class AgentId:
    """
    Agent ID uniquely identifies an agent instance within an agent runtime - including distributed runtime. It is the 'address' of the agent instance for receiving messages.

    See here for more information: :ref:`agentid_and_lifecycle`
    """

    def __init__(self, type: str | AgentType, key: str) -> None:
        if isinstance(type, AgentType):
            type = type.type

        if not is_valid_agent_type(type):
            raise ValueError(rf"Invalid agent type: {type}. Allowed values MUST match the regex: `^[\w\-\.]+\Z`")

        self._type = type
        self._key = key

    def __hash__(self) -> int:
        return hash((self._type, self._key))

    def __str__(self) -> str:
        return f"{self._type}/{self._key}"

    def __repr__(self) -> str:
        return f'AgentId(type="{self._type}", key="{self._key}")'

    def __eq__(self, value: object) -> bool:
        if not isinstance(value, AgentId):
            return False
        return self._type == value.type and self._key == value.key

View on GitHub (pinned to 027ecf0a37)

Solutions

Sanitize the type to allowed characters: re.sub(r'[^\w\-\.]', '_', type_str).
Use simple identifiers, module-qualified names ('my_pkg.MyAgent'), or dotted namespaces instead of paths with slashes.
Validate early with autogen_core._agent_id.is_valid_agent_type (or the same regex) before constructing AgentId.

Example fix

# before
agent_id = AgentId(type="workers/http-agent", key="1")  # ValueError: '/' not allowed

# after
import re
agent_type = re.sub(r"[^\w\-\.]", "_", "workers/http-agent")  # 'workers_http-agent'
agent_id = AgentId(type=agent_type, key="1")

Defensive patterns

Strategy: validation

Validate before calling

import re

def safe_agent_type(raw: str) -> str:
    return re.sub(r"[^\w\-\.]", "_", raw)

agent_id = AgentId(type=safe_agent_type(raw_name), key="1")

Type guard

import re

def is_valid_agent_type(type_str: str) -> bool:
    return re.fullmatch(r"[\w\-\.]+", type_str) is not None

Try / catch

from autogen_core import AgentId
try:
    agent_id = AgentId(type=raw_type, key=key)
except ValueError:
    agent_id = AgentId(type=re.sub(r"[^\w\-\.]", "_", raw_type), key=key)

Prevention

Restrict agent type names to letters, digits, underscore, hyphen, and dot.
Sanitize user-supplied or path-derived names before building AgentId.
Remember '/' is reserved as the type/key separator in AgentId.__str__.

When it happens

Trigger: Constructing AgentId(type="my agent", key="1") or AgentId("ns:worker", ...); passing a class-qualified name, a path, or any string containing whitespace, slashes, or punctuation as the agent type; AgentType(...) with the same invalid string.

Common situations: Deriving agent type names from file paths, URLs, or free-form user input; using 'module.Class' is fine (dots allowed) but 'module::Class' or 'a/b' fails; migrating code that used arbitrary strings in older versions.

Related errors

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