microsoft/semantic-kernel · error · KernelException

Agent Failure - Run terminated: {run.Status} [{run.Id}]: {ru

Error message

Agent Failure - Run terminated: {run.Status} [{run.Id}]: {run.LastError?.Message ?? "Unknown"}

What it means

Thrown inside the non-streaming InvokeAsync poll loop (AgentThreadActions) when, after polling, the Azure AI agent run reached one of the failure statuses: Cancelled, Expired, or Failed (the s_failureStatuses set). The message includes the run status, run Id, and the LastError message (or 'Unknown'). This is a runtime/agent-execution failure, not a configuration error.

Source

Thrown at dotnet/src/Agents/AzureAI/Internal/AgentThreadActions.cs:181

        FunctionCallsProcessor functionProcessor = new(logger);
        // This matches current behavior.  Will be configurable upon integrating with `FunctionChoice` (#6795/#5200)
        FunctionChoiceBehaviorOptions functionOptions = new() { AllowConcurrentInvocation = true, AllowParallelCalls = true };

        // Evaluate status and process steps and messages, as encountered.
        HashSet<string> processedStepIds = [];
        Dictionary<string, FunctionResultContent> functionSteps = [];
        do
        {
            // Check for cancellation
            cancellationToken.ThrowIfCancellationRequested();

            // Poll run and steps until actionable
            await PollRunStatusAsync().ConfigureAwait(false);

            // Is in terminal state?
            if (s_failureStatuses.Contains(run.Status))
            {
                throw new KernelException($"Agent Failure - Run terminated: {run.Status} [{run.Id}]: {run.LastError?.Message ?? "Unknown"}");
            }

            List<RunStep> steps = [];
            await foreach (var step in client.GetStepsAsync(run, cancellationToken: cancellationToken).ConfigureAwait(false))
            {
                steps.Add(step);
            }

            // Is tool action required?
            if (run.Status == RunStatus.RequiresAction)
            {
                logger.LogAzureAIAgentProcessingRunSteps(nameof(InvokeAsync), run.Id, threadId);

                // Execute functions in parallel and post results at once.
                FunctionCallContent[] functionCalls = [.. steps.SelectMany(step => ParseFunctionStep(agent, step))];
                if (functionCalls.Length > 0)
                {
                    // Emit function-call content

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Inspect the run.LastError.Message in the exception to identify the upstream cause.
2. For content-filter failures, revise the prompt/input content.
3. For quota/rate-limit failures, retry with backoff and check subscription usage.
4. For Expired, reduce run duration or re-invoke; for Cancelled, check whether a cancellation token was triggered.
5. Correlate using the run.Id with Azure service logs/diagnostics.

try { await agent.InvokeAsync(messages, thread, ct); }
catch (KernelException ex) when (ex.Message.Contains("Run terminated"))
{
    // ex.Message contains run.Status, run.Id, and LastError.Message
    logger.LogError("Azure AI run failed: {Msg}", ex.Message);
    // apply backoff/retry for transient statuses, or surface content-filter errors
}

When it happens

Trigger: An assistant run on the Azure AI service transitions to RunStatus.Failed, RunStatus.Cancelled, or RunStatus.Expired during invocation. Common upstream causes: content-filter trigger, token/quota exhaustion, model error, the run being explicitly cancelled, or the run expiring after inactivity.

Common situations: Prompt content tripped the content filter; Azure OpenAI quota hit; long-running run expired; concurrent cancellation token fired but the service reported Cancelled; transient backend error surfaced as Failed.

Related errors

• Agent Failure - Run not created for thread: ${threadId}
• Failed to search the collection.
• Response failed
• {type(agent)} service failed to complete the request
• {type(self)} service failed to complete the prompt

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