microsoft/semantic-kernel · error · AgentExecutionException

{self.class.name} currently only supports agent thre

Error message

{self.__class__.__name__} currently only supports agent threads of type {expected_type.__name__}.

What it means

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.

Source

Thrown at python/semantic_kernel/agents/agent.py:516

        expected_type: type[TThreadType],
    ) -> TThreadType:
        """Ensure the thread exists with the provided message(s)."""
        if messages is None:
            messages = []

        if isinstance(messages, (str, ChatMessageContent)):
            messages = [messages]

        normalized_messages = [
            ChatMessageContent(role=AuthorRole.USER, content=msg) if isinstance(msg, str) else msg for msg in messages
        ]

        if thread is None:
            thread = construct_thread()
            await thread.create()

        if not isinstance(thread, expected_type):
            raise AgentExecutionException(
                f"{self.__class__.__name__} currently only supports agent threads of type {expected_type.__name__}."
            )

        # Track the agent ID as user msg metadata, which is useful for
        # fetching thread messages as the agent may have been deleted.
        id_metadata = {
            "agent_id": self.id,
        }

        # Notify the thread that new messages are available.
        for msg in normalized_messages:
            msg.metadata.update(id_metadata)
            await self._notify_thread_of_new_message(thread, msg)

        return thread

    async def _notify_thread_of_new_message(
        self,

View on GitHub (pinned to c028a0c7dc)

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().

Example fix

# before (wrong type for ChatCompletionAgent)
thread = AzureAIAgentThread()
await chat_agent.invoke(messages='hi', thread=thread)  # AgentExecutionException
# after
from semantic_kernel.agents import ChatHistoryAgentThread
thread = ChatHistoryAgentThread()
await thread.create()
await chat_agent.invoke(messages='hi', thread=thread)

Defensive patterns

Strategy: type-guard

Validate before calling

# Match the thread type to the agent; example for ChatCompletionAgent:
from semantic_kernel.agents import ChatHistoryAgentThread
assert isinstance(thread, ChatHistoryAgentThread) or thread is None, \
    f'ChatCompletionAgent requires ChatHistoryAgentThread, got {type(thread).__name__}'

Type guard

from typing import Type, TypeGuard
from semantic_kernel.agents.agent import AgentThread
def is_thread_of_type(thread, expected: Type[AgentThread]) -> TypeGuard[AgentThread]:
    return isinstance(thread, expected)

Try / catch

from semantic_kernel.exceptions.agent_exceptions import AgentExecutionException
try:
    await agent.invoke(messages='hi', thread=thread)
except AgentExecutionException as e:
    if 'only supports agent threads of type' in str(e):
        # construct the correct thread type and retry
        ...
    raise

Prevention

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().

When it happens

Trigger: 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.

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

Related errors

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