microsoft/autogen · error · RuntimeError

AgentInstantiationContext cannot be instantiated. It is a st

Error message

AgentInstantiationContext cannot be instantiated. It is a static class that provides context management for agent instantiation.

What it means

AgentInstantiationContext is a static utility class whose __init__ deliberately raises RuntimeError. It exists only to expose classmethods (current_runtime, current_agent_id, populate_context, is_in_factory_call) that read a ContextVar holding the (runtime, agent_id) pair active during agent instantiation. It can never be meaningfully instantiated.

Source

Thrown at python/packages/autogen-core/src/autogen_core/_agent_instantiation.py:86

                # Start the runtime.
                runtime.start()

                # Register the agent type with a factory function.
                await runtime.register_factory("test_agent", test_agent_factory)

                # Send a message to the agent. The runtime will instantiate the agent and call the message handler.
                await runtime.send_message(TestMessage(content="Hello, world!"), AgentId("test_agent", "default"))

                # Stop the runtime.
                await runtime.stop()


            asyncio.run(main())

    """

    def __init__(self) -> None:
        raise RuntimeError(
            "AgentInstantiationContext cannot be instantiated. It is a static class that provides context management for agent instantiation."
        )

    _AGENT_INSTANTIATION_CONTEXT_VAR: ClassVar[ContextVar[tuple[AgentRuntime, AgentId]]] = ContextVar(
        "_AGENT_INSTANTIATION_CONTEXT_VAR"
    )

    @classmethod
    @contextmanager
    def populate_context(cls, ctx: tuple[AgentRuntime, AgentId]) -> Generator[None, Any, None]:
        """:meta private:"""
        token = AgentInstantiationContext._AGENT_INSTANTIATION_CONTEXT_VAR.set(ctx)
        try:
            yield
        finally:
            AgentInstantiationContext._AGENT_INSTANTIATION_CONTEXT_VAR.reset(token)

    @classmethod

View on GitHub (pinned to 027ecf0a37)

Solutions

1. Remove the instantiation; call the classmethods directly: AgentInstantiationContext.current_runtime(), .current_agent_id(), .is_in_factory_call().
2. If you need to set up a context (e.g. in tests or a custom runtime), use AgentInstantiationContext.populate_context((runtime, agent_id)) as a context manager.
3. In tests, prefer registering an agent factory with a real runtime (SingleThreadedAgentRuntime) so the context is populated for you.

Example fix

# before
ctx = AgentInstantiationContext()  # RuntimeError

# after
with AgentInstantiationContext.populate_context((runtime, agent_id)):
    rt = AgentInstantiationContext.current_runtime()

When it happens

Trigger: Writing AgentInstantiationContext() anywhere — e.g. trying to inject or mock it, or copy-pasting a class reference into a constructor call. The guard fires unconditionally on any instantiation attempt.

Common situations: Developers new to the framework treating the class like a service object to pass around; test code attempting to build a context object manually instead of using the runtime's register/instantiate path.

Related errors

• SubscriptionInstantiationContext cannot be instantiated. It
• AgentInstantiationContext.runtime() must be called within an
• AgentInstantiationContext.agent_id() must be called within a
• Agent is already bound to a different ID
• Agent is already bound to a different runtime

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