microsoft/autogen · error · LookupError

Agent with name {agent_id.type} not found.

Error message

Agent with name {agent_id.type} not found.

What it means

_get_agent raises LookupError when an AgentId's type has neither an instantiated agent nor a registered factory. It is the internal resolution path behind send_message, publish delivery, and save/load state, so any reference to an unknown type surfaces here (the send path raises the sibling error 'Agent type does not exist' earlier; this one fires for non-send resolution such as lazy instantiation during topic delivery or direct _get_agent use).

Source

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

                    agent = cast(T, await agent)
                return agent

            except BaseException as e:
                event_logger.info(
                    AgentConstructionExceptionEvent(
                        agent_id=agent_id,
                        exception=e,
                    )
                )
                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__}"
            )

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Register a factory (or instance) for every type any subscription or send targets before publishing/sending
2. Validate ids up front: keep a canonical list/dict of AgentType constants and check runtime._agent_factories membership (or catch LookupError) before resolution
3. Fix typos/renames by centralizing type strings (constants or RuntimeAgentType classes) shared by producers and consumers

Example fix

# before
await runtime.agent_save_state(AgentId("woker", "1"))  # typo -> LookupError

# after
WORKER = AgentType("worker")
await runtime.register_factory(WORKER, Worker.create)
await runtime.agent_save_state(AgentId(WORKER.type, "1"))

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

def is_known_type(runtime, agent_id) -> bool:
    return agent_id.type in runtime._agent_factories or agent_id in runtime._instantiated_agents

try:
    await runtime.try_get_underlying_agent_instance(agent_id, Agent)
except LookupError as e:
    if "not found" in str(e):
        log_and_register_or_skip(agent_id)
    else:
        raise

When it happens

Trigger: Resolving AgentId('unknown_type', key) via runtime.try_get_underlying_agent_instance, agent_save_state/agent_load_state, or indirectly when a subscription maps a topic to an agent type that was never registered; referencing a type after renaming its registration string.

Common situations: Subscriptions pointing at stale/misspelled agent types; orchestration code iterating expected agent names that were registered on a different runtime; tests that query agent state without registering the agent first.

Related errors

• Agent type '{recipient.type}' does not exist.
• Agent with name {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/224330ccda2d40f8. Report an issue: GitHub.