AWS CDK Hotswap Deployments Now Support Bedrock AgentCore Runtime

AWS CDK's hotswap deployments now support Bedrock AgentCore Runtime.

What are hotswap deployments?

Hotswap deployments refer to deployments using the --hotswap option with the cdk deploy command. Instead of updating the CloudFormation stack, this feature directly updates the changed resources using the AWS SDK internally in CDK, significantly reducing deployment time.

npx cdk deploy --hotswap

AWS CDK generates CloudFormation templates from CDK code by executing an internal process called "synthesis". Then, it deploys CloudFormation stacks based on those templates.

However, even when only application-side files such as Lambda function code or container images are changed, CDK still requires CloudFormation stack deployment, which takes time.

Since application code changes more frequently than infrastructure definitions, the wait time caused by CloudFormation deployment for each code change can degrade the development experience.

To address such cases, CDK provides the hotswap deployment feature. When using hotswap deployments, changes to application-side files such as Lambda function code or container images can be directly updated to resources without performing CloudFormation deployment processing. This significantly reduces deployment time and accelerates the development cycle.

However, this hotswap feature only supports specific changes to certain resources, such as Lambda function code assets and ECS image assets. For details on supported resources, please refer to the official documentation.

Developer Guide: cdk deploy

How hotswap deployments work

In hotswap deployment, synthesis processing is first executed to generate a CloudFormation template based on the implemented CDK code.

Next, it obtains the differences between that template and the template of the actually deployed stack.

If the properties of the resources with differences are hotswap-compatible, it retrieves the current configuration values using AWS SDK Get APIs. Then, combining the information from the newly generated template with the information obtained from the AWS SDK, it finally updates the differences using AWS SDK Update APIs.

Hotswap support for Bedrock AgentCore Runtime

AWS CDK CLI v2.1102.0 added hotswap deployment support for Bedrock AgentCore Runtime.

Actually, I contributed this feature to the AWS CDK.

feat(cli): support hotswap for AWS::BedrockAgentCore::Runtime

This was one of the most challenging CDK contributions I've ever done. I particularly struggled with aspects unrelated to CDK's features and implementation, such as dependencies and integration tests.

By the way, CDK is divided into the Construct library repository and the CLI repository, and this feature is implemented on the CLI repository side.

How to use hotswap deployments with Bedrock AgentCore Runtime

Bedrock AgentCore Runtime supports container images (ECR) or code files (S3) as runtime sources. As of January 2026, S3 only supports Python.

The hotswap deployment introduced this time supports both ECR and S3 updates.

Version

Please update the aws-cdk version to v2.1102.0 or later.

NOTE: aws-cdk is the CDK CLI, and aws-cdk-lib is the Construct library. The hotswap feature this time is a CLI-side feature.

NOTE: Make sure aws-cdk-lib and @aws-cdk/aws-bedrock-agentcore-alpha are also installed.

Example package.json:

