microsoft/autogen · error · LookupError

Agent with name {id.type} not found.

Error message

Agent with name {id.type} not found.

What it means

try_get_underlying_agent_instance raises LookupError when the AgentId's type is absent from _agent_factories — i.e. the runtime does not know the type at all. A separate TypeError is raised later if the type exists but the instance is not of the requested class, so this error specifically means 'no such agent type registered'.

Source

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

                logger.error(f"Error constructing agent {agent_id}", exc_info=True)
                raise

    async def _get_agent(self, agent_id: AgentId) -> Agent:
        if agent_id in self._instantiated_agents:
            return self._instantiated_agents[agent_id]

        if agent_id.type not in self._agent_factories:
            raise LookupError(f"Agent with name {agent_id.type} not found.")

        agent_factory = self._agent_factories[agent_id.type]
        agent = await self._invoke_agent_factory(agent_factory, agent_id)
        self._instantiated_agents[agent_id] = agent
        return agent

    # TODO: uncomment out the following type ignore when this is fixed in mypy: https://github.com/python/mypy/issues/3737
    async def try_get_underlying_agent_instance(self, id: AgentId, type: Type[T] = Agent) -> T:  # type: ignore[assignment]
        if id.type not in self._agent_factories:
            raise LookupError(f"Agent with name {id.type} not found.")

        # TODO: check if remote
        agent_instance = await self._get_agent(id)

        if not isinstance(agent_instance, type):
            raise TypeError(
                f"Agent with name {id.type} is not of type {type.__name__}. It is of type {type_func_alias(agent_instance).__name__}"
            )

        return agent_instance

    async def add_subscription(self, subscription: Subscription) -> None:
        await self._subscription_manager.add_subscription(subscription)

    async def remove_subscription(self, id: str) -> None:
        await self._subscription_manager.remove_subscription(id)

    async def get(

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Ensure register_factory/register_agent_instance ran (and was awaited) for that type before the lookup
2. Centralize type names as shared AgentType constants/enum so producers, registrations, and lookups cannot drift
3. Wrap the lookup in try/except LookupError when probing optional agents, treating absence as None

Example fix

# before
agent = await runtime.try_get_underlying_agent_instance(
    AgentId("worker", "1"), WorkerAgent
)  # LookupError if unregistered

# after
try:
    agent = await runtime.try_get_underlying_agent_instance(
        AgentId(WORKER.type, "1"), WorkerAgent
    )
except LookupError:
    agent = None

def lookup_will_succeed(runtime, agent_id) -> bool:
    return agent_id.type in runtime._agent_factories

def type_is_registered(runtime, t: str) -> bool:
    return t in runtime._agent_factories

try:
    agent = await runtime.try_get_underlying_agent_instance(
        AgentId(WORKER.type, key), WorkerAgent
    )
except LookupError:
    agent = None  # optional agent; handle absence
except TypeError:
    raise  # registered but wrong class: real bug

When it happens

Trigger: Calling await runtime.try_get_underlying_agent_instance(AgentId('worker', '1'), WorkerAgent) where 'worker' was never registered on this runtime; querying an agent instance in tests before registration; using an id built from a stale string constant after the registration name changed.

Common situations: Test helpers that grab the underlying instance to assert on internal state; refactors renaming agent types while call sites keep old strings; multiple runtimes (per-test) where lookup happens on the wrong runtime object.

Related errors

• Agent type '{recipient.type}' does not exist.
• Agent with name {agent_id.type} not found.
• Agent with name {agentId.Type} not found.
• Agent with name {agentId.Type} not found.
• Agent is already bound to a different runtime

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