microsoft/autogen · error · RuntimeError

Agent factory was invoked for an agent instance that was not

Error message

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.

What it means

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.

Source

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

                agent_instance = maybe_agent_instance

            if expected_class is not None and not issubclass(type_func_alias(agent_instance), expected_class):
                raise ValueError(
                    f"Factory registered using the wrong type: expected {expected_class.__name__}, got {type_func_alias(agent_instance).__name__}"
                )
            return agent_instance

        self._agent_factories[type.type] = factory_wrapper

        return type

    async def register_agent_instance(
        self,
        agent_instance: Agent,
        agent_id: AgentId,
    ) -> AgentId:
        def agent_factory() -> Agent:
            raise RuntimeError(
                "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."
            )

        if agent_id in self._instantiated_agents:
            raise ValueError(f"Agent with id {agent_id} already exists.")

        if agent_id.type not in self._agent_factories:
            self._agent_factories[agent_id.type] = agent_factory
            self._agent_instance_types[agent_id.type] = type_func_alias(agent_instance)
        else:
            if self._agent_factories[agent_id.type].__code__ != agent_factory.__code__:
                raise ValueError("Agent factories and agent instances cannot be registered to the same type.")
            if self._agent_instance_types[agent_id.type] != type_func_alias(agent_instance):
                raise ValueError("Agent instances must be the same object type.")

        await agent_instance.bind_id_and_runtime(id=agent_id, runtime=self)
        self._instantiated_agents[agent_id] = agent_instance
        return agent_id

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Register with skip_class_subscriptions=True (turn it off in the registration call) so the instance's type is not auto-subscribed to DefaultTopicId
2. Or switch to register_factory so the type can instantiate agents for any subscriber key
3. If only a specific key should receive publishes, use a targeted subscription (TypeSubscription/regex to that key) or route via direct send_message

Example fix

# before
await runtime.register_agent_instance(agent, AgentId("counter", "default"))
await runtime.publish_message(evt, DefaultTopicId())  # triggers sentinel factory

# after
await runtime.register_agent_instance(
    agent, AgentId("counter", "default"), skip_class_subscriptions=True
)
await runtime.send_message(cmd, AgentId("counter", "default"))

def instance_registration_is_safe(subscriptions_for_type) -> bool:
    # ensure no subscription targets an instance-registered type
    return len(subscriptions_for_type) == 0

try:
    await runtime.send_message(msg, AgentId(t, key))
except RuntimeError as e:
    if "Agent factory was invoked" in str(e):
        raise TypeError(
            f"type '{t}' is instance-registered; sends limited to the registered key"
        ) from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Subscription already exists
• Subscription does not exist
• Agent type '{recipient.type}' does not exist.
• Agent with type {type} already exists.
• Factory registered using the wrong type: expected {expected_

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