microsoft/semantic-kernel · error · AgentInvokeException

Run failed with status: `{run.status}` for agent `{agent.nam

Error message

Run failed with status: `{run.status}` for agent `{agent.name}` and thread `{thread_id}` with error: {error_message} or incomplete details: {incomplete_details}

What it means

While polling a (non-streaming) assistant run, if run.status lands in error_message_states (e.g. failed, cancelled, expired, incomplete), the run is terminal and AgentInvokeException is raised. The message embeds agent name, thread id, run.last_error.message (if any) and run.incomplete_details.reason (if any) to aid diagnosis.

Source

Thrown at python/semantic_kernel/agents/open_ai/assistant_thread_actions.py:255

            **run_options,
        )

        processed_step_ids = set()
        function_steps: dict[str, "FunctionCallContent"] = {}

        while run.status != "completed":
            run = await cls._poll_run_status(
                agent=agent, run=run, thread_id=thread_id, polling_options=polling_options or agent.polling_options
            )

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

            # Check if function calling required
            if run.status == "requires_action":
                logger.debug(f"Run [{run.id}] requires action for agent `{agent.name}` and thread `{thread_id}`")
                fccs = get_function_call_contents(run, function_steps)
                if fccs:
                    logger.debug(
                        f"Yielding `generate_function_call_content` for agent `{agent.name}` and "
                        f"thread `{thread_id}`, visibility False"
                    )
                    yield False, generate_function_call_content(agent_name=agent.name, fccs=fccs)

                    from semantic_kernel.contents.chat_history import ChatHistory

                    chat_history = ChatHistory()

View on GitHub (pinned to c028a0c7dc)

Solutions

Read the embedded error_message (run.last_error) and incomplete_details to classify the failure precisely.
For 'incomplete' status, raise max_completion_tokens / max_prompt_tokens or reduce input size, then retry.
For transient failures (rate limit, server error), retry the invoke with exponential backoff.
Verify registered tool/function outputs are well-formed and fast to prevent server-side run failures.

Example fix

// before
run = await assistant.invoke(thread_id=tid)  # raises if run incomplete due to token cap

// after
from semantic_kernel.agents.open_ai import RunPollingOptions
agent.polling_options = RunPollingOptions()
agent.max_completion_tokens = 4096  # give the run room to finish
run = await assistant.invoke(thread_id=tid)

Defensive patterns

Strategy: retry

Try / catch

from semantic_kernel.exceptions import AgentInvokeException
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(stop=stop_after_attempt(4), wait=wait_exponential(), retry=retry_if_exception_type(AgentInvokeException))
async def invoke():
    try:
        return await assistant.invoke(thread_id=tid)
    except AgentInvokeException as e:
        if "incomplete" in str(e):
            raise  # not transient, fix token caps instead
        raise

Prevention

Set max_completion_tokens/max_prompt_tokens high enough for your workload.
Keep tool outputs small and fast to avoid server-side run failures.
Retry transient (rate-limit/5xx) failures with backoff; fix persistent ones.

When it happens

Trigger: The OpenAI run ends in a failing/terminal state: server-side failure, cancellation, expiry, or incompleteness (e.g. token/model limits hit). The poll loop detects the status and raises.

Common situations: Function/tool outputs that error server-side; rate limiting or quota exhaustion; a run left polling past its expiry; incomplete runs due to max completion tokens or max_prompt_tokens being too low; cancelled runs from dashboard/another client.

Related errors

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