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 stores instances in self._instantiated_agents keyed by AgentId. If the exact AgentId (type + key) is already present it raises ValueError('Agent with id {agent_id} already exists.') to prevent silently replacing a bound, running agent. This is a per-worker duplicate check, independent of registrations on other workers.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py:757

        self._agent_factories[type.type] = factory_wrapper
        # Send the registration request message to the host.
        await self._register_agent_type(type.type)

        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
            await self._register_agent_type(agent_id.type)
            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]],

View on GitHub (pinned to 027ecf0a37)

Solutions

  1. Check the id is not already registered before registering (inspect via runtime.try_get_underlying_agent_instance or track registered ids yourself)
  2. Use distinct keys per registration (e.g. uuid suffix) when the same type must hold several instances
  3. Recreate the runtime (or restart the kernel/fixture) between runs so _instantiated_agents resets
  4. Move registration into an idempotent setup function executed once per process

Example fix

# before
await runtime.register_agent_instance(agent, AgentId('assistant', 'default'))  # re-run -> ValueError

# after
aid = AgentId('assistant', 'default')
try:
    await runtime.register_agent_instance(agent, aid)
except ValueError:
    pass  # already registered this run
# or: key = f'default-{uuid4()}' when multiple instances are intended
Defensive patterns

Strategy: try-catch

Validate before calling

def id_free(runtime, agent_id) -> bool:
    return agent_id not in getattr(runtime, '_instantiated_agents', {})

Try / catch

try:
    await runtime.register_agent_instance(agent, agent_id)
except ValueError as e:
    if 'already exists' in str(e):
        pass  # already registered this session
    else:
        raise

Prevention

When it happens

Trigger: Calling register_agent_instance twice with the same AgentId on one runtime; re-running setup code (notebook cell, test fixture) against a runtime that still holds the previous registration; constructing the same logical agent in a loop with a constant key.

Common situations: Notebook re-execution without recreating the runtime; pytest fixtures that register a fixed AgentId on a session-scoped runtime; scripts that register agents on every retry of a connection loop.

Related errors

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