microsoft/semantic-kernel · error · AgentInvokeException

Polling timed out before completion.

Error message

Polling timed out before completion.

What it means

Raised as an AgentInvokeException when the polling loop that waits for a non-streaming OpenAI Responses run to reach "completed" exceeds agent.polling_options.run_polling_timeout. The Responses API returns runs that are processed server-side, so Semantic Kernel polls responses.retrieve until status == "completed"; if that does not happen within the configured deadline, this fires.

Source

Thrown at python/semantic_kernel/agents/open_ai/responses_agent_thread_actions.py:219

            if response.status in cls.error_message_states:
                error_message = ""
                if response.error and response.error.message:
                    error_message = response.error.message
                incomplete_details = ""
                if response.incomplete_details:
                    incomplete_details = str(response.incomplete_details.reason)
                raise AgentInvokeException(
                    f"Run failed with status: `{response.status}` for agent `{agent.name}` "
                    f"with error: {error_message} or incomplete details: {incomplete_details}"
                )

            try:
                response = await asyncio.wait_for(
                    cls._poll_until_completed(agent, response, polling_options or agent.polling_options),
                    timeout=agent.polling_options.run_polling_timeout.total_seconds(),
                )
            except asyncio.TimeoutError:
                raise AgentInvokeException("Polling timed out before completion.")

            # Type narrowing for subsequent usage
            assert isinstance(response, Response)  # nosec

            # Extract reasoning content and yield as intermediate message (not visible to user)
            reasoning_items = cls._get_reasoning_items_from_output(response.output)  # type: ignore
            if reasoning_items:
                reasoning_message = ChatMessageContent(
                    role=AuthorRole.ASSISTANT,
                    items=cast(list[CMC_ITEM_TYPES], reasoning_items),
                    ai_model_id=agent.ai_model_id,
                    metadata=cls._get_metadata_from_response(response),
                    name=agent.name,
                )
                yield False, reasoning_message

            # Check if tool calls are required
            function_calls = cls._get_tool_calls_from_output(response.output)  # type: ignore

View on GitHub (pinned to c028a0c7dc)

Solutions

  1. Increase agent.polling_options.run_polling_timeout to a larger timedelta.
  2. Tune polling_options polling interval/strategy via RunPollingOptions so polls are neither too sparse nor too aggressive.
  3. Reduce the run's complexity (fewer tools, smaller context) so it completes faster.
  4. Verify network connectivity/latency to the OpenAI endpoint; a slow link makes each retrieve poll expensive.
  5. If using Azure, check the deployment region/provisioned throughput for slowness.

Example fix

# before
agent = OpenAIResponsesAgent(
    ai_model_id="gpt-4o",
    client=client,
    instructions="...",
)
# after - give long tool-using runs a larger polling budget
from semantic_kernel.agents.open_ai import RunPollingOptions
agent.polling_options = RunPollingOptions(run_polling_timeout=timedelta(minutes=5))
Defensive patterns

Strategy: retry

Validate before calling

# Confirm the polling timeout fits the worst-case run before invoking:
from datetime import timedelta
if agent.polling_options.run_polling_timeout < timedelta(seconds=30):
    agent.polling_options.run_polling_timeout = timedelta(minutes=3)

Try / catch

from semantic_kernel.exceptions import AgentInvokeException
attempt = 0
while True:
    try:
        async for is_final, msg in agent.invoke(thread=thread):
            ...
        break
    except AgentInvokeException as ex:
        if "Polling timed out" not in str(ex) or attempt >= 2:
            raise
        attempt += 1  # retry after widening the budget
        agent.polling_options.run_polling_timeout *= 2

Prevention

When it happens

Trigger: asyncio.wait_for around _poll_until_completed (which loops calling agent.client.responses.retrieve until status == "completed") hits the timeout configured at agent.polling_options.run_polling_timeout. Happens on long-running runs (complex tool use, large outputs), slow backend, or a polling interval/time budget misconfiguration in RunPollingOptions.

Common situations: Default run_polling_timeout too short for heavy multi-step tool-calling runs; network latency to OpenAI inflating each retrieve round-trip; backend slowness during peak load; RunPollingOptions misconfigured with a tiny timeout; runs that legitimately need many tool invocations.

Understand the failure class

Related errors

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