What causes "Agent description must be a string" in microsoft/semantic-kernel?

Pass a string description: MyAgent(description="A helpful assistant").

microsoft/semantic-kernel · error · ValueError

Agent description must be a string

Error message

Agent description must be a string

What it means

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.

Source

Thrown at python/semantic_kernel/agents/runtime/core/base_agent.py:108

        """Get the metadata for this agent."""
        assert self._id is not None  # nosec
        return CoreAgentMetadata(key=self._id.key, type=self._id.type, description=self._description)

    def __init__(self, description: str) -> None:
        """Initialize the agent."""
        try:
            runtime = AgentInstantiationContext.current_runtime()
            id = AgentInstantiationContext.current_agent_id()
        except LookupError as e:
            raise RuntimeError(
                "BaseAgent must be instantiated within the context of an AgentRuntime. It cannot be directly "
                "instantiated."
            ) from e

        self._runtime: CoreRuntime = runtime
        self._id: AgentId = id
        if not isinstance(description, str):
            raise ValueError("Agent description must be a string")
        self._description = description

    @property
    def type(self) -> str:
        """Get the type of the agent."""
        return self.id.type

    @property
    def id(self) -> AgentId:
        """Get the id of the agent."""
        return self._id

    @property
    def runtime(self) -> CoreRuntime:
        """Get the runtime of the agent."""
        return self._runtime

    @final

View on GitHub (pinned to c028a0c7dc)

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.

Example fix

// before
await runtime.register("my-agent", lambda: MyAgent(description=None))
// after
await runtime.register(
    "my-agent",
    lambda: MyAgent(description="A helpful assistant"),
)

Defensive patterns

Strategy: validation

Validate before calling

def validate_description(description) -> str:
    if not isinstance(description, str):
        raise ValueError("Agent description must be a string")
    return description

Type guard

def is_str_description(value: object) -> bool:
    return isinstance(value, str)

Try / catch

try:
    agent = MyAgent(description=desc)
except ValueError as e:
    if "description must be a string" in str(e):
        agent = MyAgent(description=str(desc) if desc is not None else "")
    else:
        raise

Prevention

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.

When it happens

Trigger: Calling a BaseAgent subclass (via the runtime factory) with description=None, an int, a dict, or any non-string object.

Common situations: 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.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/41e87b44f232ed49. Report an issue: GitHub.