feat(agentcore): add new properties for runtime, browser (#36003)

### Issue # (if applicable)

Add support for new properties in agentcore alpha package:

- Runtime: 
  - [Code Configuration](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-bedrockagentcore-runtime-codeconfiguration.html) (Direct code deployment)
  - [Lifecycle configuration](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-bedrockagentcore-runtime-lifecycleconfiguration.html)
  - [Request header configuration](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-bedrockagentcore-runtime-requestheaderconfiguration.html)
- Browser:
  - [Browser signing](https://docs.aws.amazon.com/AWSCloudFormation/latest/TemplateReference/aws-properties-bedrockagentcore-browsercustom-browsersigning.html)

Also fix a warning (@param userPoolClients) in JSDoc due to wrong param name (missing 's')

### Reason for this change

Supporting new features

### Description of changes

Adding support for new properties, not changing existing implementation

### Describe any new or updated permissions being added

Granting permissions on bucket when using code configuration as a runtime artifact

### Description of how you validated changes

unit tests, integration tests, manual tests

Example: 

- Deploying a runtime from a zip available in S3:

```ts
const agentArtifact = AgentRuntimeArtifact.fromS3({
      bucketName: 'XXXXXXXXXX',
      objectKey: 'deployment_package.zip',
}, AgentCoreRuntime.PYTHON_3_13, ['main.py']);

const runtime1 = new Runtime(this, 'MinimalRuntime', {
      runtimeName: 'minimal_runtime',
      agentRuntimeArtifact: agentArtifact,
      requestHeaderConfiguration: { allowList: ['X-Amzn-Bedrock-AgentCore-Runtime-Custom-H1'] },
      lifecycleConfiguration: {
        idleRuntimeSessionTimeout: Duration.minutes(10),
        maxLifetime: Duration.hours(4),
      },
});

    // Grant permission to invoke Bedrock models
   ...
```

<img width="1062" height="79" alt="image" src="https://github.com/user-attachments/assets/5af7a392-5d31-4e5a-b2c0-b3a2e7fd57b6" />

- Deploying a browser with signing enabled

```ts
new BrowserCustom(this, 'Browser', {
      browserCustomName: 'my-browser',
      description: 'Strands browser',
      browserSigning: BrowserSigning.ENABLED,
    });
```

<img width="1232" height="339" alt="Screenshot 2025-11-19 at 4 53 22 PM" src="https://github.com/user-attachments/assets/f9906ddb-ed37-4170-8cf9-6d8b08c92a2e" />


### Checklist
- [X] My code adheres to the [CONTRIBUTING GUIDE](https://github.com/aws/aws-cdk/blob/main/CONTRIBUTING.md) and [DESIGN GUIDELINES](https://github.com/aws/aws-cdk/blob/main/docs/DESIGN_GUIDELINES.md)

----

*By submitting this pull request, I confirm that my contribution is made under the terms of the Apache-2.0 license*

Author: krokoko

packages/@aws-cdk/aws-bedrock-agentcore-alpha/README.md

@@ -80,6 +80,7 @@ This construct library facilitates the deployment of Bedrock AgentCore primitive
     - [Creating a Runtime](#creating-a-runtime)
       - [Option 1: Use an existing image in ECR](#option-1-use-an-existing-image-in-ecr)
       - [Option 2: Use a local asset](#option-2-use-a-local-asset)
+      - [Option 3: Use direct code deployment](#option-3-use-direct-code-deployment)
     - [Granting Permissions to Invoke Bedrock Models or Inference Profiles](#granting-permissions-to-invoke-bedrock-models-or-inference-profiles)
     - [Runtime Versioning](#runtime-versioning)
       - [Managing Endpoints and Versions](#managing-endpoints-and-versions)
@@ -163,6 +164,8 @@ to production by simply updating the endpoint to point to the newer version.
 | `authorizerConfiguration` | `RuntimeAuthorizerConfiguration` | No | Authorizer configuration for the agent runtime. Use `RuntimeAuthorizerConfiguration` static methods to create configurations for IAM, Cognito, JWT, or OAuth authentication |
 | `environmentVariables` | `{ [key: string]: string }` | No | Environment variables for the agent runtime. Maximum 50 environment variables |
 | `tags` | `{ [key: string]: string }` | No | Tags for the agent runtime. A list of key:value pairs of tags to apply to this Runtime resource |
+| `lifecycleConfiguration` | LifecycleConfiguration | No | The life cycle configuration for the AgentCore Runtime. Defaults to 900 seconds (15 minutes) for idle, 28800 seconds (8 hours) for max life time |
+| `requestHeaderConfiguration` | RequestHeaderConfiguration | No | Configuration for HTTP request headers that will be passed through to the runtime. Defaults to no configuration |
 
 ### Runtime Endpoint Properties
 
@@ -180,7 +183,7 @@ to production by simply updating the endpoint to point to the newer version.
 
 Reference an image available within ECR.
 
-```typescript
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -201,7 +204,7 @@ Reference a local directory containing a Dockerfile.
 Images are built from a local Docker context directory (with a Dockerfile), uploaded to Amazon Elastic Container Registry (ECR)
 by the CDK toolkit,and can be naturally referenced in your CDK app.
 
-```typescript
+```typescript fixture=default
 const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromAsset(
   path.join(__dirname, "path to agent dockerfile directory")
 );
@@ -212,6 +215,40 @@ const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
 });
 ```
 
+#### Option 3: Use direct code deployment
+
+With the container deployment method, developers create a Dockerfile, build ARM-compatible containers, manage ECR repositories, and upload containers for code changes. This works well where container DevOps pipelines have already been established to automate deployments.
+
+However, customers looking for fully managed deployments can benefit from direct code deployment, which can significantly improve developer time and productivity. Direct code deployment provides a secure and scalable path forward for rapid prototyping agent capabilities to deploying production workloads at scale.
+
+With direct code deployment, developers create a zip archive of code and dependencies, upload to Amazon S3, and configure the bucket in the agent configuration. A ZIP archive containing Linux arm64 dependencies needs to be uploaded to S3 as a pre-requisite to Create Agent Runtime.
+
+For more information, please refer to the [documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-code-deploy.html).
+
+```typescript fixture=default
+// S3 bucket containing the agent core
+const codeBucket = new s3.Bucket(this, "AgentCode", {
+  bucketName: "my-code-bucket",
+  removalPolicy: RemovalPolicy.DESTROY, // For demo purposes
+});
+
+// the bucket above needs to contain the agent code
+
+const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromS3(
+  {
+    bucketName: codeBucket.bucketName,
+    objectKey: 'deployment_package.zip',
+  }, 
+  agentcore.AgentCoreRuntime.PYTHON_3_12, 
+  ['opentelemetry-instrument', 'main.py']
+);
+
+const runtimeInstance = new agentcore.Runtime(this, "MyAgentRuntime", {
+  runtimeName: "myAgent",
+  agentRuntimeArtifact: agentRuntimeArtifact,
+});
+```
+
 ### Granting Permissions to Invoke Bedrock Models or Inference Profiles
 
 To grant the runtime permissions to invoke Bedrock models or inference profiles:
@@ -254,7 +291,7 @@ the steps below to understand how to use versioning with runtime for controlled
 When you first create an agent runtime, AgentCore automatically creates Version 1 of your runtime. At this point, a DEFAULT endpoint is
 automatically created that points to Version 1. This DEFAULT endpoint serves as the main access point for your runtime.
 
-```ts
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -271,7 +308,7 @@ After the initial deployment, you can create additional endpoints for different
 endpoint that explicitly points to Version 1. This allows you to maintain stable access points for specific environments while keeping the
 flexibility to test newer versions elsewhere.
 
-```ts
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -296,7 +333,7 @@ configurations), AgentCore automatically creates a new version (Version 2). Upon
 - The DEFAULT endpoint automatically updates to point to Version 2
 - Any explicitly pinned endpoints (like the production endpoint) remain on their specified versions
 
-```ts
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -315,7 +352,7 @@ Once Version 2 exists, you can create a staging endpoint that points to the new
 new version in a controlled environment before promoting it to production. This separation ensures that production traffic continues
 to use the stable version while you validate the new version.
 
-```ts
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -338,7 +375,7 @@ const stagingEndpoint = runtime.addEndpoint("staging", {
 After thoroughly testing the new version through the staging endpoint, you can update the production endpoint to point to Version 2.
 This controlled promotion process ensures that you can validate changes before they affect production traffic.
 
-```ts
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -362,7 +399,7 @@ RuntimeEndpoint can also be created as a standalone resource.
 
 #### Example: Creating an endpoint for an existing runtime
 
-```typescript
+```typescript fixture=default
 // Reference an existing runtime by its ID
 const existingRuntimeId = "abc123-runtime-id"; // The ID of an existing runtime
 
@@ -387,7 +424,7 @@ IAM authentication is the default mode, when no authorizerConfiguration is set t
 
 To configure AWS Cognito User Pool authentication:
 
-```typescript
+```typescript fixture=default
 declare const userPool: cognito.UserPool;
 declare const userPoolClient: cognito.UserPoolClient;
 declare const anotherUserPoolClient: cognito.UserPoolClient;
@@ -411,7 +448,7 @@ const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
 
 To configure custom JWT authentication with your own OpenID Connect (OIDC) provider:
 
-```typescript
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -434,7 +471,7 @@ const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
 
 To configure OAuth 2.0 authentication:
 
-```typescript
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -463,7 +500,7 @@ The AgentCore Runtime supports two network modes for deployment:
 
 By default, runtimes are deployed in PUBLIC network mode, which provides internet access suitable for less sensitive or open-use scenarios:
 
-```typescript
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -481,7 +518,7 @@ const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
 
 For enhanced security and network isolation, you can deploy your runtime within a VPC:
 
-```typescript
+```typescript fixture=default
 const repository = new ecr.Repository(this, "TestRepository", {
   repositoryName: "test-agent-runtime",
 });
@@ -510,8 +547,7 @@ const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
 
 When using VPC mode, the Runtime implements `ec2.IConnectable`, allowing you to manage network access using the `connections` property:
 
-```typescript
-
+```typescript fixture=default
 const vpc = new ec2.Vpc(this, 'MyVpc', {
   maxAzs: 2,
 });
@@ -544,6 +580,58 @@ runtime.connections.allowTo(databaseSecurityGroup, ec2.Port.tcp(5432), 'Allow Po
 runtime.connections.allowToAnyIpv4(ec2.Port.tcp(443), 'Allow HTTPS outbound');
 ```
 
+### Other configuration
+
+#### Lifecycle configuration
+
+The LifecycleConfiguration input parameter to CreateAgentRuntime lets you manage the lifecycle of runtime sessions and resources in Amazon Bedrock AgentCore Runtime. This configuration helps optimize resource utilization by automatically cleaning up idle sessions and preventing long-running instances from consuming resources indefinitely.
+
+You can configure:
+
+- idleRuntimeSessionTimeout: Timeout in seconds for idle runtime sessions. When a session remains idle for this duration, it will trigger termination. Termination can last up to 15 seconds due to logging and other process completion. Default: 900 seconds (15 minutes)
+- maxLifetime: Maximum lifetime for the instance in seconds. Once reached, instances will initialize termination. Termination can last up to 15 seconds due to logging and other process completion. Default: 28800 seconds (8 hours)
+
+For additional information, please refer to the [documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-lifecycle-settings.html).
+
+```typescript fixture=default
+const repository = new ecr.Repository(this, "TestRepository", {
+  repositoryName: "test-agent-runtime",
+});
+
+const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0");
+
+new agentcore.Runtime(this, 'test-runtime', {
+  runtimeName: 'test_runtime',
+  agentRuntimeArtifact: agentRuntimeArtifact,
+  lifecycleConfiguration: {
+    idleRuntimeSessionTimeout: Duration.minutes(10),
+    maxLifetime: Duration.hours(4),
+  },
+});
+```
+
+#### Request header configuration
+
+Custom headers let you pass contextual information from your application directly to your agent code without cluttering the main request payload. This includes authentication tokens like JWT (JSON Web Tokens, which contain user identity and authorization claims) through the Authorization header, allowing your agent to make decisions based on who is calling it. You can also pass custom metadata like user preferences, session identifiers, or trace context using headers prefixed with X-Amzn-Bedrock-AgentCore-Runtime-Custom-, giving your agent access to up to 20 pieces of runtime context that travel alongside each request. This information can be also used in downstream systems like AgentCore Memory that you can namespace based on those characteristics like user_id or aud in claims like line of business.
+
+For additional information, please refer to the [documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-header-allowlist.html).
+
+```typescript fixture=default
+const repository = new ecr.Repository(this, "TestRepository", {
+  repositoryName: "test-agent-runtime",
+});
+
+const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0");
+
+new agentcore.Runtime(this, 'test-runtime', {
+  runtimeName: 'test_runtime',
+  agentRuntimeArtifact: agentRuntimeArtifact,
+  requestHeaderConfiguration: {
+    allowlistedHeaders: ['X-Amzn-Bedrock-AgentCore-Runtime-Custom-H1'],
+  },
+});
+```
+
 ## Browser
 
 The Amazon Bedrock AgentCore Browser provides a secure, cloud-based browser that enables AI agents to interact with websites. It includes security features such as session isolation, built-in observability through live viewing, CloudTrail logging, and session replay capabilities.
@@ -583,6 +671,7 @@ For more information on VPC connectivity for Amazon Bedrock AgentCore Browser, p
 | `recordingConfig` | `RecordingConfig` | No | Recording configuration for browser. Defaults to no recording |
 | `executionRole` | `iam.IRole` | No | The IAM role that provides permissions for the browser to access AWS services. A new role will be created if not provided |
 | `tags` | `{ [key: string]: string }` | No | Tags to apply to the browser resource |
+| `browserSigning` | BrowserSigning | No | Browser signing configuration. Defaults to DISABLED |
 
 ### Basic Browser Creation
 
@@ -709,6 +798,21 @@ const browser = new agentcore.BrowserCustom(this, "MyBrowser", {
 // when recording is enabled, so no additional IAM configuration is needed
 ```
 
+### Browser with Browser signing
+
+AI agents need to browse the web on your behalf. When your agent visits a website to gather information, complete a form, or verify data, it encounters the same defenses designed to stop unwanted bots: CAPTCHAs, rate limits, and outright blocks.
+
+Amazon Bedrock AgentCore Browser supports Web Bot Auth. Web Bot Auth is a draft IETF protocol that gives agents verifiable cryptographic identities. When you enable Web Bot Auth in AgentCore Browser, the service issues cryptographic credentials that websites can verify. The agent presents these credentials with every request. The WAF may now additionally check the signature, confirm it matches a trusted directory, and allow the request through if verified bots are allowed by the domain owner and other WAF checks are clear.
+
+To enable the browser to sign requests using the Web Bot Auth protocol, create a browser tool with the browserSigning configuration:
+
+```typescript fixture=default
+const browser = new agentcore.BrowserCustom(this, 'test-browser', {
+  browserCustomName: 'test_browser',
+  browserSigning: agentcore.BrowserSigning.ENABLED
+});
+```
+
 ### Browser IAM Permissions
 
 The Browser construct provides convenient methods for granting IAM permissions:

packages/@aws-cdk/aws-bedrock-agentcore-alpha/agentcore/runtime/runtime-artifact.ts

@@ -18,6 +18,32 @@ import { md5hash } from 'aws-cdk-lib/core/lib/helpers-internal';
 import { Construct } from 'constructs';
 import { Runtime } from './runtime';
 import { ValidationError } from './validation-helpers';
+import { Location } from 'aws-cdk-lib/aws-s3';
+import { Stack, Token } from 'aws-cdk-lib';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+
+/**
+ * Bedrock AgentCore runtime environment for code execution
+ * Allowed values: PYTHON_3_10 | PYTHON_3_11 | PYTHON_3_12 | PYTHON_3_13
+ */
+export enum AgentCoreRuntime {
+  /**
+   * Python 3.10 runtime
+   */
+  PYTHON_3_10 = 'PYTHON_3_10',
+  /**
+   * Python 3.11 runtime
+   */
+  PYTHON_3_11 = 'PYTHON_3_11',
+  /**
+   * Python 3.12 runtime
+   */
+  PYTHON_3_12 = 'PYTHON_3_12',
+  /**
+   * Python 3.13 runtime
+   */
+  PYTHON_3_13 = 'PYTHON_3_13',
+}
 
 /**
  * Abstract base class for agent runtime artifacts.
@@ -40,6 +66,16 @@ export abstract class AgentRuntimeArtifact {
     return new AssetImage(directory, options);
   }
 
+  /**
+   * Reference an agent runtime artifact that's constructed directly from an S3 object
+   * @param s3Location The source code location and configuration details.
+   * @param runtime The runtime environment for executing the code. Allowed values: PYTHON_3_10 | PYTHON_3_11 | PYTHON_3_12 | PYTHON_3_13
+   * @param entrypoint The entry point for the code execution, specifying the function or method that should be invoked when the code runs.
+   */
+  public static fromS3(s3Location: Location, runtime: AgentCoreRuntime, entrypoint: string[]): AgentRuntimeArtifact {
+    return new S3Image(s3Location, runtime, entrypoint);
+  }
+
   /**
    * Called when the image is used by a Runtime to handle side effects like permissions
    */
@@ -113,3 +149,45 @@ class AssetImage extends AgentRuntimeArtifact {
     } as any;
   }
 }
+
+class S3Image extends AgentRuntimeArtifact {
+  private bound = false;
+
+  constructor(private readonly s3Location: Location, private readonly runtime: AgentCoreRuntime, private readonly entrypoint: string[]) {
+    super();
+  }
+
+  public bind(scope: Construct, runtime: Runtime): void {
+    // Handle permissions (only once)
+    if (!this.bound && runtime.role) {
+      if (!Token.isUnresolved(this.s3Location.bucketName)) {
+        Stack.of(scope).resolve(this.s3Location.bucketName);
+      }
+      const bucket = s3.Bucket.fromBucketName(
+        scope,
+        `${this.s3Location.bucketName}CodeArchive`,
+        this.s3Location.bucketName,
+      );
+      // Ensure the policy is applied before the browser resource is created
+      bucket.grantRead(runtime.role);
+      this.bound = true;
+    }
+  }
+
+  public _render(): CfnRuntime.AgentRuntimeArtifactProperty {
+    const s3Config: any = {
+      bucket: this.s3Location.bucketName,
+      prefix: this.s3Location.objectKey,
+    };
+    if (this.s3Location.objectVersion) {
+      s3Config.versionId = this.s3Location.objectVersion;
+    }
+    return {
+      code: {
+        s3: s3Config,
+      },
+      runtime: this.runtime,
+      entryPoint: this.entrypoint,
+    } as any;
+  }
+}