{"record":{"id":"8766b835d0955736","repo":"microsoft/semantic-kernel","slug":"no-serializers-found-for-type-msg-type-r-please","errorCode":null,"errorMessage":"No serializers found for type {msg_type!r}. Please provide an explicit serializer.","messagePattern":"No serializers found for type (.+?)\\. Please provide an explicit serializer\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/runtime/core/base_agent.py","lineNumber":56,"sourceCode":"        return cls\n\n    return decorator\n\n\n@experimental\ndef handles(\n    msg_type: type[Any], serializer: MessageSerializer[Any] | list[MessageSerializer[Any]] | None = None\n) -> Callable[[type[BaseAgentType]], type[BaseAgentType]]:\n    \"\"\"Decorator for associating a message type and corresponding serializer(s) with a BaseAgent or its subclass.\"\"\"\n\n    def decorator(cls: type[BaseAgentType]) -> type[BaseAgentType]:\n        if serializer is None:\n            serializer_list = try_get_known_serializers_for_type(msg_type)\n        else:\n            serializer_list = [serializer] if not isinstance(serializer, Sequence) else list(serializer)\n\n        if not serializer_list:\n            raise ValueError(f\"No serializers found for type {msg_type!r}. Please provide an explicit serializer.\")\n\n        cls.internal_extra_handles_types.append((msg_type, serializer_list))\n        return cls\n\n    return decorator\n\n\n@experimental\nclass BaseAgent(ABC, Agent):\n    \"\"\"Base class for all agents.\"\"\"\n\n    internal_unbound_subscriptions_list: ClassVar[list[UnboundSubscription]] = []\n    \"\"\":meta private:\"\"\"\n    internal_extra_handles_types: ClassVar[list[tuple[type[Any], list[MessageSerializer[Any]]]]] = []\n    \"\"\":meta private:\"\"\"\n\n    def __init_subclass__(cls, **kwargs: Any) -> None:\n        \"\"\"Initialize the class.\"\"\"","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/runtime/core/base_agent.py#L38-L74","documentation":"Raised by the @handles decorator on BaseAgent when no serializer is supplied and the runtime cannot find a built-in serializer for the given message type. The decorator auto-discovers serializers only for pydantic BaseModel, dataclasses, and Protobuf Message subclasses; any other type yields no serializer, so the agent would be unable to (de)serialize that message over the runtime.","triggerScenarios":"Using @handles(SomeType) where SomeType is a plain class, a TypedDict, a str/int, or any type that is not a pydantic BaseModel, a @dataclass, or a protobuf Message, and not passing an explicit serializer argument.","commonSituations":"Defining a message as a regular class instead of a dataclass/pydantic model; passing a Python primitive as a message type; using a typing construct (Union, Optional) as the msg_type.","solutions":["Pass an explicit serializer: @handles(SomeType, serializer=MySerializer()).","Make SomeType a pydantic BaseModel, a @dataclass, or a protobuf Message so a known serializer is auto-discovered.","Register a custom MessageSerializer in the runtime's serialization registry and reference it.","Register a custom MessageSerializer in the runtime's serialization registry and reference it."],"exampleFix":"// before\n@handles(MyPlainMessage)\nclass MyAgent(BaseAgent):\n    ...\n// after\nfrom dataclasses import dataclass\n\n@dataclass\nclass MyMessage:\n    text: str\n\n@handles(MyMessage)\nclass MyAgent(BaseAgent):\n    ...","handlingStrategy":"validation","validationCode":"from pydantic import BaseModel\nfrom dataclasses import is_dataclass\nfrom google.protobuf.message import Message\n\ndef has_known_serializer(msg_type) -> bool:\n    return issubclass(msg_type, BaseModel) or is_dataclass(msg_type) or issubclass(msg_type, Message)","typeGuard":"def is_serializable_message_type(t: object) -> bool:\n    from pydantic import BaseModel\n    from dataclasses import is_dataclass\n    try:\n        from google.protobuf.message import Message\n        proto = issubclass(t, Message)\n    except Exception:\n        proto = False\n    return (isinstance(t, type) and (issubclass(t, BaseModel) or is_dataclass(t) or proto))","tryCatchPattern":"try:\n    @handles(MyMsg)\n    class MyAgent(BaseAgent): ...\nexcept ValueError as e:\n    if \"No serializers found\" in str(e):\n        from dataclasses import dataclass\n        # convert MyMsg to a dataclass or pass an explicit serializer\n        @handles(MyMsg, serializer=MyMsgSerializer())\n        class MyAgent(BaseAgent): ...\n    else:\n        raise","preventionTips":["Define messages as pydantic BaseModel, @dataclass, or protobuf Message.","Pass an explicit serializer for non-standard message types.","Avoid using primitives or plain classes as message types.","Register custom serializers in the runtime registry."],"tags":["runtime","serialization","decorators","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}