microsoft/autogen · error · ValueError

Agent description must be a string

Error message

Agent description must be a string

What it means

BaseAgent.__init__ validates that the description argument is a Python str. Passing None, a non-string object, or a value from loosely-typed config (e.g. a dict or int) triggers ValueError. The check happens after the instantiation-context lookup, but the context only needs to be active for runtime-bound construction; the type check applies in all cases.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_base_agent.py:90

    @classmethod
    def _handles_types(cls) -> List[Tuple[Type[Any], List[MessageSerializer[Any]]]]:
        return cls.internal_extra_handles_types

    @classmethod
    def _unbound_subscriptions(cls) -> List[UnboundSubscription]:
        return cls.internal_unbound_subscriptions_list

    @property
    def metadata(self) -> AgentMetadata:
        assert self._id is not None
        return AgentMetadata(key=self._id.key, type=self._id.type, description=self._description)

    def __init__(self, description: str) -> None:
        if AgentInstantiationContext.is_in_factory_call():
            self._runtime: AgentRuntime = AgentInstantiationContext.current_runtime()
            self._id = AgentInstantiationContext.current_agent_id()
        if not isinstance(description, str):
            raise ValueError("Agent description must be a string")
        self._description = description

    async def bind_id_and_runtime(self, id: AgentId, runtime: AgentRuntime) -> None:
        if hasattr(self, "_id"):
            if self._id != id:
                raise RuntimeError("Agent is already bound to a different ID")

        if hasattr(self, "_runtime"):
            if self._runtime != runtime:
                raise RuntimeError("Agent is already bound to a different runtime")

        self._id = id
        self._runtime = runtime

    @property
    def type(self) -> str:
        return self.id.type

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Pass a string literal: MyAgent("A helpful assistant").
2. Default missing config values: MyAgent(config.get('description', 'default description')).
3. Validate config at load time (pydantic model with description: str) before constructing agents.

Example fix

# before
agent = MyAgent(config.get('description'))  # None if key missing -> ValueError

# after
agent = MyAgent(config.get('description', 'A helpful assistant'))

description = config.get("description") or "default description"
if not isinstance(description, str):
    raise TypeError("config['description'] must be a string")
agent = MyAgent(description)

def is_agent_description(v: object) -> TypeGuard[str]:
    return isinstance(v, str)

When it happens

Trigger: BaseAgent(description=None), BaseAgent(description=123), or a factory like lambda: MyAgent(cfg['description']) where the config key is missing and yields None.

Common situations: Loading agent descriptions from YAML/JSON/env where the key is absent; passing a pydantic field that serializes to a non-string; copy-paste factories that forward positional args incorrectly.

Related errors

• Required create args are missing: {required_create_args - cr
• Unsupported config type {config.GetType()}
• Messages should not be provided in options
• The agent name must be a valid Python identifier.
• 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/7c9612ef4055b6df. Report an issue: GitHub.