{"record":{"id":"1bf61c112e539566","repo":"microsoft/semantic-kernel","slug":"system-messages-cannot-be-added-to-the-chat-histor","errorCode":null,"errorMessage":"System messages cannot be added to the chat history.","messagePattern":"System messages cannot be added to the chat history\\.","errorType":"exception","errorClass":"AgentChatException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/agents/group_chat/agent_chat.py","lineNumber":115,"sourceCode":"\n        return hash_value\n\n    async def add_chat_message(self, message: str | ChatMessageContent) -> None:\n        \"\"\"Add a chat message.\"\"\"\n        if isinstance(message, str):\n            message = ChatMessageContent(role=AuthorRole.USER, content=message)\n\n        await self.add_chat_messages([message])\n\n    async def add_chat_messages(self, messages: list[ChatMessageContent]) -> None:\n        \"\"\"Add chat messages.\"\"\"\n        self.set_activity_or_throw()\n\n        for message in messages:\n            if message.role == AuthorRole.SYSTEM:\n                error_message = \"System messages cannot be added to the chat history.\"\n                logger.error(error_message)\n                raise AgentChatException(error_message)\n\n        logger.info(f\"Adding `{len(messages)}` agent chat messages\")\n\n        try:\n            self.history.messages.extend(messages)\n\n            # Broadcast message to other channels (in parallel)\n            # Note: Able to queue messages without synchronizing channels.\n            channel_refs = [ChannelReference(channel=channel, hash=key) for key, channel in self.agent_channels.items()]\n            await self.broadcast_queue.enqueue(channel_refs, messages)\n        finally:\n            self.clear_activity_signal()\n\n    async def _get_or_create_channel(self, agent: Agent) -> AgentChannel:\n        \"\"\"Get or create a channel.\"\"\"\n        channel_key = self._get_agent_hash(agent)\n        channel = await self._synchronize_channel(channel_key)\n        if channel is None:","sourceCodeStart":97,"sourceCodeEnd":133,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/agents/group_chat/agent_chat.py#L97-L133","documentation":"Raised by AgentChat.add_chat_messages() (and transitively add_chat_message()) when any message in the batch has role == AuthorRole.SYSTEM. The group-chat history is designed to hold user/assistant/tool messages only; system messages are rejected because they represent instructions that should be configured at the agent level, not injected into shared chat history. It is an AgentChatException.","triggerScenarios":"Calling chat.add_chat_message(ChatMessageContent(role=AuthorRole.SYSTEM, content=...)) or add_chat_messages with a list containing a SYSTEM-role message.","commonSituations":"Porting code from ChatHistory (which does accept system messages) to AgentGroupChat; building messages generically and not filtering by role; accidentally including the system prompt in the message batch fed to the group chat.","solutions":["Filter out SYSTEM-role messages before calling add_chat_messages/add_chat_message.","Set system-level instructions on the individual agent's instructions or prompt_template_config instead of injecting them into the shared history.","Convert system messages to user-role messages if they must appear in the history."],"exampleFix":"# before\nawait chat.add_chat_message(\n    ChatMessageContent(role=AuthorRole.SYSTEM, content=\"You are helpful\")\n)  # raises\n\n# after — set instructions on the agent, add only user/assistant messages\nagent = ChatCompletionAgent(instructions=\"You are helpful\", ...)\nawait chat.add_chat_message(\n    ChatMessageContent(role=AuthorRole.USER, content=\"Hello\")\n)","handlingStrategy":"validation","validationCode":"from semantic_kernel.contents.utils.author_role import AuthorRole\n\nfiltered = [m for m in messages if m.role != AuthorRole.SYSTEM]\nawait chat.add_chat_messages(filtered)","typeGuard":"from semantic_kernel.contents.chat_message_content import ChatMessageContent\nfrom semantic_kernel.contents.utils.author_role import AuthorRole\n\ndef has_no_system_messages(msgs: list[ChatMessageContent]) -> bool:\n    return all(m.role != AuthorRole.SYSTEM for m in msgs)","tryCatchPattern":"from semantic_kernel.exceptions.agent_exceptions import AgentChatException\n\ntry:\n    await chat.add_chat_messages(messages)\nexcept AgentChatException as exc:\n    if \"System messages\" in str(exc):\n        messages = [m for m in messages if m.role != AuthorRole.SYSTEM]\n        await chat.add_chat_messages(messages)\n    raise","preventionTips":["Filter SYSTEM-role messages out before calling add_chat_messages/add_chat_message.","Set system instructions on individual agents, not in the shared chat history.","Validate message roles at the boundary where messages enter the group chat."],"tags":["validation","group-chat","chat-history","author-role"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}