{"record":{"id":"2216ee921138fd59","repo":"microsoft/autogen","slug":"agent-with-name-agent-id-type-not-found-2216ee","errorCode":null,"errorMessage":"Agent with name {agent_id.type} not found.","messagePattern":"Agent with name (.+?) not found\\.","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py","lineNumber":802,"sourceCode":"                    \"Agent factories that take two arguments are deprecated. Use AgentInstantiationContext instead. Two arg factories will be removed in a future version.\",\n                    stacklevel=2,\n                )\n                factory_two = cast(Callable[[AgentRuntime, AgentId], T], agent_factory)\n                agent = factory_two(self, agent_id)\n            else:\n                raise ValueError(\"Agent factory must take 0 or 2 arguments.\")\n\n            if inspect.isawaitable(agent):\n                agent = cast(T, await agent)\n\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","sourceCodeStart":784,"sourceCodeEnd":820,"githubUrl":"https://github.com/microsoft/autogen/blob/027ecf0a379bcc1d09956d46d12d44a3ad9cee14/python/packages/autogen-ext/src/autogen_ext/runtimes/grpc/_worker_runtime.py#L784-L820","documentation":"GrpcWorkerAgentRuntime._get_agent resolves an AgentId by first checking _instantiated_agents, then looking for a factory in _agent_factories. If neither exists it raises ValueError(f\"Agent with name {agent_id.type} not found.\") — the worker received work for an agent type it never registered. In the gRPC worker model the host routes by subscription, so this usually means the subscription map sends a topic's messages to a worker that does not own that agent type.","triggerScenarios":"A subscription (added on the host or worker) maps a topic to an agent type that this worker never registered; the host still holds a stale registration for a worker that restarted without re-registering; another worker registered the type but this worker subscribed to the same topic; messages arrive before registration completes or after the worker's registration was dropped.","commonSituations":"Workers restarting (crash, redeploy) and losing in-memory registrations while the host keeps routing; subscription added with a wrong agent_type string (typo/case mismatch); multiple workers with overlapping TypeSubscriptions but only one registering the type; race between runtime.start(), register_factory, and the first publish.","solutions":["Ensure every worker that subscribes to a topic also registers a factory (or instance) for the agent type that subscription targets","Fix the agent_type string in add_subscription so it exactly matches the registered type (watch case/typos)","On worker restart, re-run the full registration sequence before the host resumes routing to it","Re-publish the message after registration completes; gate publishers on the subscriber's registration success"],"exampleFix":"# before\nawait runtime.add_subscription(TypeSubscription(topic_type='tasks', agent_type='TaskAgent'))\n# but registered as 'task_agent' -> ValueError on delivery\n\n# after\nawait runtime.register_factory('task_agent', lambda: TaskAgent())\nawait runtime.add_subscription(TypeSubscription(topic_type='tasks', agent_type='task_agent'))","handlingStrategy":"validation","validationCode":"def type_registered_locally(runtime, type_str: str) -> bool:\n    return type_str in getattr(runtime, '_agent_factories', {})","typeGuard":null,"tryCatchPattern":"try:\n    await runtime.send_message(msg, AgentId('my_type', 'default'))\nexcept ValueError as e:\n    if 'not found' in str(e):\n        raise ValueError('agent type not registered on this worker; fix subscriptions or register first') from e\n    raise","preventionTips":["Register the agent type on every worker whose subscription can receive its messages","Keep subscription agent_type strings byte-identical to registered names","Re-run full registration on worker restart before traffic resumes","Gate publishers on subscriber registration completion"],"tags":["routing","subscription","agent-type","not-found"],"backgroundTag":null,"analyzedSha":"027ecf0a379bcc1d09956d46d12d44a3ad9cee14","analyzedAt":"2026-08-15T03:38:00.719Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}