microsoft/autogen · error · TypeError

Agent with name {id.type} is not of type {type.__name__}. It

Error message

Agent with name {id.type} is not of type {type.__name__}. It is of type {type_func_alias(agent_instance).__name__}

What it means

Thrown by SingleThreadedAgentRuntime.try_get_underlying_agent_instance() when the runtime locates the requested agent (its type is registered and instantiated) but the concrete instance is not an instance of the type parameter you passed. The runtime deliberately enforces this check before returning, so you cannot accidentally receive an object of the wrong class and have it fail later at attribute access. The message names both the requested type and the actual runtime type of the instance.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_single_threaded_agent_runtime.py:997

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

        return agent_instance

    async def add_subscription(self, subscription: Subscription) -> None:
        await self._subscription_manager.add_subscription(subscription)

    async def remove_subscription(self, id: str) -> None:
        await self._subscription_manager.remove_subscription(id)

    async def get(
        self, id_or_type: AgentId | AgentType | str, /, key: str = "default", *, lazy: bool = True
    ) -> AgentId:
        return await get_impl(
            id_or_type=id_or_type,
            key=key,
            lazy=lazy,

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Read the message: it tells you the actual class of the instance; change the `type` argument of try_get_underlying_agent_instance to that class.
2. Verify what factory you registered for `id.type` (runtime.agent_styles / the AgentRuntime.register call) and make the requested type match the class that factory returns.
3. If you do not know the concrete class, call with the base class `try_get_underlying_agent_instance(id, Agent)` and then narrow with isinstance yourself.
4. If the agent registration itself is wrong (wrong class in the factory), fix the registration at startup.

Example fix

# before
agent = await runtime.try_get_underlying_agent_instance(
    AgentId("worker", "default"), MyOtherAgent
)  # TypeError: it is of type MyAgent

# after
from autogen_core import Agent
base = await runtime.try_get_underlying_agent_instance(AgentId("worker", "default"), Agent)
if isinstance(base, MyAgent):
    agent: MyAgent = base
else:
    raise TypeError(f"unexpected agent class {type(base).__name__}")

agent_id = AgentId("worker", "default")
base = await runtime.try_get_underlying_agent_instance(agent_id, Agent)  # base type always passes
if not isinstance(base, MyAgent):
    raise TypeError(f"worker agent is {type(base).__name__}, expected MyAgent")

def is_agent_of_type(runtime: SingleThreadedAgentRuntime, agent_id: AgentId, cls: type) -> bool:
    base = asyncio.get_event_loop().run_until_complete(
        runtime.try_get_underlying_agent_instance(agent_id, Agent)
    )
    return isinstance(base, cls)

try:
    agent = await runtime.try_get_underlying_agent_instance(agent_id, MyAgent)
except TypeError as e:
    # message contains the actual class name; log it and re-register or adjust callers
    logger.error("type mismatch: %s", e)
    raise

When it happens

Trigger: Calling `await runtime.try_get_underlying_agent_instance(AgentId("worker", "default"), MySubAgent)` when the agent type "worker" was registered with a factory producing a different class (e.g. `Agent` or another subclass). Also happens when two agent types share a key/type string and you fetch with the wrong type parameter, or after refactoring the agent class without updating the call site.

Common situations: Test code that grabs the underlying agent to assert on its state; refactoring where the agent class was renamed or swapped in the register call while callers still use the old class; copy-pasting an AgentId literal from another agent's code path.

Related errors

• Message type {type(message)} not in target types {target_typ
• Return type {type(return_value)} not in return types {return
• Return type {type(return_value)} is not None.
• SubscriptionInstantiationContext.runtime() must be called wi
• str(message.error)

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