microsoft/semantic-kernel · 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

Raised by CoreAgentId.__init__ when the supplied agent type string fails the regex ^[\w\-\.]+\Z (letters, digits, underscore, hyphen, period only). Agent types are used in topic/subscription routing identifiers, so disallowed characters would break the runtime's name-based dispatch.

Source

Thrown at python/semantic_kernel/agents/runtime/core/agent_id.py:59

        ...

    def __str__(self) -> str:
        """String representation of the AgentId, e.g. 'type/key'."""
        ...


@experimental
class CoreAgentId(AgentId):
    """Core implementation of the AgentId protocol."""

    def __init__(self, type: str | AgentType, key: str) -> None:
        """Initialize the AgentId with the given type and key."""
        # If `type` is itself an AgentType, extract the string property.
        if isinstance(type, AgentType):
            type = type.type

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

        self._type = type
        self._key = key

    @classmethod
    def from_str(cls, agent_id: str) -> Self:
        """Convert a string of the format ``type/key`` into a CoreAgentId."""
        items = agent_id.split("/", maxsplit=1)
        if len(items) != 2:
            raise ValueError(f"Invalid agent id: {agent_id}")
        t, k = items[0], items[1]
        return cls(t, k)

    @property
    def type(self) -> str:

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Sanitize the type to contain only [A-Za-z0-9_.-] characters.
2. Use a short stable identifier (e.g. 'my-agent' or 'MyAgent') instead of a free-form label.
3. If deriving from a class, strip module path: type = cls.__name__.
4. Validate with is_valid_agent_type(value) before constructing CoreAgentId.

Example fix

// before
agent_id = CoreAgentId(type="my namespace/agent", key="k")
// after
from semantic_kernel.agents.runtime.core.validation_utils import is_valid_agent_type
type_str = "my-namespace-agent"
assert is_valid_agent_type(type_str)
agent_id = CoreAgentId(type=type_str, key="k")

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

import re

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

try:
    agent_id = CoreAgentId(type=type_str, key=key)
except ValueError as e:
    if "Invalid agent type" in str(e):
        import re
        type_str = re.sub(r"[^\w\-.]", "-", type_str or "agent")
        agent_id = CoreAgentId(type=type_str, key=key)
    else:
        raise

When it happens

Trigger: Constructing a CoreAgentId (or registering an agent whose type derives from a class name) where the type contains spaces, slashes, colons, or any punctuation outside [A-Za-z0-9_\-.]. Common when the type is auto-derived from a class with a namespace path or from user free text.

Common situations: Passing an agent type like 'my agent', 'foo/bar', 'type:1', or an empty string; using a fully-qualified class name (with dots and module separators that include other chars) as the type; copy-pasting a UUID with braces.

Related errors

• Invalid agent id: {agent_id}
• Invalid response from DirectLine Bot.\n{response_data}
• Agent description must be a string
• Invalid AgentId key: '{key}'. Must only contain ASCII charac
• Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/8b65bbb063c00ba2. Report an issue: GitHub.