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}

What it means

Streaming counterpart of the run-failure guard. While consuming the run event stream, a thread.run.failed event signals the run terminated abnormally; the code raises AgentInvokeException embedding agent name, thread id, and run.last_error.message (empty string if the API supplied none).

Source

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

                            for id in active_messages:
                                step: RunStep = active_messages[id]
                                message = await cls._retrieve_message(
                                    agent=agent,
                                    thread_id=thread_id,
                                    message_id=id,  # type: ignore
                                )

                                if message and message.content:
                                    content = generate_final_streaming_message_content(agent.name, message, step)
                                    if output_messages is not None:
                                        output_messages.append(content)
                        return
                    elif event.event == "thread.run.failed":
                        run = event.data  # type: ignore
                        error_message = ""
                        if run.last_error and run.last_error.message:
                            error_message = run.last_error.message
                        raise AgentInvokeException(
                            f"Run failed with status: `{run.status}` for agent `{agent.name}` and thread `{thread_id}` "
                            f"with error: {error_message}"
                        )
                else:
                    # If the inner loop completes without encountering a 'break', exit the outer loop
                    break

    @classmethod
    async def _handle_streaming_requires_action(
        cls: type[_T],
        agent_name: str,
        kernel: "Kernel",
        run: "Run",
        function_steps: dict[str, "FunctionCallContent"],
        arguments: KernelArguments,
        function_choice_behavior: FunctionChoiceBehavior | None = None,
        **kwargs: Any,
    ) -> FunctionActionResult | None:

View on GitHub (pinned to c028a0c7dc)

Solutions

Inspect the embedded error_message (run.last_error) to pinpoint the server-side cause.
For tool-output failures, validate FunctionResultContent payloads before streaming submission.
Retry the invoke with backoff for transient (rate-limit / 5xx) failures; restructure inputs for persistent ones.
Ensure no other client or process cancels/overwrites the run during streaming.

Example fix

// before
async for msg in assistant.invoke_stream(thread_id=tid):
    ...  # raises thread.run.failed mid-stream

// after
from tenacity import retry, stop_after_attempt, wait_exponential
@retry(stop=stop_after_attempt(3), wait=wait_exponential())
async def run_once():
    async for msg in assistant.invoke_stream(thread_id=tid):
        ...
await run_once()

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(3), wait=wait_exponential())
async def stream():
    async for msg in assistant.invoke_stream(thread_id=tid):
        yield msg
# wrap consumption; on AgentInvokeException inspect run.last_error via logs

Prevention

Validate FunctionResultContent payloads before submitting tool outputs.
Retry transient stream failures (rate-limit/5xx) with backoff.
Avoid concurrent run mutation/cancellation during streaming.

When it happens

Trigger: The OpenAI run fails during streaming — server-side error, tool-output submission failure, or a model error mid-stream — emitting thread.run.failed. The stream handler maps that event to this exception.

Common situations: Malformed tool outputs submitted via submit_tool_outputs_stream; rate limiting/quota hit mid-stream; model errors; concurrent modification/cancellation of the run from another client.

Related errors

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