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 looks up an agent by id in the worker's local _agent_factories and raises LookupError(f"Agent with name {id.type} not found.") when the type was never registered on this runtime. LookupError (rather than ValueError) is the API's 'expected miss' signal: callers are meant to catch it when probing for optional agents. Note it checks registration, not instantiation — an un-instantiated but registered type proceeds to _get_agent and lazily creates the agent.

Source

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

        return agent

    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 ValueError(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__}")

        return agent_instance

    async def add_subscription(self, subscription: Subscription) -> None:
        if self._host_connection is None:
            raise RuntimeError("Host connection is not set.")

        message = agent_worker_pb2.AddSubscriptionRequest(subscription=subscription_to_proto(subscription))
        _response: agent_worker_pb2.AddSubscriptionResponse = await self._host_connection.stub.AddSubscription(
            message, metadata=self._host_connection.metadata
        )

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Register the agent type (factory or instance) before calling try_get_underlying_agent_instance
2. Verify the exact type string (it must match the registration key, e.g. the class name used at register time)
3. For remote agents on other workers, do not use this local API — track their identities yourself or query via messaging
4. When absence is legitimate, catch LookupError and treat it as 'not present' rather than a failure

Example fix

# before
agent = await runtime.try_get_underlying_agent_instance(AgentId('assistant', 'default'))  # LookupError

# after
await runtime.register_factory('assistant', lambda: AssistantAgent())
try:
    agent = await runtime.try_get_underlying_agent_instance(AgentId('assistant', 'default'), AssistantAgent)
except LookupError:
    agent = None  # type not registered on this worker

def may_lookup(runtime, type_str: str) -> bool:
    return type_str in getattr(runtime, '_agent_factories', {})

try:
    agent = await runtime.try_get_underlying_agent_instance(AgentId(t, k), ExpectedClass)
except LookupError:
    agent = None  # type not registered locally — expected miss
except TypeError:
    raise  # registered but wrong class

When it happens

Trigger: Calling try_get_underlying_agent_instance with an AgentId whose type string has no factory/instance on this runtime; querying before registration finished; querying a type that lives on a different worker (this API is local; the TODO in source shows remote lookup is not implemented); typo or case mismatch in the type string.

Common situations: Inspecting agents from test harnesses or orchestration code before registering them; assuming the API resolves remote workers; iterating over expected agent names where some are optional.

Related errors

• Agent with name {agent_id.type} not found.
• Agent with type {type} already exists.
• Agent with name {id.type} is not of type {type.__name__}

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