microsoft/semantic-kernel · error · AgentInitializationException

Service provided for ChatCompletionAgent is not an instance

Error message

Service provided for ChatCompletionAgent is not an instance of ChatCompletionClientBase. Service: {type(self.service)}

What it means

Raised by ChatCompletionAgent.configure_service (a pydantic model_validator, AgentInitializationException) when self.service is provided but is not an instance of ChatCompletionClientBase. The agent can only use a chat-completion service; passing any other service type (e.g. an embedding or text-completion service) fails initialization.

Source

Thrown at python/semantic_kernel/agents/chat_completion/chat_completion_agent.py:206

        if instructions is not None:
            args["instructions"] = instructions
        if prompt_template_config is not None:
            args["prompt_template"] = TEMPLATE_FORMAT_MAP[prompt_template_config.template_format](
                prompt_template_config=prompt_template_config
            )
            if prompt_template_config.template is not None:
                # Use the template from the prompt_template_config if it is provided
                args["instructions"] = prompt_template_config.template
        super().__init__(**args)

    @model_validator(mode="after")
    def configure_service(self) -> "ChatCompletionAgent":
        """Configure the service used by the ChatCompletionAgent."""
        if self.service is None:
            return self
        if not isinstance(self.service, ChatCompletionClientBase):
            raise AgentInitializationException(
                f"Service provided for ChatCompletionAgent is not an instance of ChatCompletionClientBase. "
                f"Service: {type(self.service)}"
            )
        self.kernel.add_service(self.service, overwrite=True)
        return self

    async def create_channel(
        self, chat_history: ChatHistory | None = None, thread_id: str | None = None
    ) -> AgentChannel:
        """Create a ChatHistoryChannel.

        Args:
            chat_history: The chat history for the channel. If None, a new ChatHistory instance will be created.
            thread_id: The ID of the thread. If None, a new thread will be created.

        Returns:
            An instance of AgentChannel.
        """

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass a ChatCompletionClientBase service instance (e.g. AzureChatCompletion or OpenAIChatComplete) as the service argument.
2. If relying on a kernel-registered service, omit the service argument and let the agent select via kernel.select_ai_service, or ensure a chat-completion service is registered.
3. Double-check the service variable is a service object, not settings or a client.
4. After upgrade, confirm the service class still subclasses ChatCompletionClientBase.

Example fix

// before
agent = ChatCompletionAgent(service=AzureTextCompletion(...))  # raises
// after
from semantic_kernel.connectors.ai.open_ai import AzureChatCompletion
agent = ChatCompletionAgent(service=AzureChatCompletion(...))

from semantic_kernel.connectors.ai.chat_completion_client_base import ChatCompletionClientBase
def validate_service(service):
    if service is not None and not isinstance(service, ChatCompletionClientBase):
        raise TypeError(f'service must be ChatCompletionClientBase, got {type(service)}')
    return service

def is_chat_completion_service(service) -> bool:
    from semantic_kernel.connectors.ai.chat_completion_client_base import ChatCompletionClientBase
    return isinstance(service, ChatCompletionClientBase)

from semantic_kernel.exceptions.agent_exceptions import AgentInitializationException
try:
    agent = ChatCompletionAgent(service=svc)
except AgentInitializationException as e:
    if 'not an instance of ChatCompletionClientBase' in str(e): raise TypeError(e)
    raise

When it happens

Trigger: Constructing ChatCompletionAgent(service=<embedding/text-completion service object>); passing a service retrieved from the kernel that is not a ChatCompletionClientBase; passing a dict or settings object instead of a service instance.

Common situations: Registering an embedding service and handing it to ChatCompletionAgent; confusing PromptExecutionSettings with a service; version change where a service base class was renamed; passing a text-completion service to a chat-completion-only agent.

Related errors

• Chat completion service not found. Check your service or ker
• Failed to validate settings: {exc}
• chat_deployment_name is required.
• The client does not support sampling.
• AI Chat Service type '{appConfig.RagConfig.AIChatService}' i

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