microsoft/semantic-kernel · 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 looks up an agent by AgentId. If the agent is not already instantiated and its type string is not in _agent_factories, LookupError is raised. This is the lazy-instantiation guard: the runtime cannot create an agent whose factory was never registered.

Source

Thrown at python/semantic_kernel/agents/runtime/in_process/in_process_runtime.py:800

                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(evmattso): 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]
        """Try to get the underlying agent instance by name and namespace."""
        if id.type not in self._agent_factories:
            raise LookupError(f"Agent with name {id.type} not found.")

        # TODO(evmattso): 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__}. "

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Call register_factory for the agent type before requesting or sending to it.
2. Verify the agent type string in the AgentId matches the registered type exactly.
3. If loading saved state, ensure all referenced agent types are registered before loading.

Example fix

# before
agent = await runtime.get_agent(AgentId('my_agent', 'default'))  # raises

# after
await runtime.register_factory('my_agent', lambda: MyAgent())
agent = await runtime.get_agent(AgentId('my_agent', 'default'))

# Track registered types
registered_types: set[str] = set()
# After register_factory calls, add type names to the set
# Before get_agent:
if agent_id.type not in registered_types:
    raise ValueError(f'Agent type {agent_id.type} not registered')

null

try:
    agent = await runtime.get_agent(agent_id)
except LookupError:
    await runtime.register_factory(agent_id.type, factory)
    agent = await runtime.get_agent(agent_id)

When it happens

Trigger: Calling runtime.get_agent(AgentId('UnregisteredType', 'key')) or sending a message to an agent whose type was never registered. Also triggered internally when the runtime tries to load state for an unregistered agent.

Common situations: Agent type registered under a different name (typo, case difference). Agent used in a subscription routing before registration completes. Runtime state deserialization referencing an old/removed agent type.

Related errors

• Agent with name {id.type} not found.
• Agent type '{recipient.type}' does not exist.
• Agent with type {type} already exists.
• Factory registered using the wrong type.
• Agent factory must take 0 or 2 arguments.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/858969ece76c8ba3. Report an issue: GitHub.