AWS bedrock-agentcore documentation change
Summary
Added new troubleshooting section 'My idle sessions are not being released and I am exhausting my session quota' and updated session management documentation. Clarified ping response requirements for session timeout handling.
Security assessment
The changes address operational issues with session management and resource exhaustion, not security vulnerabilities. The updates focus on proper implementation of ping responses to prevent session quota exhaustion, which is a reliability concern rather than a security flaw. No evidence of security vulnerability remediation is present.
Diff
diff --git a/bedrock-agentcore/latest/devguide/runtime-troubleshooting.md b/bedrock-agentcore/latest/devguide/runtime-troubleshooting.md index 44eb9405c..74d38a469 100644 --- a//bedrock-agentcore/latest/devguide/runtime-troubleshooting.md +++ b//bedrock-agentcore/latest/devguide/runtime-troubleshooting.md @@ -7 +7 @@ -My agent invocations fail with 504 Gateway Timeout errorsMy Docker build fails with "403 Forbidden" when pulling Python base imagesI get "Unknown service: 'bedrock-agent-core-runtime'" error when using boto3I get "AccessDeniedException" when trying to create an Amazon Bedrock AgentCore RuntimeMy Docker build fails with "exec /bin/sh: exec format error"What are the requirements for Docker containers used with Amazon Bedrock AgentCore Runtime?My long-running tool gets interrupted after 15 minutesHow do I access the runtimeSessionId in my agent code for tagging or grouping resources?I have RuntimeClientError (403) issuesI have missing or empty CloudWatch LogsI have payload format issuesI need help understanding HTTP error codesI need recommendations for testing my agentI need help debugging container issuesI need help troubleshooting MCP protocol agentsI need help troubleshooting bidirectional streaming using WebSocketMy code changes aren’t reflected in existing sessionsSpans are missing when my runtime is invoked from a Lambda functionMy S3 Files or EFS mount fails with "Access denied"My S3 Files or EFS mount fails with "ResourceNotFound"My S3 Files or EFS mount times outI get "Permission Denied" when writing to my mounted filesystemMy container fails to start with HTTP 424 error on high-layer imagesBest practices +My agent invocations fail with 504 Gateway Timeout errorsMy Docker build fails with "403 Forbidden" when pulling Python base imagesI get "Unknown service: 'bedrock-agent-core-runtime'" error when using boto3I get "AccessDeniedException" when trying to create an Amazon Bedrock AgentCore RuntimeMy Docker build fails with "exec /bin/sh: exec format error"What are the requirements for Docker containers used with Amazon Bedrock AgentCore Runtime?My long-running tool gets interrupted after 15 minutesMy idle sessions are not being released and I am exhausting my session quotaHow do I access the runtimeSessionId in my agent code for tagging or grouping resources?I have RuntimeClientError (403) issuesI have missing or empty CloudWatch LogsI have payload format issuesI need help understanding HTTP error codesI need recommendations for testing my agentI need help debugging container issuesI need help troubleshooting MCP protocol agentsI need help troubleshooting bidirectional streaming using WebSocketMy code changes aren’t reflected in existing sessionsSpans are missing when my runtime is invoked from a Lambda functionMy S3 Files or EFS mount fails with "Access denied"My S3 Files or EFS mount fails with "ResourceNotFound"My S3 Files or EFS mount times outI get "Permission Denied" when writing to my mounted filesystemMy container fails to start with HTTP 424 error on high-layer imagesBest practices @@ -28,0 +29,2 @@ This troubleshooting topic helps you identify and resolve common issues when wor + * My idle sessions are not being released and I am exhausting my session quota + @@ -161 +163,12 @@ For information, see [Handle asynchronous and long running agents with Amazon Be -**Why this happens:** Amazon Bedrock AgentCore automatically terminates sessions after 15 minutes of inactivity. The platform determines activity based on both the `status` field **and** the `time_of_last_update` field in the `/ping` response. If `time_of_last_update` is missing, the idle timeout fires regardless of the status value. +**Why this happens:** Amazon Bedrock AgentCore automatically terminates sessions after 15 minutes of inactivity. The platform determines activity from the `/ping` response: a session reporting `HealthyBusy` is kept alive, while a session reporting `Healthy` is treated as idle-eligible and its idle time is measured from when the `status` last changed (see the `time_of_last_update` field below). + +**Solution:** Ensure your `/ping` endpoint returns `HealthyBusy` while background work is in progress: + + + {"status": "HealthyBusy"} + +If you are using the Bedrock AgentCore SDK, the ping response is handled automatically. For custom implementations, ensure your ping handler returns `HealthyBusy` while processing. + +## My idle sessions are not being released and I am exhausting my session quota + +**When this occurs:** Session count climbs continuously under load and sessions are not released after the idle timeout (for example, `ServiceQuotaExceededException` / `maxVms` errors during a burst of invocations), even though each session is idle. @@ -163 +176 @@ For information, see [Handle asynchronous and long running agents with Amazon Be -**Solution:** Ensure your `/ping` endpoint returns both required fields: +**Why this happens:** When a session reports `Healthy`, the platform measures how long it has been idle from the `time_of_last_update` field in your `/ping` response, which must reflect when the `status` last changed. If your ping handler sets `time_of_last_update` to the current time on **every** ping, the reported idle time keeps resetting, which prevents the idle timeout from firing. Sessions then live until `MaxLifetime` and can exhaust your session quota. @@ -164,0 +178 @@ For information, see [Handle asynchronous and long running agents with Amazon Be +**Solution:** Update `time_of_last_update` only when the `status` actually changes, or omit it entirely so the platform tracks status changes on its own: @@ -166 +179,0 @@ For information, see [Handle asynchronous and long running agents with Amazon Be - {"status": "HealthyBusy", "time_of_last_update": 1715000000} @@ -168 +181 @@ For information, see [Handle asynchronous and long running agents with Amazon Be -Where `time_of_last_update` is a Unix timestamp (seconds) that updates whenever the status changes. If you are using the Bedrock AgentCore SDK, this is handled automatically. For custom implementations, ensure your ping handler includes both fields. + {"status": "Healthy"} @@ -170 +183 @@ Where `time_of_last_update` is a Unix timestamp (seconds) that updates whenever -**Example solution:** Implement ping handlers with HEALTHY_BUSY status for async tasks: +If you are using the Bedrock AgentCore SDK, upgrade to the latest version, where the ping response is handled correctly. As a stopgap, calling `StopRuntimeSession` releases stuck sessions.