microsoft/autogen · error · ValueError

Agent with id {agent_id} already exists.

Error message

Agent with id {agent_id} already exists.

What it means

register_agent_instance raises ValueError when the exact AgentId (type + key) is already present in _instantiated_agents. Each instance occupies one id; re-registering the same id — even with a new object — is rejected to prevent silently orphaning the bound agent.

Source

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

                )
            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

    async def _invoke_agent_factory(
        self,
        agent_factory: Callable[[], T | Awaitable[T]] | Callable[[AgentRuntime, AgentId], T | Awaitable[T]],
        agent_id: AgentId,

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Use a unique key per instance (e.g. str(i) or uuid) when registering many instances of the same type
2. Check agent_id in runtime._instantiated_agents (or track registered ids yourself) before registering
3. Recreate the SingleThreadedAgentRuntime when restarting a session rather than re-registering on the old one

Example fix

# before
await runtime.register_agent_instance(a1, AgentId("counter", "main"))
await runtime.register_agent_instance(a2, AgentId("counter", "main"))  # ValueError

# after
await runtime.register_agent_instance(a1, AgentId("counter", "main"))
await runtime.register_agent_instance(a2, AgentId("counter", "backup"))

async def register_instance_if_absent(runtime, agent, agent_id):
    if agent_id not in runtime._instantiated_agents:
        await runtime.register_agent_instance(agent, agent_id)
        return True
    return False

try:
    await runtime.register_agent_instance(agent, agent_id)
except ValueError as e:
    if "already exists" in str(e):
        existing = runtime._instantiated_agents[agent_id]
        # decide: reuse existing or pick a new key
    else:
        raise

When it happens

Trigger: Calling register_agent_instance(agent, AgentId("counter", "1")) twice; a startup routine that re-runs (retry, hot reload) and re-registers its instances; registering an instance created for a previous runtime run on a reused runtime object.

Common situations: Re-running initialization cells in notebooks; service restarts that rebuild agents against a runtime that was not recreated; loops that register one instance per worker with a constant key instead of a unique one.

Related errors

• Agent with type {type} already exists.
• Agent factories and agent instances cannot be registered to
• Agent instances must be the same object type.
• Agent factory with type {type} already exists.
• Subscription already exists

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