microsoft/semantic-kernel · error · AgentExecutionException

Channel Keys must not be empty. Unable to generate channel h

Error message

Channel Keys must not be empty. Unable to generate channel hash.

What it means

Raised by KeyEncoder.generate_hash() when the keys iterable is empty. The hash is used as a channel-map key derived from an agent's get_channel_keys(); an empty key list means the agent returned no channel keys, making it impossible to generate a unique channel hash. It is an AgentExecutionException.

Source

Thrown at python/semantic_kernel/agents/group_chat/agent_chat_utils.py:29

@experimental
class KeyEncoder:
    """A class for encoding keys."""

    @staticmethod
    def generate_hash(keys: Iterable[str]) -> str:
        """Generate a hash from a list of keys.

        Args:
            keys: A list of keys to generate the hash from.

        Returns:
            str: The generated hash.

        Raises:
            AgentExecutionException: If the keys are empty
        """
        if not keys:
            raise AgentExecutionException("Channel Keys must not be empty. Unable to generate channel hash.")
        joined_keys = ":".join(keys)
        buffer = joined_keys.encode("utf-8")
        sha256_hash = hashlib.sha256(buffer).digest()
        return base64.b64encode(sha256_hash).decode("utf-8")

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Ensure every Agent subclass returns at least one non-empty string from get_channel_keys().
2. If using a custom agent, override get_channel_keys() to return [self.__class__.__name__] or another stable identifier.
3. Validate agents before adding them to the group chat by checking agent.get_channel_keys() is non-empty.

Example fix

# before — custom agent returns empty channel keys
class MyAgent(Agent):
    def get_channel_keys(self) -> list[str]:
        return []

# after — return at least one stable key
class MyAgent(Agent):
    def get_channel_keys(self) -> list[str]:
        return [type(self).__name__]

keys = agent.get_channel_keys()
if not keys:
    raise ValueError(f"Agent {agent.name} returned empty channel keys")
chat.add_agent(agent)

def agent_has_channel_keys(agent) -> bool:
    return bool(agent.get_channel_keys())

When it happens

Trigger: An Agent subclass whose get_channel_keys() returns an empty list/tuple is added to an AgentGroupChat and invoked. AgentChat._get_agent_hash() calls KeyEncoder.generate_hash(agent.get_channel_keys()), which throws.

Common situations: Custom Agent subclass that does not override get_channel_keys() correctly; a bug in an agent factory that produces agents without channel keys; using a mock/stub agent in a group chat that lacks proper channel-key setup.

Related errors

• The Bedrock agent requires a message to be invoked.
• The streaming configuration must be null for non-streaming r
• The streaming configuration must have StreamFinalResponse se
• Bedrock agents must be invoked with a user message
• Invalid role: {authorRole}

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