"devDependencies": {
  // ...,
  // ...,
  "aws-cdk": "2.1102.0"
},
"dependencies": {
  "@aws-cdk/aws-bedrock-agentcore-alpha": "^2.235.0-alpha.0",
  "aws-cdk-lib": "2.235.0",

ECR source implementation example

First, here's an implementation example using container images.

The AgentRuntimeArtifact.fromAsset method builds the local Dockerfile, automatically pushes it to a CDK-managed ECR, and allows you to specify it as the Runtime source.

NOTE: You need to prepare application code and Dockerfile in the ArtifactDirectory directory in advance, but this is omitted in this article.

const runtimeArtifact = AgentRuntimeArtifact.fromAsset(path.join(__dirname, 'ArtifactDirectory'));

const runtimeECR = new Runtime(this, 'RuntimeECR', {
  runtimeName: 'runtime_ecr',
  description: 'Runtime',
  agentRuntimeArtifact: runtimeArtifact,
  environmentVariables: {
    LOG_LEVEL: 'INFO',
  },
});

S3 source implementation example

Next, here's an implementation example using code files.

First, upload local code files to S3 using the Asset construct from the aws-cdk-lib/aws-s3-assets module.

Then, you can specify that S3 object as the Runtime source using the AgentRuntimeArtifact.fromS3 method.

const asset = new Asset(this, 'CodeAsset', {
  path: path.join(__dirname, 'ArtifactDirectory'),
});

const runtimeArtifact = AgentRuntimeArtifact.fromS3(
  {
    bucketName: asset.s3BucketName,
    objectKey: asset.s3ObjectKey,
  },
  AgentCoreRuntime.PYTHON_3_13,
  ['app.py'],
);

const runtimeS3 = new Runtime(this, 'RuntimeS3', {
  runtimeName: 'runtime_s3',
  agentRuntimeArtifact: runtimeArtifact,
  description: 'Runtime',
  environmentVariables: {
    LOG_LEVEL: 'INFO',
  },
});

Executing hotswap deployment

After completing the CDK implementation as described above, first deploy without the --hotswap option.

NOTE: This example shows the case using S3 source CDK code, but the same applies to ECR source.

npx cdk deploy

Next, make changes only to the application code, not the CDK code.

Then, before performing hotswap deployment, try running the cdk diff command.

npx cdk diff

You should see differences in the AgentRuntimeArtifact of the Runtime resource, as shown below. Since AgentRuntimeArtifact is a hotswap-supported property, you can execute hotswap deployment.

[~] AWS::BedrockAgentCore::Runtime RuntimeS3 RuntimeS39E2E9695
 └─ [~] AgentRuntimeArtifact
     └─ [~] .CodeConfiguration:
         └─ [~] .Code:
             └─ [~] .S3:
                 └─ [~] .Prefix:
                     ├─ [-] a18dede8bbfbfc4db1d3a434052cab2fe8ea82c01a945a1d66127d63b5523299.zip
                     └─ [+] f2793197e0247f4f89ebcf16787e78399b4de6c255ff8e57d7d1766ac38d4113.zip

Then, execute deployment with the --hotswap option.

npx cdk deploy --hotswap

If a message like hotswapped! is displayed as shown below, the hotswap deployment has succeeded. The deployment time should be significantly reduced compared to when not using hotswap deployment.

(  Synthesis time: 3.45s

� The --hotswap and --hotswap-fallback flags deliberately introduce CloudFormation drift to speed up deployments
� They should only be used for development - never use them for your production Stacks!

CdkSampleStack: start: Building CdkSampleStack Template
CdkSampleStack: success: Built CdkSampleStack Template
CdkSampleStack: start: Publishing CdkSampleStack Template (current_account-us-east-1-2ad80d58)
CdkSampleStack: success: Published CdkSampleStack Template (current_account-us-east-1-2ad80d58)
CdkSampleStack: deploying... [1/1]

( hotswapping resources:
   ( AWS::BedrockAgentCore::Runtime 'runtime_s3-iImLoZB224'
   ( AWS::BedrockAgentCore::Runtime 'runtime_s3-iImLoZB224' hotswapped!

Bedrock AgentCore Runtime properties that support hotswap

The following properties of Bedrock AgentCore Runtime support hotswap deployment:

In other words, hotswap deployment is only executed when these properties are changed.

• agentRuntimeArtifact
• description
• environmentVariables

If changes include other properties, only changes to the above properties are applied with hotswap deployment, and changes to other properties are ignored.

Using the --hotswap-fallback option allows you to fall back to a full CloudFormation deployment.

npx cdk deploy --hotswap-fallback

By the way, I aligned these three properties with Lambda's hotswap-supported properties.

Internally, the target properties can be increased as much as desired, but targeting properties that don't change frequently doesn't provide much benefit, so I simply narrowed it down to the minimum necessary properties, just like Lambda.

If there are properties you'd like to be targeted, please let me know and I'll consider changes.

Precautions for hotswap deployments

Never use in production environments

While this seemingly convenient hotswap deployment feature is useful, it must not be used in production environments.

This is because hotswap deployment intentionally introduces drift (inconsistency between the template and actual resource state) to the CloudFormation stack, which can cause unexpected behavior when trying to update the CloudFormation stack later.

Therefore, use hotswap deployments to improve development speed in development environments.

Be aware of tokens

For example, when defining an S3 source using BucketDeployment and Source.asset() as shown below, hotswap doesn't work.

const bucket = new Bucket(this, 'CodeBucket');

// Not recommended (hotswap doesn't work)
const deployment = new aws_s3_deployment.BucketDeployment(this, 'Deploy', {
  sources: [aws_s3_deployment.Source.asset(path.join(__dirname, 'agent-code'))],
  destinationBucket: bucket,
  extract: false,
});

const agentRuntimeArtifact = AgentRuntimeArtifact.fromS3(
  {
    bucketName: bucket.bucketName,
    objectKey: cdk.Fn.select(0, deployment.objectKeys), // Token, resolved at deployment time
  },
  AgentCoreRuntime.PYTHON_3_13,
  ['app.py'],
);

The objectKey generated here is a token, which is information that is not resolved during synthesis but is resolved at deployment time. On the CloudFormation template, it is represented using functions like Fn::GetAtt or Ref.

In that case, even if you upload the changed code files, the property value specifying the S3 information of Runtime on the CloudFormation template remains a value using functions like Fn::GetAtt, and no difference occurs, so hotswap doesn't work. Therefore, please use the Asset construct as shown above.

"AgentRuntimeArtifact": {
  "CodeConfiguration": {
  "Code": {
    "S3": {
    "Bucket": {
      "Ref": "CodeBucketFF4C7AD6"
    },
    "Prefix": {
      "Fn::Select": [
      0,
      {
        "Fn::GetAtt": [
        "DeployCustomResource218AF6A4",
        "SourceObjectKeys"
        ]
      }
      ]
    }
    }
  },

If hotswap is not being executed, check whether it's a token.

Specifically, look at the CloudFormation template generated by CDK and check if it's something like Fn::GetAtt whose value doesn't change even when modified.

Making it more convenient

When using S3 as a source, it's tedious to manually call the Asset construct every time, right?

Actually, I've submitted a pull request to AWS CDK to address this.

feat(bedrock-agentcore-alpha): add fromCodeAsset method to create runtime artifact with local code assets

Once this is merged, you'll be able to simply specify the directory path of code files using the AgentRuntimeArtifact.fromCodeAsset method, and it will upload to S3 for you, as shown below.

const runtimeArtifact = agentcore.AgentRuntimeArtifact.fromCodeAsset({
  path: path.join(__dirname, 'ArtifactDirectory'),
  runtime: agentcore.AgentCoreRuntime.PYTHON_3_13,
  entrypoint: ['app.py'],
});

Conclusion

If there are any bugs, I'd appreciate it if you could let me know. I'll fix them immediately.