Build image

To run an agent on AWS Bedrock AgentCore, the image must be wrapped with the agent-proxy layer. The agent-proxy layer intercepts all outbound traffic of the agent to log the source, destination, and byte counts for observability and auditing purposes. If you created a managed gateway when you set up the AgentCore runtime, the agent-proxy layer additionally reroutes all outbound traffic through the gateway so that the gateway can enforce runtime authorization policies and facilitate communication between the agent and MCP servers that are also deployed to AgentCore.

To wrap the agent image with the agent-proxy layer, you use the arctl wrap-agent-image command. Note that your Dockerfile must meet the following requirements to be eligible for wrapping:

• The Dockerfile must set a real ENTRYPOINT or CMD. The image’s launch command is rewritten to start through the agent-proxy layer. If no launch command is set in your Dockerfile, the wrapping of the image fails.
• If the Dockerfile sets a non-root USER, that user must resolve from the image’s own /etc/passwd and /etc/group files. The agent-proxy layer preserves this user when it launches your agent, and fails to start if the identity does not resolve.
• Your agent must listen on the port that AWS Bedrock AgentCore forwards requests to, which is 9000 for the A2A protocol and 8080 if spec.source.protocol is set to HTTP in your agent definition. The agent-proxy layer forwards each inbound request to your agent on this same port.

AWS Bedrock AgentCore also only runs linux/arm64 images that it pulls from a private Amazon ECR repository in the same AWS account and region as your AgentCore runtime. Because of that, you must push the wrapped image to your Amazon ECR repository.

1. Create and run an agent on your local machine.

2. Create a private Amazon ECR repository for the agent image, if you don’t already have one. For more information, see Creating a private repository in the AWS documentation.

   aws ecr create-repository \
     --repository-name myagent \
     --region <region>

   Example output:

   {
     "repository": {
       "repositoryUri": "123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent",
       ...
     }
   }
   

3. Authenticate Docker to your ECR registry.

   aws ecr get-login-password --region <region> \
     | docker login --username AWS --password-stdin <account-id>.dkr.ecr.<region>.amazonaws.com

4. Build the linux/arm64 image and push it to the AWS ECR repository URI that you retrieved earlier. Make sure that your Dockerfile adheres to the requirements that were outlined earlier. The image that you create in this step serves as the base image for your agent. You later layer the agent-proxy on top of this image and also push the wrapped image to the same repository.

   Note

   AgentCore spins up the agent from the wrapped image that you create in a later step, not the base image that you create in this step. You can store the base image in a container registry of your choice. However, this guide assumes that you want to store the base image in the same repository as the wrapped image.

   arctl build myagent \
     --image 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest \
     --platform linux/arm64 \
     --push

   Example output:

   Building agent image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest
   ✓ Successfully built Docker image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest
   ✓ Pushed image: 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest
   

5. Wrap the pushed base image with the agent-proxy layer, and push the wrapped image to the same repository under a separate tag. AWS Bedrock AgentCore only pulls the wrapped image when deploying your agent runtime.

   arctl wrap-agent-image \
     --image 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:latest \
     --tag 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:wrapped \
     --platform linux/arm64 \
     --push

   Setting	Description
   --image	The agent image to wrap.
   --tag	The reference to assign to the wrapped image. Use a new tag so that the unwrapped image stays available too.
   --platform	The platform of the base image. Use linux/arm64 for AWS Bedrock AgentCore.
   --push	Push the wrapped image directly to the repository that you defined in the --tag option.

6. Update the spec.source.image field in your agent definition (agent.yaml) file to point to the wrapped image tag, such as 123456789012.dkr.ecr.us-east-1.amazonaws.com/myagent:wrapped.