microsoft/autogen · error · ValueError

Invalid agent id: {agent_id}

Error message

Invalid agent id: {agent_id}

What it means

AgentId.from_str() parses strings of the exact format 'type/key' (split on the first '/'). If the input contains no '/' — or is empty — the split yields fewer than two parts and the constructor raises ValueError('Invalid agent id: ...'). The key may itself contain slashes (maxsplit=1), but the type portion may not be empty.

Source

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

        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

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

    @property
    def type(self) -> str:
        """
        An identifier that associates an agent with a specific factory function.

        Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).
        """
        return self._type

    @property
    def key(self) -> str:
        """
        Agent instance identifier.

        Strings may only be composed of alphanumeric letters (a-z) and (0-9), or underscores (_).

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Ensure the string is in 'type/key' form, e.g. AgentId.from_str("assistant/default").
2. If you only have a type, construct the ID directly: AgentId("assistant", "default").
3. When persisting IDs, store str(agent_id) (which yields 'type/key') so round-tripping through from_str works.
4. Sanitize/validate external input before calling from_str (see validation code).

Example fix

# before
agent_id = AgentId.from_str("assistant")  # ValueError

# after
agent_id = AgentId("assistant", "default")
# or
agent_id = AgentId.from_str("assistant/default")

def is_valid_agent_id_str(s: str) -> bool:
    return isinstance(s, str) and len(s.split("/", maxsplit=1)) == 2 and all(s.split("/", maxsplit=1))

# before: AgentId.from_str(raw)
if not is_valid_agent_id_str(raw):
    raise ValueError(f"expected 'type/key', got {raw!r}")
agent_id = AgentId.from_str(raw)

def is_agent_id_str(s: object) -> TypeGuard[str]:
    if not isinstance(s, str):
        return False
    parts = s.split("/", maxsplit=1)
    return len(parts) == 2 and bool(parts[0]) and bool(parts[1])

try:
    agent_id = AgentId.from_str(raw)
except ValueError as e:
    if "Invalid agent id" in str(e):
        # handle bad input: log, default, or re-raise with context
        raise ValueError(f"Bad agent id from config: {raw!r}") from e
    raise

When it happens

Trigger: Calling AgentId.from_str("my_agent") (no slash), AgentId.from_str("") , or passing a bare agent type where an 'type/key' string is expected (e.g. AgentId.from_str(agent.type) instead of str(agent.id)). Also hits when deserializing IDs from config/env vars that stored only the type.

Common situations: Reading agent IDs from environment variables, CLI args, JSON/YAML config, or message payloads where only the agent type was persisted; refactoring code that previously used plain strings as identifiers.

Related errors

• Invalid agent type: {type}. Allowed values MUST match the re
• Invalid topic id: {topic_id}
• Invalid AgentId type: '{type}'. Must be alphanumeric (a-z, 0
• Invalid AgentId key: '{key}'. Must only contain ASCII charac
• Invalid key-value pair format: {kvString}; expecting "{keyNa

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