AWS bedrock-agentcore high security documentation change
Summary
Restructured troubleshooting guide with specific error scenarios and solutions, added documentation for common runtime errors (504s, 403s, AccessDeniedException), Docker requirements, session ID usage, and testing recommendations
Security assessment
Added documentation for 'AccessDeniedException' resolution explicitly addresses security-related permissions configuration ('bedrock-agentcore:CreateAgentRuntime' policy requirement and execution role trust relationships). This directly impacts security by preventing unauthorized access to agent runtime creation.
Diff
diff --git a/bedrock-agentcore/latest/devguide/runtime-troubleshooting.md b/bedrock-agentcore/latest/devguide/runtime-troubleshooting.md index 662590214..e312ba998 100644 --- a//bedrock-agentcore/latest/devguide/runtime-troubleshooting.md +++ b//bedrock-agentcore/latest/devguide/runtime-troubleshooting.md @@ -5 +5 @@ -Common issues and solutionsAdvanced troubleshootingCommon best 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 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 agentsBest practices @@ -15 +15 @@ This troubleshooting topic helps you identify and resolve common issues when wor - * Common issues and solutions + * My agent invocations fail with 504 Gateway Timeout errors @@ -17 +17 @@ This troubleshooting topic helps you identify and resolve common issues when wor - * Advanced troubleshooting + * My Docker build fails with "403 Forbidden" when pulling Python base images @@ -19 +19 @@ This troubleshooting topic helps you identify and resolve common issues when wor - * Common best practices + * I get "Unknown service: 'bedrock-agent-core-runtime'" error when using boto3 @@ -20,0 +21 @@ This troubleshooting topic helps you identify and resolve common issues when wor + * I get "AccessDeniedException" when trying to create an Amazon Bedrock AgentCore Runtime @@ -21,0 +23 @@ This troubleshooting topic helps you identify and resolve common issues when wor + * My Docker build fails with "exec /bin/sh: exec format error" @@ -22,0 +25 @@ This troubleshooting topic helps you identify and resolve common issues when wor + * What are the requirements for Docker containers used with Amazon Bedrock AgentCore Runtime? @@ -24 +27 @@ This troubleshooting topic helps you identify and resolve common issues when wor -## Common issues and solutions + * My long-running tool gets interrupted after 15 minutes @@ -26 +29,187 @@ This troubleshooting topic helps you identify and resolve common issues when wor -### RuntimeClientError (403) issues + * How do I access the runtimeSessionId in my agent code for tagging or grouping resources? + + * I have RuntimeClientError (403) issues + + * I have missing or empty CloudWatch Logs + + * I have payload format issues + + * I need help understanding HTTP error codes + + * I need recommendations for testing my agent + + * I need help debugging container issues + + * I need help troubleshooting MCP protocol agents + + * Best practices + + + + +## My agent invocations fail with 504 Gateway Timeout errors + +**When this occurs:** During agent invocation via SDK or console + +**Why this happens:** Multiple factors can prevent your agent from responding within the timeout period + +Several factors can cause this: + + * **Container Issues:** Make sure your Docker image exposes port 8080 and has the `/invocations` path + + * **ARM64 Compatibility:** Currently your container must be ARM64 compatible + + * **Retry Logic:** Review retry mechanisms for handling transient issues + + + + +## My Docker build fails with "403 Forbidden" when pulling Python base images + +**When this occurs:** During `docker build` or `docker run` when using `public.ecr.aws` base images + +**Why this happens:** ECR Public authentication issues — expired or missing authentication is a common issue. + +**Solution:** Either login to ECR Public or logout completely: + + + # Option 1: Login to ECR Public + aws ecr-public get-login-password --region us-east-1 | docker login --username AWS --password-stdin public.ecr.aws + + # Option 2: Logout (recommended for avoiding token expiration) + docker logout public.ecr.aws + + # Option 3: Use Docker Hub directly in Dockerfile + FROM python:3.10-slim + # instead of public.ecr.aws/docker/library/python:3.10-slim + + +## I get "Unknown service: 'bedrock-agent-core-runtime'" error when using boto3 + +**When this occurs:** When invoking Amazon Bedrock AgentCore APIs using boto3 SDK + +**Why this happens:** Outdated boto3 library — common issue as most installations don't have latest SDK + +**Solution:** Update to latest boto3 and botocore versions: + + + pip install --upgrade boto3 botocore + + # Minimum versions: boto3 1.39.8+, botocore 1.33.8+ + + +## I get "AccessDeniedException" when trying to create an Amazon Bedrock AgentCore Runtime + +**When this occurs:** During agent creation via console, SDK, or CLI + +**Why this happens:** Either your user lacks permissions, or the execution role isn't properly configured for Amazon Bedrock AgentCore + +**Solution:** Several factors can cause this: + + * **Missing permissions for the caller.** Make sure that the caller's credentials has `bedrock-agentcore:CreateAgentRuntime`. + + * **Execution Role cannot be assumed by Bedrock Amazon Bedrock AgentCore.** Make sure that the execution role follows this guidance on [permissions for Amazon Bedrock AgentCore Runtime execution role](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-permissions.html). + + + + +## My Docker build fails with "exec /bin/sh: exec format error" + +**When this occurs:** When building containers for Amazon Bedrock AgentCore deployment + +**Why this happens:** Building ARM64 containers on x86 systems without proper cross-platform setup + +**Solution:** Build ARM64 compatible containers. You can consider using [buildx](https://github.com/docker/buildx) for cross-platform builds. Alternatively, you can use CodeBuild. For example code, see the [Amazon Bedrock AgentCore Samples](https://github.com/awslabs/amazon-bedrock-agentcore-samples/). + +## What are the requirements for Docker containers used with Amazon Bedrock AgentCore Runtime? + +Review [Amazon Bedrock AgentCore Runtime requirements](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-service-contract.html) for full details. + +In summary, your Docker container must meet these requirements: + + * **Port:** Expose port 8080 (additional ports will be supported soon) + + * **Endpoint:** Must have `/invocations` path available + + * **Architecture:** Must be ARM64 compatible + + * **Response:** Should handle the expected payload format + + + + +## My long-running tool gets interrupted after 15 minutes + +For information, see [Handle asynchronous and long running agents with Amazon Bedrock Amazon Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-long-run.html) for full details. + +**When this occurs:** During long-running agent operations or complex workflows + +**Why this happens:** Amazon Bedrock AgentCore automatically terminates sessions after 15 minutes of inactivity + +**Example solution:** Implement ping handlers with HEALTHY_BUSY status for async tasks: + + + import asyncio + from bedrock_agentcore.runtime import BedrockAgentCoreApp + + app = BedrockAgentCoreApp() + + @app.entrypoint + async def long_running_agent(payload, context): + # For long-running tasks, create async task with ping handler + async def ping_handler(): + while task_running: + await context.ping(status="HEALTHY_BUSY") + await asyncio.sleep(30) # Ping every 30 seconds + + # Start ping handler + ping_task = asyncio.create_task(ping_handler()) + + # Your long-running work here + result = await perform_long_task() + + # Clean up + ping_task.cancel() + return result + + +## How do I access the runtimeSessionId in my agent code for tagging or grouping resources? + +**When this applies:** You want to group, tag, or trace resources (e.g., S3 objects, logs) by the current agent runtime session. + +**Solutions:** + + * If you're using the Bedrock Agents SDK, use `context.session_id`. + + * If you're building a custom runtime server, extract it from the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` HTTP header. + + + + +**Solution 1:** For agents using the Bedrock Amazon Bedrock AgentCore SDK, use `context.session_id` from your agent entrypoint + + + @app.entrypoint + def my_agent(payload, context): + session_id = context.session_id + + # Use session_id for S3 object tagging/organization + s3_client = boto3.client('s3') + s3_client.put_object( + Bucket='my-bucket', + Key=f'agent-outputs/{session_id}/output.json', + Body=json.dumps(result),