microsoft/semantic-kernel · error · ValueError

Invalid agent id: {agent_id}

Error message

Invalid agent id: {agent_id}

What it means

Raised by CoreAgentId.from_str when the input string does not contain exactly one '/' separator splitting it into 'type' and 'key'. The canonical textual form of an agent id is 'type/key', so anything else cannot be unambiguously parsed.

Source

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

        # 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:
        r"""The agent's 'type' (or category). Must match `^[\\w\\-\\.]+$`."""
        return self._type

    @property
    def key(self) -> str:
        """The agent's instance key, e.g. 'default' or a unique identifier."""
        return self._key

    def __eq__(self, value: object) -> bool:
        """Check if two AgentIds are equal by comparing 'type' and 'key'."""
        if not isinstance(value, AgentId):
            return False
        return (self.type == value.type) and (self.key == value.key)

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Format the id as 'type/key', e.g. CoreAgentId.from_str('my-agent/default').
2. If you already have type and key separately, use CoreAgentId(type, key) directly.
3. Validate input shape before parsing: assert '/' in s and s.count('/') >= 1.
4. Trim whitespace and ensure the key segment is non-empty.

Example fix

// before
agent_id = CoreAgentId.from_str("my-agent")   # missing /key
// after
agent_id = CoreAgentId.from_str("my-agent/default")
# or
agent_id = CoreAgentId(type="my-agent", key="default")

def parse_agent_id_str(s: str):
    parts = s.split("/", maxsplit=1)
    if len(parts) != 2 or not parts[0] or not parts[1]:
        raise ValueError(f"Invalid agent id: {s}")
    return parts[0], parts[1]

def is_valid_agent_id_str(value: object) -> bool:
    if not isinstance(value, str) or "/" not in value:
        return False
    t, k = value.split("/", maxsplit=1)
    return bool(t) and bool(k)

try:
    agent_id = CoreAgentId.from_str(s)
except ValueError as e:
    if "Invalid agent id" in str(e):
        # fall back to constructing from known type/key
        agent_id = CoreAgentId(type=known_type, key=known_key)
    else:
        raise

When it happens

Trigger: Calling CoreAgentId.from_str(agent_id) with a string that has no slash (e.g. 'myagent') or, because of maxsplit=1, that is fine with one slash — but a totally slash-less or empty string yields len(items) != 2 and triggers the error.

Common situations: Parsing agent ids from external config/logs that omitted the key portion; passing only the type or only the key; whitespace trimming issues; splitting the wrong identifier (e.g. a topic name instead of an agent id).

Related errors

• Invalid agent type: {type}. Allowed values MUST match the re
• 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/05fd4b4abb2d820b. Report an issue: GitHub.