microsoft/semantic-kernel · error · CantHandleException

If agent_type is not specified DefaultSubscription must be c

Error message

If agent_type is not specified DefaultSubscription must be created within the subscription callback in AgentRuntime.register

What it means

DefaultSubscription auto-detects the agent type by querying SubscriptionInstantiationContext.agent_type() when agent_type is not explicitly passed. If that context is unavailable (not within the subscription callback of AgentRuntime.register), a CantHandleException is raised indicating the subscription must be created inside that callback.

Source

Thrown at python/semantic_kernel/agents/runtime/in_process/default_subscription.py:33

class DefaultSubscription(TypeSubscription):
    """The default subscription is designed to be a default for applications that only need global scope for agents.

    This topic by default uses the "default" topic type and attempts to detect the agent type to use based on the
    instantiation context.

    Args:
        topic_type (str, optional): The topic type to subscribe to. Defaults to "default".
        agent_type (str, optional): The agent type to use for the subscription. Defaults to None, in which case it
            will attempt to detect the agent type based on the instantiation context.
    """

    def __init__(self, topic_type: str = "default", agent_type: str | AgentType | None = None):
        """Initialize the DefaultSubscription."""
        if agent_type is None:
            try:
                agent_type = SubscriptionInstantiationContext.agent_type().type
            except RuntimeError as e:
                raise CantHandleException(
                    "If agent_type is not specified DefaultSubscription must be created within the subscription "
                    "callback in AgentRuntime.register"
                ) from e

        super().__init__(topic_type, agent_type)


BaseAgentType = TypeVar("BaseAgentType", bound="BaseAgent")


@overload
def default_subscription() -> Callable[[type[BaseAgentType]], type[BaseAgentType]]: ...


@overload
def default_subscription(cls: type[BaseAgentType]) -> type[BaseAgentType]: ...

View on GitHub (pinned to c028a0c7dc)

Solutions

Pass agent_type explicitly: DefaultSubscription(topic_type='default', agent_type='MyAgent').
Ensure the @default_subscription() decorator is used on a class that is registered via runtime.register so the subscription callback context is active.
Move DefaultSubscription creation inside the register callback rather than at module import time.

Example fix

# before
@default_subscription()
class MyAgent(ChatAgent):
    ...
# CantHandleException at decoration time

# after
from semantic_kernel.agents import DefaultSubscription
await runtime.register("MyAgent", lambda: MyAgent(), subscriptions=[DefaultSubscription(agent_type='MyAgent')])

Defensive patterns

Strategy: validation

Validate before calling

# Always pass agent_type explicitly when creating DefaultSubscription outside a register callback
from semantic_kernel.agents.runtime.in_process.default_subscription import DefaultSubscription
sub = DefaultSubscription(topic_type='default', agent_type='MyAgent')

Type guard

null

Try / catch

from semantic_kernel.agents.runtime.in_process.default_subscription import DefaultSubscription
from semantic_kernel.exceptions import CantHandleException
try:
    sub = DefaultSubscription()  # relies on context
except CantHandleException:
    sub = DefaultSubscription(agent_type='MyAgent')  # explicit fallback

Prevention

Always pass agent_type explicitly unless inside the register subscription callback.
Use the @default_subscription() decorator only on classes registered via runtime.register.

When it happens

Trigger: Using @default_subscription() decorator on an agent class but the decorator runs outside the runtime's register callback. Or constructing DefaultSubscription(agent_type=None) in user code outside the register_subscription callback.

Common situations: A developer uses the @default_subscription() class decorator at module level (where no subscription context exists) without specifying agent_type. The decorator needs the subscription callback context to infer the type automatically.

Related errors

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