microsoft/autogen · error · ValueError

Agent with name {agent_id.type} not found.

Error message

Agent with name {agent_id.type} not found.

What it means

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.

Source

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

                    "Agent factories that take two arguments are deprecated. Use AgentInstantiationContext instead. Two arg factories will be removed in a future version.",
                    stacklevel=2,
                )
                factory_two = cast(Callable[[AgentRuntime, AgentId], T], agent_factory)
                agent = factory_two(self, agent_id)
            else:
                raise ValueError("Agent factory must take 0 or 2 arguments.")

            if inspect.isawaitable(agent):
                agent = cast(T, await agent)

        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

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Ensure every worker that subscribes to a topic also registers a factory (or instance) for the agent type that subscription targets
2. Fix the agent_type string in add_subscription so it exactly matches the registered type (watch case/typos)
3. On worker restart, re-run the full registration sequence before the host resumes routing to it
4. Re-publish the message after registration completes; gate publishers on the subscriber's registration success

Example fix

# before
await runtime.add_subscription(TypeSubscription(topic_type='tasks', agent_type='TaskAgent'))
# but registered as 'task_agent' -> ValueError on delivery

# after
await runtime.register_factory('task_agent', lambda: TaskAgent())
await runtime.add_subscription(TypeSubscription(topic_type='tasks', agent_type='task_agent'))

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

try:
    await runtime.send_message(msg, AgentId('my_type', 'default'))
except ValueError as e:
    if 'not found' in str(e):
        raise ValueError('agent type not registered on this worker; fix subscriptions or register first') from e
    raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Agent factory was invoked for an agent instance that was not
• Agent with name {id.type} not found.
• Target is null.
• Handoff message target does not match agent name: {messages[
• Invalid next speaker: {next_speaker} from the ledger, partic

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