microsoft/semantic-kernel · error · LookupError

Agent type '{recipient.type}' does not exist.

Error message

Agent type '{recipient.type}' does not exist.

What it means

When the runtime processes a SendMessageEnvelope, it checks whether the recipient's agent type is in _known_agent_names. If the type was never registered (or was registered under a different name string), a LookupError is raised. This is the send-side guard before attempting to invoke the message handler.

Source

Thrown at python/semantic_kernel/agents/runtime/in_process/in_process_runtime.py:349

        provided in the dictionary. The keys of the dictionary are the agent IDs, and the values are the state
        dictionaries returned by the :meth:`~agent_runtime.BaseAgent.save_state` method.

        .. note::

            This method does not currently load the subscription state. We will add this in the future.

        """
        for agent_id_str in state:
            agent_id = CoreAgentId.from_str(agent_id_str)
            if agent_id.type in self._known_agent_names:
                await (await self._get_agent(agent_id)).load_state(state[str(agent_id)])

    async def _process_send(self, message_envelope: SendMessageEnvelope) -> None:
        with self._tracer_helper.trace_block("send", message_envelope.recipient, parent=message_envelope.metadata):
            recipient = message_envelope.recipient

            if recipient.type not in self._known_agent_names:
                raise LookupError(f"Agent type '{recipient.type}' does not exist.")

            try:
                sender_id = str(message_envelope.sender) if message_envelope.sender is not None else "Unknown"
                logger.info(
                    f"Calling message handler for {recipient} with message type "
                    f"{type(message_envelope.message).__name__} sent by {sender_id}"
                )
                event_logger.info(
                    MessageEvent(
                        payload=self._try_serialize(message_envelope.message),
                        sender=message_envelope.sender,
                        receiver=recipient,
                        kind=MessageKind.DIRECT,
                        delivery_stage=DeliveryStage.DELIVER,
                    )
                )
                recipient_agent = await self._get_agent(recipient)

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Verify the recipient type string matches exactly what was passed to register_factory.
2. Ensure register_factory was called (and completed) before sending messages.
3. Check for case sensitivity and whitespace in the agent type string.
4. If using subscriptions, confirm the subscription's agent_type resolves to a registered factory.

Example fix

# before
await runtime.register_factory('my_agent', factory)
await runtime.send_message(msg, AgentId('MyAgent', 'default'))  # case mismatch

# after
await runtime.register_factory('my_agent', factory)
await runtime.send_message(msg, AgentId('my_agent', 'default'))

# Before sending, verify the agent type is registered
# (No public API to check; track registration in your own code)
registered_types: set[str] = set()
async def safe_register(runtime, type_name, factory):
    await runtime.register_factory(type_name, factory)
    registered_types.add(type_name)

# Guard sends:
if recipient.type not in registered_types:
    raise ValueError(f'Agent type {recipient.type} not registered')

null

try:
    await runtime.send_message(msg, recipient)
except LookupError:
    # recipient type not registered
    await runtime.register_factory(recipient.type, factory)
    await runtime.send_message(msg, recipient)

When it happens

Trigger: Calling runtime.send_message(message, AgentId('UnknownType', 'key')) where 'UnknownType' was never registered via register_factory. Also triggered by a subscription routing a message to an agent type that has no registered factory.

Common situations: Typo or case mismatch between the registered type name and the recipient type. Registering a factory under one name but sending to a slightly different name. Using an agent type from a different runtime instance or after the runtime was reset.

Related errors

• Agent with name {agent_id.type} not found.
• Agent with name {id.type} not found.
• Agent with type {type} already exists.
• Factory registered using the wrong type.
• Subscription already exists

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