microsoft/autogen · error · LookupError

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

Error message

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

What it means

SingleThreadedAgentRuntime._process_send raises LookupError when a direct message is delivered to an agent whose type (the AgentId.type string) has no registered factory or instance. The runtime only routes sends to types in _known_agent_names, so an unregistered or misspelled type fails at dispatch time, not at send() time (send is async-queued).

Source

Thrown at python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py:471

        provided in the dictionary. The keys of the dictionary are the agent IDs, and the values are the state
        dictionaries returned by the :meth:`~autogen_core.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 = AgentId.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 {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)

                message_context = MessageContext(

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Register the target type before sending: await runtime.register_factory(AgentType("worker"), WorkerAgent.create) or the type-safe RuntimeAgentType registration helper
2. Verify membership before sending: if AgentType("worker") not in runtime._known_agent_names / use try_get_underlying_agent_instance guarded by try/except LookupError
3. Check exact spelling/case of the type string on both sides; centralize type literals as constants or use RuntimeAgentType classes so both ends share one definition
4. Ensure registration completes (await) before publish/send in startup code

Example fix

# before
await runtime.send_message(msg, AgentId("woker", "1"))  # typo -> LookupError

# after
WORKER = AgentType("worker")
await runtime.register_factory(WORKER, WorkerAgent.create)
await runtime.send_message(msg, AgentId(WORKER.type, "1"))

async def agent_type_exists(runtime, type_str: str) -> bool:
    try:
        await runtime.try_get_underlying_agent_instance(AgentId(type_str, "probe"))
        return True
    except LookupError:
        return False

def is_known_agent_type(runtime, t: AgentType) -> bool:
    return t.type in runtime._known_agent_names  # or track registrations in your own set

try:
    await runtime.send_message(msg, recipient)
except LookupError as e:
    if "does not exist" in str(e):
        # register late or route to fallback agent
        await runtime.register_factory(recipient.type, DefaultAgent.create)
    else:
        raise

When it happens

Trigger: Calling await runtime.send_message(msg, AgentId("worker", key)) where "worker" was never registered via register_factory/try_register... or as an instance; using an AgentType string that differs in case/spelling from the registered one; sending after the target type was registered on a different runtime instance.

Common situations: Typos or drift between the AgentType literal used by sender and receiver; forgetting to await registration before starting to send; multiple runtimes in tests where the agent was registered on runtime A but the send happens on runtime B; renamed agent types after refactoring.

Related errors

• Agent with name {agent_id.type} not found.
• Agent with name {id.type} not found.
• Agent with name {agentId.Type} not found.
• Agent with name {agentId.Type} not found.
• Agent is already bound to a different runtime

AI-assisted analysis of microsoft/autogen@027ecf0a37 (2026-08-15). Data as JSON: /api/errors/b0e771e44ad91756. Report an issue: GitHub.