{"record":{"id":"1aeeae5d3c56f1b9","repo":"microsoft/autogen","slug":"agent-factory-was-invoked-for-an-agent-instance-th","errorCode":null,"errorMessage":"Agent factory was invoked for an agent instance that was not registered. This is likely due to the agent type being incorrectly subscribed to a topic. If this exception occurs when publishing a message to the DefaultTopicId, then it is likely that `skip_class_subscriptions` needs to be turned off when registering the agent.","messagePattern":"Agent factory was invoked for an agent instance that was not registered\\. This is likely due to the agent type being incorrectly subscribed to a topic\\. If this exception occurs when publishing a message to the DefaultTopicId, then it is likely that `skip_class_subscriptions` needs to be turned off when registering the agent\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py","lineNumber":922,"sourceCode":"                agent_instance = maybe_agent_instance\n\n            if expected_class is not None and not issubclass(type_func_alias(agent_instance), expected_class):\n                raise ValueError(\n                    f\"Factory registered using the wrong type: expected {expected_class.__name__}, got {type_func_alias(agent_instance).__name__}\"\n                )\n            return agent_instance\n\n        self._agent_factories[type.type] = factory_wrapper\n\n        return type\n\n    async def register_agent_instance(\n        self,\n        agent_instance: Agent,\n        agent_id: AgentId,\n    ) -> AgentId:\n        def agent_factory() -> Agent:\n            raise RuntimeError(\n                \"Agent factory was invoked for an agent instance that was not registered. This is likely due to the agent type being incorrectly subscribed to a topic. If this exception occurs when publishing a message to the DefaultTopicId, then it is likely that `skip_class_subscriptions` needs to be turned off when registering the agent.\"\n            )\n\n        if agent_id in self._instantiated_agents:\n            raise ValueError(f\"Agent with id {agent_id} already exists.\")\n\n        if agent_id.type not in self._agent_factories:\n            self._agent_factories[agent_id.type] = agent_factory\n            self._agent_instance_types[agent_id.type] = type_func_alias(agent_instance)\n        else:\n            if self._agent_factories[agent_id.type].__code__ != agent_factory.__code__:\n                raise ValueError(\"Agent factories and agent instances cannot be registered to the same type.\")\n            if self._agent_instance_types[agent_id.type] != type_func_alias(agent_instance):\n                raise ValueError(\"Agent instances must be the same object type.\")\n\n        await agent_instance.bind_id_and_runtime(id=agent_id, runtime=self)\n        self._instantiated_agents[agent_id] = agent_instance\n        return agent_id","sourceCodeStart":904,"sourceCodeEnd":940,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py#L904-L940","documentation":"When you register an agent via register_agent_instance, the runtime installs a sentinel factory whose only job is to raise this RuntimeError if invoked. It fires when the runtime tries to instantiate the instance-registered type for a different AgentId key — i.e. the type got subscribed to a topic, so publishing triggers _get_agent for a new key, which calls the sentinel instead of your instance.","triggerScenarios":"Registering an instance with register_agent_instance and also subscribing its type to a topic (auto class subscriptions on by default); then publishing to that topic (especially the DefaultTopicId) causes the runtime to construct 'another' agent of that type, hitting the sentinel. Also occurs when sending to AgentId(type, different_key) for an instance-registered type.","commonSituations":"Using register_agent_instance (stateful, single-agent pattern) while forgetting skip_class_subscriptions=True; publishing broadcast messages that the instance's default topic subscription picks up; mixing instance registration with topic-based fan-out designs that assume factories.","solutions":["Register with skip_class_subscriptions=True (turn it off in the registration call) so the instance's type is not auto-subscribed to DefaultTopicId","Or switch to register_factory so the type can instantiate agents for any subscriber key","If only a specific key should receive publishes, use a targeted subscription (TypeSubscription/regex to that key) or route via direct send_message"],"exampleFix":"# before\nawait runtime.register_agent_instance(agent, AgentId(\"counter\", \"default\"))\nawait runtime.publish_message(evt, DefaultTopicId())  # triggers sentinel factory\n\n# after\nawait runtime.register_agent_instance(\n    agent, AgentId(\"counter\", \"default\"), skip_class_subscriptions=True\n)\nawait runtime.send_message(cmd, AgentId(\"counter\", \"default\"))","handlingStrategy":"retry","validationCode":"def instance_registration_is_safe(subscriptions_for_type) -> bool:\n    # ensure no subscription targets an instance-registered type\n    return len(subscriptions_for_type) == 0","typeGuard":null,"tryCatchPattern":"try:\n    await runtime.send_message(msg, AgentId(t, key))\nexcept RuntimeError as e:\n    if \"Agent factory was invoked\" in str(e):\n        raise TypeError(\n            f\"type '{t}' is instance-registered; sends limited to the registered key\"\n        ) from e\n    raise","preventionTips":["Always pass skip_class_subscriptions=True with register_agent_instance","Prefer register_factory for any type that receives publishes","Reserve instance registration for single-key, send-only agents"],"tags":["autogen-core","agent-registration","subscriptions","default-topic","runtimeerror"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}