microsoft/semantic-kernel · 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 checks if the agent type exists in _agent_factories before attempting retrieval. If not found, LookupError is raised. This is the public API entry point for typed agent access, with the same registration requirement as _get_agent.

Source

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

                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__}. "
                f"It is of type {type_func_alias(agent_instance).__name__}"
            )

        return agent_instance

    async def add_subscription(self, subscription: Subscription) -> None:
        """Add a subscription to the runtime."""
        await self._subscription_manager.add_subscription(subscription)

    async def remove_subscription(self, id: str) -> None:
        """Remove a subscription from the runtime."""

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Register the factory for the agent type before calling try_get_underlying_agent_instance.
2. Verify the type string matches exactly (case-sensitive).
3. Handle LookupError gracefully if the agent may legitimately not exist.

Example fix

# before
agent = await runtime.try_get_underlying_agent_instance(
    AgentId('my_agent', 'default'), MyAgent
)  # raises LookupError

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

# Track registered types and check before calling
if id.type not in my_registered_types:
    raise ValueError(f'Agent {id.type} not registered')
agent = await runtime.try_get_underlying_agent_instance(id, MyAgent)

null

try:
    agent = await runtime.try_get_underlying_agent_instance(id, MyAgent)
except LookupError:
    # agent not registered — handle gracefully
    agent = None

When it happens

Trigger: Calling await runtime.try_get_underlying_agent_instance(AgentId('Unknown', 'key'), MyAgent) where 'Unknown' was never registered. The check happens before instantiation is attempted.

Common situations: Requesting an agent instance before registration, or after the runtime was recreated/reset. Type string mismatch between registration and retrieval.

Related errors

• Agent with name {agent_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/133fc82c1baafc23. Report an issue: GitHub.