What causes "MCP Actor not running, call initialize() first" in microsoft/autogen?

Await actor.initialize() before the first call(): await actor.initialize(); result = await actor.call('list_tools').

microsoft/autogen · error · RuntimeError

MCP Actor not running, call initialize() first

Error message

MCP Actor not running, call initialize() first

What it means

The MCP actor is a long-running asyncio task that owns the MCP session. call() checks the self._active flag set only by initialize(); calling any command before initialize() (or after close() reset it) raises RuntimeError('MCP Actor not running, call initialize() first'). It is a lifecycle-order error, not an MCP protocol error.

Source

Thrown at python/packages/autogen-ext/src/autogen_ext/tools/mcp/_actor.py:100

        self._command_queue: asyncio.Queue[Dict[str, Any]] = asyncio.Queue()
        self._actor_task: asyncio.Task[Any] | None = None
        self._shutdown_future: asyncio.Future[Any] | None = None
        self._active = False
        self._initialize_result: mcp_types.InitializeResult | None = None
        atexit.register(self._sync_shutdown)

    @property
    def initialize_result(self) -> mcp_types.InitializeResult | None:
        return self._initialize_result

    async def initialize(self) -> None:
        if not self._active:
            self._active = True
            self._actor_task = asyncio.create_task(self._run_actor())

    async def call(self, type: str, args: McpActorArgs | None = None) -> McpFuture:
        if not self._active:
            raise RuntimeError("MCP Actor not running, call initialize() first")
        if self._actor_task and self._actor_task.done():
            raise RuntimeError("MCP actor task crashed", self._actor_task.exception())
        fut: asyncio.Future[McpFuture] = asyncio.Future()
        if type in {"list_tools", "list_prompts", "list_resources", "list_resource_templates", "shutdown"}:
            await self._command_queue.put({"type": type, "future": fut})
            res = await fut
        elif type in {"call_tool", "read_resource", "get_prompt"}:
            if args is None:
                raise ValueError(f"args is required for {type}")
            name = args.get("name", None)
            kwargs = args.get("kargs", {})
            if type == "call_tool" and name is None:
                raise ValueError("name is required for call_tool")
            elif type == "read_resource":
                uri = kwargs.get("uri", None)
                if uri is None:
                    raise ValueError("uri is required for read_resource")
                await self._command_queue.put({"type": type, "uri": uri, "future": fut})

View on GitHub (pinned to 027ecf0a37)

Solutions

Await actor.initialize() before the first call(): await actor.initialize(); result = await actor.call('list_tools').
Make sure you call methods on the same actor instance you initialized.
After close(), create a new actor or re-call initialize() before issuing more commands.
In frameworks that manage the actor (e.g. McpWorkbench), use the framework's lifecycle entry points instead of touching the actor directly.

Example fix

# before
actor = McpActor(session_factory)
tools = await actor.call("list_tools")  # RuntimeError

# after
actor = McpActor(session_factory)
await actor.initialize()
tools = await actor.call("list_tools")

Defensive patterns

Strategy: validation

Validate before calling

if not actor._active:  # or track initialized state in your wrapper
    await actor.initialize()

Try / catch

try:
    res = await actor.call("list_tools")
except RuntimeError as e:
    if "not running" in str(e):
        await actor.initialize()
        res = await actor.call("list_tools")
    else:
        raise

Prevention

Encapsulate the actor in a context manager that initializes on __aenter__ and closes on __aexit__.
Never share actor construction and call sites across different code paths.
Add an integration test that exercises the full lifecycle (init -> call -> close).

When it happens

Trigger: Calling actor.call('list_tools') (or call_tool/read_resource/get_prompt) without awaiting actor.initialize() first, or after close() has run and cleared _active. Also when initialize() was scheduled but not awaited, so the flag is not yet set.

Common situations: Forgetting the initialize step in a script; awaiting initialize() on a different actor instance than the one used for call(); reusing an actor after close() in a retry loop; calling from a different event loop/task where initialization raced ahead.

Related errors

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