{"record":{"id":"41e87b44f232ed49","repo":"microsoft/semantic-kernel","slug":"agent-description-must-be-a-string","errorCode":null,"errorMessage":"Agent description must be a string","messagePattern":"Agent description must be a string","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/runtime/core/base_agent.py","lineNumber":108,"sourceCode":"        \"\"\"Get the metadata for this agent.\"\"\"\n        assert self._id is not None  # nosec\n        return CoreAgentMetadata(key=self._id.key, type=self._id.type, description=self._description)\n\n    def __init__(self, description: str) -> None:\n        \"\"\"Initialize the agent.\"\"\"\n        try:\n            runtime = AgentInstantiationContext.current_runtime()\n            id = AgentInstantiationContext.current_agent_id()\n        except LookupError as e:\n            raise RuntimeError(\n                \"BaseAgent must be instantiated within the context of an AgentRuntime. It cannot be directly \"\n                \"instantiated.\"\n            ) from e\n\n        self._runtime: CoreRuntime = runtime\n        self._id: AgentId = id\n        if not isinstance(description, str):\n            raise ValueError(\"Agent description must be a string\")\n        self._description = description\n\n    @property\n    def type(self) -> str:\n        \"\"\"Get the type of the agent.\"\"\"\n        return self.id.type\n\n    @property\n    def id(self) -> AgentId:\n        \"\"\"Get the id of the agent.\"\"\"\n        return self._id\n\n    @property\n    def runtime(self) -> CoreRuntime:\n        \"\"\"Get the runtime of the agent.\"\"\"\n        return self._runtime\n\n    @final","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/runtime/core/base_agent.py#L90-L126","documentation":"Raised by BaseAgent.__init__ when the description argument is not a str. The agent description is stored and used for runtime metadata/lookup, so a non-string (None, int, object) is rejected.","triggerScenarios":"Calling a BaseAgent subclass (via the runtime factory) with description=None, an int, a dict, or any non-string object.","commonSituations":"Forgetting to pass description and letting it default to None in a custom factory; passing a pydantic object or localized dict as description; config-driven factories that read a missing key and forward None.","solutions":["Pass a string description: MyAgent(description=\"A helpful assistant\").","In config-driven factories, coerce or default the value: description = str(config.get('description') or '').","Add a type check in your factory before constructing.","If description is optional in your domain, supply an empty string rather than None."],"exampleFix":"// before\nawait runtime.register(\"my-agent\", lambda: MyAgent(description=None))\n// after\nawait runtime.register(\n    \"my-agent\",\n    lambda: MyAgent(description=\"A helpful assistant\"),\n)","handlingStrategy":"validation","validationCode":"def validate_description(description) -> str:\n    if not isinstance(description, str):\n        raise ValueError(\"Agent description must be a string\")\n    return description","typeGuard":"def is_str_description(value: object) -> bool:\n    return isinstance(value, str)","tryCatchPattern":"try:\n    agent = MyAgent(description=desc)\nexcept ValueError as e:\n    if \"description must be a string\" in str(e):\n        agent = MyAgent(description=str(desc) if desc is not None else \"\")\n    else:\n        raise","preventionTips":["Always pass a string description to BaseAgent subclasses.","Default missing config values to '' rather than None.","Type-check descriptions in factories that read from config.","Add unit tests asserting description is a str."],"tags":["runtime","agent-lifecycle","validation","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}