{"record":{"id":"02a96c4131eb2b3b","repo":"microsoft/semantic-kernel","slug":"self-class-name-currently-only-supports","errorCode":null,"errorMessage":"{self.__class__.__name__} currently only supports agent threads of type {expected_type.__name__}.","messagePattern":"(.+?) currently only supports agent threads of type (.+?)\\.","errorType":"exception","errorClass":"AgentExecutionException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/agent.py","lineNumber":516,"sourceCode":"        expected_type: type[TThreadType],\n    ) -> TThreadType:\n        \"\"\"Ensure the thread exists with the provided message(s).\"\"\"\n        if messages is None:\n            messages = []\n\n        if isinstance(messages, (str, ChatMessageContent)):\n            messages = [messages]\n\n        normalized_messages = [\n            ChatMessageContent(role=AuthorRole.USER, content=msg) if isinstance(msg, str) else msg for msg in messages\n        ]\n\n        if thread is None:\n            thread = construct_thread()\n            await thread.create()\n\n        if not isinstance(thread, expected_type):\n            raise AgentExecutionException(\n                f\"{self.__class__.__name__} currently only supports agent threads of type {expected_type.__name__}.\"\n            )\n\n        # Track the agent ID as user msg metadata, which is useful for\n        # fetching thread messages as the agent may have been deleted.\n        id_metadata = {\n            \"agent_id\": self.id,\n        }\n\n        # Notify the thread that new messages are available.\n        for msg in normalized_messages:\n            msg.metadata.update(id_metadata)\n            await self._notify_thread_of_new_message(thread, msg)\n\n        return thread\n\n    async def _notify_thread_of_new_message(\n        self,","sourceCodeStart":498,"sourceCodeEnd":534,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/agent.py#L498-L534","documentation":"Inside _ensure_thread_exists_with_messages, the agent validates that the supplied AgentThread is an instance of the agent's expected thread type (each agent flavor requires a specific thread, e.g. AzureAIAgentThread, AssistantAgentThread). Passing a mismatched thread type raises AgentExecutionException. This prevents, for example, giving a ChatCompletionAgent an OpenAI assistant thread.","triggerScenarios":"Passing thread=<WrongThreadType> to an agent's invoke()/get_response(); reusing a thread created for one agent family with a different agent family; constructing a generic AgentThread base instead of the concrete subclass.","commonSituations":"Swapping agent types in a multi-agent app while reusing the same thread object; instantiating the abstract AgentThread base; copy-paste between samples that use different thread types.","solutions":["Use the thread type the error names as expected_type (e.g. ChatHistoryAgentThread for ChatCompletionAgent, AzureAIAgentThread for AzureAIAgent).","Create a fresh, correct thread type when switching agent families.","Do not instantiate the abstract AgentThread base; use the concrete subclass.","Check each agent's docs for its required thread type before wiring invoke()."],"exampleFix":"# before (wrong type for ChatCompletionAgent)\nthread = AzureAIAgentThread()\nawait chat_agent.invoke(messages='hi', thread=thread)  # AgentExecutionException\n# after\nfrom semantic_kernel.agents import ChatHistoryAgentThread\nthread = ChatHistoryAgentThread()\nawait thread.create()\nawait chat_agent.invoke(messages='hi', thread=thread)","handlingStrategy":"type-guard","validationCode":"# Match the thread type to the agent; example for ChatCompletionAgent:\nfrom semantic_kernel.agents import ChatHistoryAgentThread\nassert isinstance(thread, ChatHistoryAgentThread) or thread is None, \\\n    f'ChatCompletionAgent requires ChatHistoryAgentThread, got {type(thread).__name__}'","typeGuard":"from typing import Type, TypeGuard\nfrom semantic_kernel.agents.agent import AgentThread\ndef is_thread_of_type(thread, expected: Type[AgentThread]) -> TypeGuard[AgentThread]:\n    return isinstance(thread, expected)","tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentExecutionException\ntry:\n    await agent.invoke(messages='hi', thread=thread)\nexcept AgentExecutionException as e:\n    if 'only supports agent threads of type' in str(e):\n        # construct the correct thread type and retry\n        ...\n    raise","preventionTips":["Look up the required thread type per agent family before wiring.","Create a fresh correct thread when switching agent types.","Never instantiate the abstract AgentThread base.","Type-check the thread before passing it to invoke()/get_response()."],"tags":["agents","thread","type-mismatch","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}