microsoft/semantic-kernel · error · TimeoutException

Agent did not reach status {status} within the specified tim

Error message

Agent did not reach status {status} within the specified time.

What it means

Thrown after a bounded polling loop that repeatedly calls GetAgentAsync waiting for an agent to reach a target AgentStatus (e.g., PREPARED). The loop runs `maxAttempts` times with a fixed `interval` (in seconds) delay between checks. If the status never matches within the budgeted attempts, a TimeoutException is raised. This is used after agent creation or updates that trigger an asynchronous preparation step.

Source

Thrown at dotnet/src/Agents/Bedrock/Extensions/BedrockAgentExtensions.cs:278

        Amazon.BedrockAgent.Model.Agent agent,
        AgentStatus status,
        int interval = 2,
        int maxAttempts = 5,
        CancellationToken cancellationToken = default)
    {
        for (var i = 0; i < maxAttempts; i++)
        {
            var getAgentResponse = await client.GetAgentAsync(new() { AgentId = agent.AgentId }, cancellationToken).ConfigureAwait(false);

            if (getAgentResponse.Agent.AgentStatus == status)
            {
                return getAgentResponse.Agent;
            }

            await Task.Delay(interval * 1000, cancellationToken).ConfigureAwait(false);
        }

        throw new TimeoutException($"Agent did not reach status {status} within the specified time.");
    }
}

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Increase the maxAttempts and/or interval parameters passed to the wait method to allow more time for preparation.
2. Check the agent's actual current status via GetAgentAsync — if it is FAILED, fix the underlying configuration rather than waiting longer.
3. Verify the agent's action groups, knowledge bases, and model ID are correctly configured so preparation can complete.
4. If this is in CI/automated flow, raise the timeout budget or poll status separately and handle FAILED explicitly.

Example fix

// before
await agent.WaitForAgentStatusAsync(AgentStatus.Prepared, maxAttempts: 30, interval: 2, cancellationToken);

// after — more time + explicit failure handling
var status = await GetAgentStatusSafelyAsync(agent);
if (status == AgentStatus.Failed) throw new InvalidOperationException("Agent preparation failed; check configuration.");
await agent.WaitForAgentStatusAsync(AgentStatus.Prepared, maxAttempts: 120, interval: 5, cancellationToken);

// Check current status first; bail early if already failed
var current = await client.GetAgentAsync(new() { AgentId = agent.AgentId }, cancellationToken);
if (current.Agent.AgentStatus == AgentStatus.Failed)
    throw new InvalidOperationException("Agent is in FAILED status; will never reach target.");

static bool IsTerminalFailure(AgentStatus s) => s == AgentStatus.Failed;

try
{
    await agent.WaitForAgentStatusAsync(AgentStatus.Prepared, maxAttempts: 120, interval: 5, cancellationToken);
}
catch (TimeoutException ex)
{
    var s = await client.GetAgentAsync(new() { AgentId = agent.AgentId });
    logger.LogError("Agent stuck at {Status} after polling. {Msg}", s.Agent.AgentStatus, ex.Message);
    throw;
}

When it happens

Trigger: Calling the WaitForAgentStatusAsync (or similarly named) extension after creating/updating a Bedrock agent, when the agent remains in PREPARING or another transitional state longer than maxAttempts * interval seconds. Common when the agent's knowledge base or action groups are large, causing slow preparation.

Common situations: Default polling budget too small for agents with large knowledge bases; AWS-side preparation delays; the agent stuck in a FAILED status (never reaches the target); incorrect target status passed.

Related errors

• Message role must be either Assistant or User.
• runtimeClient
• The thread could not be created due to an error response fro
• The thread could not be deleted due to an error response fro
• Failed to invoke agent. Status code: {invokeAgentResponse.Ht

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