microsoft/semantic-kernel · 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 that provides access to the current runtime and agent ID during agent instantiation via a ContextVar. It is not meant to be instantiated directly — its __init__ unconditionally raises RuntimeError. The class exposes classmethods (current_runtime, current_agent_id) and a context manager (populate_context) for internal use by the runtime.

Source

Thrown at python/semantic_kernel/agents/runtime/in_process/agent_instantiation_context.py:24

from typing import Any, ClassVar

from semantic_kernel.agents.runtime.core.agent_id import AgentId
from semantic_kernel.agents.runtime.core.core_runtime import CoreRuntime
from semantic_kernel.utils.feature_stage_decorator import experimental


@experimental
class AgentInstantiationContext:
    """A static class that provides context for agent instantiation.

    This static class can be used to access the current runtime and agent ID
    during agent instantiation -- inside the factory function or the agent's
    class constructor.
    """

    def __init__(self) -> None:
        """Instantiate the AgentInstantiationContext class."""
        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[CoreRuntime, AgentId]]] = ContextVar(
        "_AGENT_INSTANTIATION_CONTEXT_VAR"
    )

    @classmethod
    @contextmanager
    def populate_context(cls, ctx: tuple[CoreRuntime, AgentId]) -> Generator[None, Any, None]:
        """Populate the context with the current runtime and agent ID."""
        token = AgentInstantiationContext._AGENT_INSTANTIATION_CONTEXT_VAR.set(ctx)
        try:
            yield
        finally:
            AgentInstantiationContext._AGENT_INSTANTIATION_CONTEXT_VAR.reset(token)

View on GitHub (pinned to c028a0c7dc)

Solutions

Do not instantiate the class. Access context through the classmethods: AgentInstantiationContext.current_runtime() and AgentInstantiationContext.current_agent_id().
If you need agent context inside an agent's __init__ or factory function, call the classmethods directly — the runtime sets the ContextVar for you during instantiation.

Example fix

// before
ctx = AgentInstantiationContext()

// after
runtime = AgentInstantiationContext.current_runtime()
agent_id = AgentInstantiationContext.current_agent_id()

Defensive patterns

Strategy: validation

Validate before calling

# This is a static class — never instantiate it.
# Validate by checking the class, not an instance:
from semantic_kernel.agents.runtime.in_process.agent_instantiation_context import AgentInstantiationContext
# Correct: use classmethods directly
runtime = AgentInstantiationContext.current_runtime()
agent_id = AgentInstantiationContext.current_agent_id()

Type guard

null

Try / catch

null

Prevention

Treat AgentInstantiationContext as a namespace/static accessor, never as a constructor.
Look for @classmethod and @contextmanager decorators — their presence signals static-only usage.

When it happens

Trigger: Calling AgentInstantiationContext() directly, e.g. `ctx = AgentInstantiationContext()`. The __init__ method raises immediately before any instance state is set.

Common situations: A developer discovers the class name and assumes it is a normal dataclass or context object, attempting to construct it to pass around agent context. Common when migrating from a pattern where context objects are injected manually.

Related errors

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/ffe35ff4643dd828. Report an issue: GitHub.