{"record":{"id":"b01c02c0942df9d6","repo":"microsoft/autogen","slug":"agent-with-name-id-type-not-found-b01c02","errorCode":null,"errorMessage":"Agent with name {id.type} not found.","messagePattern":"Agent with name (.+?) not found\\.","errorType":"exception","errorClass":"LookupError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py","lineNumber":812,"sourceCode":"\n        return agent\n\n    async def _get_agent(self, agent_id: AgentId) -> Agent:\n        if agent_id in self._instantiated_agents:\n            return self._instantiated_agents[agent_id]\n\n        if agent_id.type not in self._agent_factories:\n            raise ValueError(f\"Agent with name {agent_id.type} not found.\")\n\n        agent_factory = self._agent_factories[agent_id.type]\n        agent = await self._invoke_agent_factory(agent_factory, agent_id)\n        self._instantiated_agents[agent_id] = agent\n        return agent\n\n    # TODO: uncomment out the following type ignore when this is fixed in mypy: https://github.com/python/mypy/issues/3737\n    async def try_get_underlying_agent_instance(self, id: AgentId, type: Type[T] = Agent) -> T:  # type: ignore[assignment]\n        if id.type not in self._agent_factories:\n            raise LookupError(f\"Agent with name {id.type} not found.\")\n\n        # TODO: check if remote\n        agent_instance = await self._get_agent(id)\n\n        if not isinstance(agent_instance, type):\n            raise TypeError(f\"Agent with name {id.type} is not of type {type.__name__}\")\n\n        return agent_instance\n\n    async def add_subscription(self, subscription: Subscription) -> None:\n        if self._host_connection is None:\n            raise RuntimeError(\"Host connection is not set.\")\n\n        message = agent_worker_pb2.AddSubscriptionRequest(subscription=subscription_to_proto(subscription))\n        _response: agent_worker_pb2.AddSubscriptionResponse = await self._host_connection.stub.AddSubscription(\n            message, metadata=self._host_connection.metadata\n        )\n","sourceCodeStart":794,"sourceCodeEnd":830,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py#L794-L830","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Register the agent type (factory or instance) before calling try_get_underlying_agent_instance","Verify the exact type string (it must match the registration key, e.g. the class name used at register time)","For remote agents on other workers, do not use this local API — track their identities yourself or query via messaging","When absence is legitimate, catch LookupError and treat it as 'not present' rather than a failure"],"exampleFix":"# before\nagent = await runtime.try_get_underlying_agent_instance(AgentId('assistant', 'default'))  # LookupError\n\n# after\nawait runtime.register_factory('assistant', lambda: AssistantAgent())\ntry:\n    agent = await runtime.try_get_underlying_agent_instance(AgentId('assistant', 'default'), AssistantAgent)\nexcept LookupError:\n    agent = None  # type not registered on this worker","handlingStrategy":"try-catch","validationCode":"def may_lookup(runtime, type_str: str) -> bool:\n    return type_str in getattr(runtime, '_agent_factories', {})","typeGuard":null,"tryCatchPattern":"try:\n    agent = await runtime.try_get_underlying_agent_instance(AgentId(t, k), ExpectedClass)\nexcept LookupError:\n    agent = None  # type not registered locally — expected miss\nexcept TypeError:\n    raise  # registered but wrong class","preventionTips":["Register the type before lookup; verify exact type spelling","Remember the API is local-only — it cannot resolve agents on other workers","Treat LookupError as an expected 'absent' outcome in probing code","Cache lookup results per runtime generation"],"tags":["lookup","agent-type","not-found"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}