{"record":{"id":"b0e771e44ad91756","repo":"microsoft/autogen","slug":"agent-type-recipient-type-does-not-exist","errorCode":null,"errorMessage":"Agent type '{recipient.type}' does not exist.","messagePattern":"Agent type '(.+?)' does not exist\\.","errorType":"exception","errorClass":"LookupError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py","lineNumber":471,"sourceCode":"        provided in the dictionary. The keys of the dictionary are the agent IDs, and the values are the state\n        dictionaries returned by the :meth:`~autogen_core.BaseAgent.save_state` method.\n\n        .. note::\n\n            This method does not currently load the subscription state. We will add this in the future.\n\n        \"\"\"\n        for agent_id_str in state:\n            agent_id = AgentId.from_str(agent_id_str)\n            if agent_id.type in self._known_agent_names:\n                await (await self._get_agent(agent_id)).load_state(state[str(agent_id)])\n\n    async def _process_send(self, message_envelope: SendMessageEnvelope) -> None:\n        with self._tracer_helper.trace_block(\"send\", message_envelope.recipient, parent=message_envelope.metadata):\n            recipient = message_envelope.recipient\n\n            if recipient.type not in self._known_agent_names:\n                raise LookupError(f\"Agent type '{recipient.type}' does not exist.\")\n\n            try:\n                sender_id = str(message_envelope.sender) if message_envelope.sender is not None else \"Unknown\"\n                logger.info(\n                    f\"Calling message handler for {recipient} with message type {type(message_envelope.message).__name__} sent by {sender_id}\"\n                )\n                event_logger.info(\n                    MessageEvent(\n                        payload=self._try_serialize(message_envelope.message),\n                        sender=message_envelope.sender,\n                        receiver=recipient,\n                        kind=MessageKind.DIRECT,\n                        delivery_stage=DeliveryStage.DELIVER,\n                    )\n                )\n                recipient_agent = await self._get_agent(recipient)\n\n                message_context = MessageContext(","sourceCodeStart":453,"sourceCodeEnd":489,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py#L453-L489","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register the target type before sending: await runtime.register_factory(AgentType(\"worker\"), WorkerAgent.create) or the type-safe RuntimeAgentType registration helper","Verify membership before sending: if AgentType(\"worker\") not in runtime._known_agent_names / use try_get_underlying_agent_instance guarded by try/except LookupError","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","Ensure registration completes (await) before publish/send in startup code"],"exampleFix":"# before\nawait runtime.send_message(msg, AgentId(\"woker\", \"1\"))  # typo -> LookupError\n\n# after\nWORKER = AgentType(\"worker\")\nawait runtime.register_factory(WORKER, WorkerAgent.create)\nawait runtime.send_message(msg, AgentId(WORKER.type, \"1\"))","handlingStrategy":"validation","validationCode":"async def agent_type_exists(runtime, type_str: str) -> bool:\n    try:\n        await runtime.try_get_underlying_agent_instance(AgentId(type_str, \"probe\"))\n        return True\n    except LookupError:\n        return False","typeGuard":"def is_known_agent_type(runtime, t: AgentType) -> bool:\n    return t.type in runtime._known_agent_names  # or track registrations in your own set","tryCatchPattern":"try:\n    await runtime.send_message(msg, recipient)\nexcept LookupError as e:\n    if \"does not exist\" in str(e):\n        # register late or route to fallback agent\n        await runtime.register_factory(recipient.type, DefaultAgent.create)\n    else:\n        raise","preventionTips":["Define AgentType constants once and import them everywhere","Await all registrations before starting the message flow","Add a startup assertion listing required types vs registered types"],"tags":["autogen-core","runtime","agent-registration","lookuperror","send"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}