Run your agent on Amazon Bedrock AgentCore Runtime

This tutorial deploys an AgentCore Runtime that runs codex exec-server for BMA. BMA activates the Runtime for agent work. You do not attach an exec server manually.

What the example creates

The CDK application creates an ARM64 Runtime, its execution role, a BMA client role, and an optional session role. It also creates:

The Runtime's network rules allow HTTPS egress and NFS connections to the example's S3 Files mount targets. See security for the roles and storage permissions.

These resources can incur charges until you remove them. Use a development account and retain only the test data that you need.

Step 1: Prepare the container build

Complete the prerequisites. Save the Linux ARM64 Codex executable at bin/codex in the bundle root, and ensure that Docker is running with ARM64 build support.

From the bundle root:

cd acr
export AWS_PROFILE=my-deployment-profile
export AWS_REGION=us-east-1
export AWS_DEFAULT_REGION="$AWS_REGION"
export BMA_REGION="$AWS_REGION"
export BMA_ENDPOINT="https://bedrock-mantle.${BMA_REGION}.api.aws"
npm ci
npx cdk bootstrap

Step 2: Deploy

npm run deploy -- \
  --parameters BmaRegion="$BMA_REGION" \
  --parameters BmaEndpoint="$BMA_ENDPOINT"

If the session role already exists, add --parameters ManageCustomerInferenceRole=false. For example, use that option when the self-hosted stack owns the role.

Wait for the stack to reach CREATE_COMPLETE or UPDATE_COMPLETE. The outputs include RuntimeArn, SkillsBucketName, OutputsBucketName, BmaAccessRoleArn, and CustomerInferenceRoleArn.

The Runtime and its storage must be available in the deployment Region. Use Availability Zones enabled for your account. See troubleshooting if deployment fails while creating networking or storage resources.

Step 3: Create a BMA session

Select your BMA client profile:

export AWS_PROFILE=my-bma-client-profile
./scripts/bma/0.create-session.sh

The script obtains the Runtime ARN from AcBmaStack. You can instead set BMA_AGENTCORE_RUNTIME_ARN explicitly, such as when using a Runtime that another stack manages.

The session's environment uses type: "aws_bedrock_agentcore". It identifies the Runtime ARN, a Runtime qualifier, a workspace directory, and capability directories. The default qualifier is DEFAULT.

Step 4: Run the sample skill

./scripts/bma/2.submit-turn.sh "Run the hello-bma skill."
./scripts/bma/3.read-result.sh

BMA invokes the Runtime adapter, which prepares storage and starts the exec server. The sample skill verifies that its files reached the execution environment. It reads the skill instructions and lists the available skills.

You can inspect the BMA session while work is running:

./scripts/bma/1.status.sh

The BMA session role authorizes Runtime activation and cleanup. The Runtime execution role authorizes the container's registration and connection to BMA. The adapter uses the Runtime role and rejects requests that attempt to supply alternative AWS credentials.

Workspace, skills, and outputs

The adapter copies the mounted skills into the workspace when it activates. Use skills and tools to add your own skill files.

To generate a file:

./scripts/bma/2.submit-turn.sh "Write the text BMA_OUTPUT_VERIFIED to /mnt/output/verification.txt, then read it back."
./scripts/bma/3.read-result.sh

Retrieve the bucket name and the file:

OUTPUTS_BUCKET=$(aws cloudformation describe-stacks \
  --stack-name AcBmaStack --region "$BMA_REGION" \
  --query "Stacks[0].Outputs[?OutputKey=='OutputsBucketName'].OutputValue | [0]" \
  --output text)
aws s3 cp "s3://${OUTPUTS_BUCKET}/verification.txt" ./verification.txt

S3 Files synchronization is asynchronous. A completed agent write can precede the object's availability through the S3 API. Retry the download after synchronization if the object is not yet available.

Runtime lifecycle

The example sets both the idle timeout and maximum compute lifetime to 28,800 seconds (eight hours). Keep these settings for the preview example. The adapter also supports bounded turn leases so active work can report busy health to AgentCore.

A maximum compute lifetime still applies while a turn is busy. Compute replacement does not preserve running processes or sockets. The adapter stores connection state in session storage and uses it when replacement compute is activated for the same Runtime session.

Session storage and the S3-backed files have different lifecycles. Review AgentCore Runtime lifecycle settings and filesystem configuration before relying on persistence across compute replacement or Runtime updates.

Step 5: Clean up

./scripts/bma/4.delete-session.sh
export AWS_PROFILE=my-deployment-profile
npm run destroy

Download any outputs that you want to keep first. The sample stack uses destructive removal policies for its storage resources, including automatic deletion of objects. See cleanup when both example stacks share the session role.