{"record":{"id":"7c9612ef4055b6df","repo":"microsoft/autogen","slug":"agent-description-must-be-a-string","errorCode":null,"errorMessage":"Agent description must be a string","messagePattern":"Agent description must be a string","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-core/src/autogen_core/_base_agent.py","lineNumber":90,"sourceCode":"    @classmethod\n    def _handles_types(cls) -> List[Tuple[Type[Any], List[MessageSerializer[Any]]]]:\n        return cls.internal_extra_handles_types\n\n    @classmethod\n    def _unbound_subscriptions(cls) -> List[UnboundSubscription]:\n        return cls.internal_unbound_subscriptions_list\n\n    @property\n    def metadata(self) -> AgentMetadata:\n        assert self._id is not None\n        return AgentMetadata(key=self._id.key, type=self._id.type, description=self._description)\n\n    def __init__(self, description: str) -> None:\n        if AgentInstantiationContext.is_in_factory_call():\n            self._runtime: AgentRuntime = AgentInstantiationContext.current_runtime()\n            self._id = AgentInstantiationContext.current_agent_id()\n        if not isinstance(description, str):\n            raise ValueError(\"Agent description must be a string\")\n        self._description = description\n\n    async def bind_id_and_runtime(self, id: AgentId, runtime: AgentRuntime) -> None:\n        if hasattr(self, \"_id\"):\n            if self._id != id:\n                raise RuntimeError(\"Agent is already bound to a different ID\")\n\n        if hasattr(self, \"_runtime\"):\n            if self._runtime != runtime:\n                raise RuntimeError(\"Agent is already bound to a different runtime\")\n\n        self._id = id\n        self._runtime = runtime\n\n    @property\n    def type(self) -> str:\n        return self.id.type\n","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-core/src/autogen_core/_base_agent.py#L72-L108","documentation":"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.","triggerScenarios":"BaseAgent(description=None), BaseAgent(description=123), or a factory like lambda: MyAgent(cfg['description']) where the config key is missing and yields None.","commonSituations":"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.","solutions":["Pass a string literal: MyAgent(\"A helpful assistant\").","Default missing config values: MyAgent(config.get('description', 'default description')).","Validate config at load time (pydantic model with description: str) before constructing agents."],"exampleFix":"# before\nagent = MyAgent(config.get('description'))  # None if key missing -> ValueError\n\n# after\nagent = MyAgent(config.get('description', 'A helpful assistant'))","handlingStrategy":"validation","validationCode":"description = config.get(\"description\") or \"default description\"\nif not isinstance(description, str):\n    raise TypeError(\"config['description'] must be a string\")\nagent = MyAgent(description)","typeGuard":"def is_agent_description(v: object) -> TypeGuard[str]:\n    return isinstance(v, str)","tryCatchPattern":null,"preventionTips":["Type config schemas with pydantic (description: str) so bad values fail at load, not at agent construction.","Never pass config.get('description') unchecked into an agent constructor."],"tags":["autogen-core","validation","constructor","config"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}