Amazon Bedrock AgentCore Construct Library

---

> The APIs of higher level constructs in this module are experimental and under active development.
> They are subject to non-backward compatible changes or removal in any future version. These are
> not subject to the Semantic Versioning model and breaking changes will be
> announced in the release notes. This means that while you may use them, you may need to update
> your source code when upgrading to a newer version of this package.

---

| Language | Package |
| :--------------------------------------------------------------------------------------------- | --------------------------------------- |
| !Typescript Logo TypeScript | @aws-cdk/aws-bedrock-agentcore-alpha |

Amazon Bedrock AgentCore enables you to deploy and operate highly capable AI agents securely, at scale. It offers infrastructure purpose-built for dynamic agent workloads, powerful tools to enhance agents, and essential controls for real-world deployment. AgentCore services can be used together or independently and work with any framework including CrewAI, LangGraph, LlamaIndex, and Strands Agents, as well as any foundation model in or outside of Amazon Bedrock, giving you ultimate flexibility. AgentCore eliminates the undifferentiated heavy lifting of building specialized agent infrastructure, so you can accelerate agents to production.

This construct library facilitates the deployment of Bedrock AgentCore primitives, enabling you to create sophisticated AI applications that can interact with your systems and data sources.

> Note: Users need to ensure their CDK deployment role has the iam:CreateServiceLinkedRole permission for AgentCore service-linked roles.

AgentCore Runtime

The AgentCore Runtime construct enables you to deploy containerized agents on Amazon Bedrock AgentCore.
This L2 construct simplifies runtime creation just pass your ECR repository name
and the construct handles all the configuration with sensible defaults.

$3

Endpoints provide a stable way to invoke specific versions of your agent runtime, enabling controlled deployments across different environments.
When you create an agent runtime, Amazon Bedrock AgentCore automatically creates a "DEFAULT" endpoint which always points to the latest version
of runtime.

You can create additional endpoints in two ways:

1. Using Runtime.addEndpoint() - Convenient method when creating endpoints alongside the runtime.
2. Using RuntimeEndpoint - Flexible approach for existing runtimes.

For example, you might keep a "production" endpoint on a stable version while testing newer versions
through a "staging" endpoint. This separation allows you to test changes thoroughly before promoting them
to production by simply updating the endpoint to point to the newer version.

$3

| Name | Type | Required | Description |
|------|------|----------|-------------|
| runtimeName | string | No | The name of the agent runtime. Valid characters are a-z, A-Z, 0-9, _ (underscore). Must start with a letter and can be up to 48 characters long. If not provided, a unique name will be auto-generated |
| agentRuntimeArtifact | AgentRuntimeArtifact | Yes | The artifact configuration for the agent runtime containing the container configuration with ECR URI |
| executionRole | iam.IRole | No | The IAM role that provides permissions for the agent runtime. If not provided, a role will be created automatically |
| networkConfiguration | NetworkConfiguration | No | Network configuration for the agent runtime. Defaults to RuntimeNetworkConfiguration.usingPublicNetwork() |
| description | string | No | Optional description for the agent runtime |
| protocolConfiguration | ProtocolType | No | Protocol configuration for the agent runtime. Defaults to ProtocolType.HTTP |
| 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 |

$3

| Name | Type | Required | Description |
|------|------|----------|-------------|
| endpointName | string | No | The name of the runtime endpoint. Valid characters are a-z, A-Z, 0-9, _ (underscore). Must start with a letter and can be up to 48 characters long. If not provided, a unique name will be auto-generated |
| agentRuntimeId | string | Yes | The Agent Runtime ID for this endpoint |
| agentRuntimeVersion | string | Yes | The Agent Runtime version for this endpoint. Must be between 1 and 5 characters long.|
| description | string | No | Optional description for the runtime endpoint |
| tags | { [key: string]: string } | No | Tags for the runtime endpoint |

$3

#### Option 1: Use an existing image in ECR

Reference an image available within ECR.

``typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

// The runtime by default create ECR permission only for the repository available in the account the stack is being deployed const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0");

// Create runtime using the built image const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact });`

#### Option 2: Use a local asset

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 fixture=default const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromAsset( path.join(__dirname, "path to agent dockerfile directory") );

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, });`

#### 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.

`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, });`

#### Option 4: Use an ECR container image URI

Reference an ECR container image directly by its URI. This is useful when you have a pre-existing ECR image URI from CloudFormation parameters or cross-stack references. No IAM permissions are automatically granted - you must ensure the runtime has ECR pull permissions.

`typescript fixture=default // Direct URI reference const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromImageUri( "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-agent:v1.0.0" );

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, });`

You can also use CloudFormation parameters or references:

`typescript fixture=default // Using a CloudFormation parameter const imageUriParam = new cdk.CfnParameter(this, "ImageUri", { type: "String", description: "Container image URI for the agent runtime", });

const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromImageUri( imageUriParam.valueAsString );

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, });`

`$3`

To grant the runtime permissions to invoke Bedrock models or inference profiles:

`typescript fixture=default // Note: This example uses @aws-cdk/aws-bedrock-alpha which must be installed separately declare const runtime: agentcore.Runtime;

// Define the Bedrock Foundation Model const model = bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_7_SONNET_V1_0;

// Grant the runtime permissions to invoke the model model.grantInvoke(runtime);

// Create a cross-region inference profile for Claude 3.7 Sonnet const inferenceProfile = bedrock.CrossRegionInferenceProfile.fromConfig({ geoRegion: bedrock.CrossRegionInferenceProfileRegion.US, model: bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_7_SONNET_V1_0 });

// Grant the runtime permissions to invoke the inference profile inferenceProfile.grantInvoke(runtime);`

`$3`

Amazon Bedrock AgentCore automatically manages runtime versioning to ensure safe deployments and rollback capabilities. When you create an agent runtime, AgentCore automatically creates version 1 (V1). Each subsequent update to the runtime configuration (such as updating the container image, modifying network settings, or changing protocol configurations) creates a new immutable version. These versions contain complete, self-contained configurations that can be referenced by endpoints, allowing you to maintain different versions for different environments or gradually roll out updates.

#### Managing Endpoints and Versions

Amazon Bedrock AgentCore automatically manages runtime versioning to provide safe deployments and rollback capabilities. You can follow the steps below to understand how to use versioning with runtime for controlled deployments across different environments.

##### Step 1: Initial Deployment

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.

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0"), });`

##### Step 2: Creating Custom Endpoints

After the initial deployment, you can create additional endpoints for different environments. For example, you might create a "production" 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.

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0"), });

const prodEndpoint = runtime.addEndpoint("production", { version: "1", description: "Stable production endpoint - pinned to v1" });`

##### Step 3: Runtime Update Deployment

When you update the runtime configuration (such as updating the container image, modifying network settings, or changing protocol configurations), AgentCore automatically creates a new version (Version 2). Upon this update:

- Version 2 is created automatically with the new configuration - The DEFAULT endpoint automatically updates to point to Version 2 - Any explicitly pinned endpoints (like the production endpoint) remain on their specified versions

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const agentRuntimeArtifactNew = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v2.0.0");

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifactNew, });`

##### Step 4: Testing with Staging Endpoints

Once Version 2 exists, you can create a staging endpoint that points to the new version. This staging endpoint allows you to test the 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.

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const agentRuntimeArtifactNew = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v2.0.0");

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifactNew, });

const stagingEndpoint = runtime.addEndpoint("staging", { version: "2", description: "Staging environment for testing new version" });`

##### Step 5: Promoting to Production

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.

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const agentRuntimeArtifactNew = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v2.0.0");

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifactNew, });

const prodEndpoint = runtime.addEndpoint("production", { version: "2", // New version added here description: "Stable production endpoint" });`

`$3`

RuntimeEndpoint can also be created as a standalone resource.

#### Example: Creating an endpoint for an existing runtime

`typescript fixture=default // Reference an existing runtime by its ID const existingRuntimeId = "abc123-runtime-id"; // The ID of an existing runtime

// Create a standalone endpoint const endpoint = new agentcore.RuntimeEndpoint(this, "MyEndpoint", { endpointName: "production", agentRuntimeId: existingRuntimeId, agentRuntimeVersion: "1", // Specify which version to use description: "Production endpoint for existing runtime" });`

`$3`

The AgentCore Runtime supports multiple authentication modes to secure access to your agent endpoints. Authentication is configured during runtime creation using the RuntimeAuthorizerConfiguration class's static factory methods.

#### IAM Authentication (Default)

IAM authentication is the default mode, when no authorizerConfiguration is set then the underlying service use IAM.

#### Cognito Authentication

To configure AWS Cognito User Pool authentication:

`typescript fixture=default declare const userPool: cognito.UserPool; declare const userPoolClient: cognito.UserPoolClient; declare const anotherUserPoolClient: cognito.UserPoolClient;

const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", }); const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0");

// Optional: Create custom claims for additional validation const customClaims = [ agentcore.RuntimeCustomClaim.withStringValue('department', 'engineering'), agentcore.RuntimeCustomClaim.withStringArrayValue('roles', ['admin'], agentcore.CustomClaimOperator.CONTAINS), agentcore.RuntimeCustomClaim.withStringArrayValue('permissions', ['read', 'write'], agentcore.CustomClaimOperator.CONTAINS_ANY), ];

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, authorizerConfiguration: agentcore.RuntimeAuthorizerConfiguration.usingCognito( userPool, // User Pool (required) [userPoolClient, anotherUserPoolClient], // User Pool Clients ["audience1"], // Allowed Audiences (optional) ["read", "write"], // Allowed Scopes (optional) customClaims, // Custom claims (optional) - see Custom Claims Validation section ), });`

You can configure:

- User Pool: The Cognito User Pool that issues JWT tokens - User Pool Clients: One or more Cognito User Pool App Clients that are allowed to access the runtime - Allowed audiences: Used to validate that the audiences specified in the Cognito token match or are a subset of the audiences specified in the AgentCore Runtime - Allowed scopes: Allow access only if the token contains at least one of the required scopes configured here - Custom claims: A set of rules to match specific claims in the incoming token against predefined values for validating JWT tokens

#### JWT Authentication

To configure custom JWT authentication with your own OpenID Connect (OIDC) provider:

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", }); const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0");

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, authorizerConfiguration: agentcore.RuntimeAuthorizerConfiguration.usingJWT( "https://example.com/.well-known/openid-configuration", // Discovery URL (required) ["client1", "client2"], // Allowed Client IDs (optional) ["audience1"], // Allowed Audiences (optional) ["read", "write"], // Allowed Scopes (optional) // Custom claims (optional) - see Custom Claims Validation section below ), });`

You can configure:

- Discovery URL: Enter the Discovery URL from your identity provider (e.g. Okta, Cognito, etc.), typically found in that provider's documentation. This allows your Agent or Tool to fetch login, downstream resource token, and verification settings. - Allowed audiences: This is used to validate that the audiences specified for the OAuth token matches or are a subset of the audiences specified in the AgentCore Runtime. - Allowed clients: This is used to validate that the public identifier of the client, as specified in the authorization token, is allowed to access the AgentCore Runtime. - Allowed scopes: Allow access only if the token contains at least one of the required scopes configured here. - Custom claims: A set of rules to match specific claims in the incoming token against predefined values for validating JWT tokens.

Note: The discovery URL must end with /.well-known/openid-configuration.

##### Custom Claims Validation

Custom claims allow you to validate additional fields in JWT tokens beyond the standard audience, client, and scope validations. You can create custom claims using the RuntimeCustomClaim class:

// String claim - validates that the claim exactly equals the specified value // Uses EQUALS operator automatically const departmentClaim = agentcore.RuntimeCustomClaim.withStringValue('department', 'engineering');

// String array claim with CONTAINS operator (default) // Validates that the claim array contains a specific string value // IMPORTANT: CONTAINS requires exactly one value in the array parameter const rolesClaim = agentcore.RuntimeCustomClaim.withStringArrayValue('roles', ['admin']);

// String array claim with CONTAINS_ANY operator // Validates that the claim array contains at least one of the specified values // Use this when you want to check for multiple possible values const permissionsClaim = agentcore.RuntimeCustomClaim.withStringArrayValue( 'permissions', ['read', 'write'], agentcore.CustomClaimOperator.CONTAINS_ANY );

// Use custom claims in authorizer configuration const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, authorizerConfiguration: agentcore.RuntimeAuthorizerConfiguration.usingJWT( "https://example.com/.well-known/openid-configuration", ["client1", "client2"], ["audience1"], ["read", "write"], [departmentClaim, rolesClaim, permissionsClaim] // Custom claims ), });`

Custom Claim Rules:

- String claims: Must use the EQUALSoperator (automatically set). The claim value must exactly match the specified string. - String array claims: Can useCONTAINS (default) or CONTAINS_ANYoperators: -CONTAINS: Checks if the claim array contains a specific string value. Requires exactly one value in the array parameter. For example, ['admin'] will check if the token's claim array contains the string 'admin'. -CONTAINS_ANY: Checks if the claim array contains at least one of the provided string values. Use this when you want to validate against multiple possible values. For example, ['read', 'write'] will check if the token's claim array contains either 'read' or 'write'.

Example Use Cases:

- Use CONTAINS when you need to verify a user has a specific role: RuntimeCustomClaim.withStringArrayValue('roles', ['admin'])- UseCONTAINS_ANY when you need to verify a user has any of several permissions: RuntimeCustomClaim.withStringArrayValue('permissions', ['read', 'write'], CustomClaimOperator.CONTAINS_ANY)

#### OAuth Authentication

To configure OAuth 2.0 authentication:

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, authorizerConfiguration: agentcore.RuntimeAuthorizerConfiguration.usingOAuth( "https://github.com/.well-known/openid-configuration", // Discovery URL (required) "oauth_client_123", // OAuth Client ID (required) ["audience1"], // Allowed Audiences (optional) ["openid", "profile"], // Allowed Scopes (optional) // Custom claims (optional) - see Custom Claims Validation section ), });`

#### Using a Custom IAM Role

Instead of using the auto-created execution role, you can provide your own IAM role with specific permissions: The auto-created role includes all necessary baseline permissions for ECR access, CloudWatch logging, and X-Ray tracing. When providing a custom role, ensure these permissions are included.

`$3`

The AgentCore Runtime supports two network modes for deployment:

#### Public Network Mode (Default)

By default, runtimes are deployed in PUBLIC network mode, which provides internet access suitable for less sensitive or open-use scenarios:

// Explicitly using public network (this is the default) const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, networkConfiguration: agentcore.RuntimeNetworkConfiguration.usingPublicNetwork(), });`

#### VPC Network Mode

For enhanced security and network isolation, you can deploy your runtime within a VPC:

// Create or use an existing VPC const vpc = new ec2.Vpc(this, 'MyVpc', { maxAzs: 2, });

// Configure runtime with VPC const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, networkConfiguration: agentcore.RuntimeNetworkConfiguration.usingVpc(this, { vpc: vpc, vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS }, // Optionally specify security groups, or one will be created automatically // securityGroups: [mySecurityGroup], }), });

#### Managing Security Groups with VPC Configuration

When using VPC mode, the Runtime implements ec2.IConnectable, allowing you to manage network access using the connections property:

`typescript fixture=default const vpc = new ec2.Vpc(this, 'MyVpc', { maxAzs: 2, });

// Create runtime with VPC configuration const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, networkConfiguration: agentcore.RuntimeNetworkConfiguration.usingVpc(this, { vpc: vpc, vpcSubnets: { subnetType: ec2.SubnetType.PRIVATE_WITH_EGRESS }, }), });

// Now you can manage network access using the connections property // Allow inbound HTTPS traffic from a specific security group const webServerSecurityGroup = new ec2.SecurityGroup(this, 'WebServerSG', { vpc }); runtime.connections.allowFrom(webServerSecurityGroup, ec2.Port.tcp(443), 'Allow HTTPS from web servers');

// Allow outbound connections to a database const databaseSecurityGroup = new ec2.SecurityGroup(this, 'DatabaseSG', { vpc }); runtime.connections.allowTo(databaseSecurityGroup, ec2.Port.tcp(5432), 'Allow PostgreSQL connection');

// Allow outbound HTTPS to anywhere (for external API calls) runtime.connections.allowToAnyIpv4(ec2.Port.tcp(443), 'Allow HTTPS outbound');`

`$3`

The Runtime construct provides convenient methods for granting IAM permissions to principals that need to invoke the runtime or manage its execution role.

// Create a runtime const runtime = new agentcore.Runtime(this, "MyRuntime", { runtimeName: "my_runtime", agentRuntimeArtifact: agentRuntimeArtifact, });

// Create a Lambda function that needs to invoke the runtime const invokerFunction = new lambda.Function(this, "InvokerFunction", { runtime: lambda.Runtime.PYTHON_3_12, handler: "index.handler", code: lambda.Code.fromInline(
import boto3
def handler(event, context):
client = boto3.client('bedrock-agentcore')
# Invoke the runtime...
), });

// Grant permission to invoke the runtime directly runtime.grantInvokeRuntime(invokerFunction);

// Grant permission to invoke the runtime on behalf of a user // (requires X-Amzn-Bedrock-AgentCore-Runtime-User-Id header) runtime.grantInvokeRuntimeForUser(invokerFunction);

// Grant both invoke permissions (most common use case) runtime.grantInvoke(invokerFunction);

// Grant specific custom permissions to the runtime's execution role runtime.grant(['bedrock:InvokeModel'], ['arn:aws:bedrock:::*']);

// Add a policy statement to the runtime's execution role runtime.addToRolePolicy(new iam.PolicyStatement({ actions: ['s3:GetObject'], resources: ['arn:aws:s3:::my-bucket/*'], }));`

`$3`

#### 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.

`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.

`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.

Additional information about the browser tool can be found in the official documentation

`$3`

The Browser construct supports the following network modes:

1. Public Network Mode (BrowserNetworkMode.usingPublicNetwork()) - Default

- Allows internet access for web browsing and external API calls - Suitable for scenarios where agents need to interact with publicly available websites - Enables full web browsing capabilities - VPC mode is not supported with this option

2. VPC (Virtual Private Cloud) (BrowserNetworkMode.usingVpc())

- Select whether to run the browser in a virtual private cloud (VPC). - By configuring VPC connectivity, you enable secure access to private resources such as databases, internal APIs, and services within your VPC.

While the VPC itself is mandatory, these are optional: - Subnets - if not provided, CDK will select appropriate subnets from the VPC - Security Groups - if not provided, CDK will create a default security group - Specific subnet selection criteria - you can let CDK choose automatically

For more information on VPC connectivity for Amazon Bedrock AgentCore Browser, please refer to the official documentation.

`$3`

| Name | Type | Required | Description | |------|------|----------|-------------| |browserCustomName | string | No | The name of the browser. Must start with a letter and can be up to 48 characters long. Pattern: [a-zA-Z][a-zA-Z0-9_]{0,47}. If not provided, a unique name will be auto-generated | |description | string| No | Optional description for the browser. Can have up to 200 characters | |networkConfiguration | BrowserNetworkConfiguration| No | Network configuration for browser. Defaults to PUBLIC network mode | |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 |

`$3`

`typescript fixture=default // Create a basic browser with public network access const browser = new agentcore.BrowserCustom(this, "MyBrowser", { browserCustomName: "my_browser", description: "A browser for web automation", });`

`$3`

`typescript fixture=default // Create a browser with custom tags const browser = new agentcore.BrowserCustom(this, "MyBrowser", { browserCustomName: "my_browser", description: "A browser for web automation with tags", networkConfiguration: agentcore.BrowserNetworkConfiguration.usingPublicNetwork(), tags: { Environment: "Production", Team: "AI/ML", Project: "AgentCore", }, });`

`$3`

`typescript fixture=default const browser = new agentcore.BrowserCustom(this, 'BrowserVpcWithRecording', { browserCustomName: 'browser_recording', networkConfiguration: agentcore.BrowserNetworkConfiguration.usingVpc(this, { vpc: new ec2.Vpc(this, 'VPC', { restrictDefaultSecurityGroup: false }), }), });`

Browser exposes a connections property. This property returns a connections object, which simplifies the process of defining and managing ingress and egress rules for security groups in your AWS CDK applications. Instead of directly manipulating security group rules, you interact with the Connections object of a construct, which then translates your connectivity requirements into the appropriate security group rules. For instance:

`typescript fixture=default const vpc = new ec2.Vpc(this, 'testVPC');

const browser = new agentcore.BrowserCustom(this, 'test-browser', { browserCustomName: 'test_browser', networkConfiguration: agentcore.BrowserNetworkConfiguration.usingVpc(this, { vpc: vpc, }), });

browser.connections.addSecurityGroup(new ec2.SecurityGroup(this, 'AdditionalGroup', { vpc }));`

So security groups can be added after the browser construct creation. You can use methods like allowFrom() and allowTo() to grant ingress access to/egress access from a specified peer over a given portRange. The Connections object automatically adds the necessary ingress or egress rules to the security group(s) associated with the calling construct.

`$3`

`typescript fixture=default // Create an S3 bucket for recordings const recordingBucket = new s3.Bucket(this, "RecordingBucket", { bucketName: "my-browser-recordings", removalPolicy: RemovalPolicy.DESTROY, // For demo purposes });

// Create browser with recording enabled const browser = new agentcore.BrowserCustom(this, "MyBrowser", { browserCustomName: "my_browser", description: "Browser with recording enabled", networkConfiguration: agentcore.BrowserNetworkConfiguration.usingPublicNetwork(), recordingConfig: { enabled: true, s3Location: { bucketName: recordingBucket.bucketName, objectKey: "browser-recordings/", }, }, });`

`$3`

`typescript fixture=default // Create a custom execution role const executionRole = new iam.Role(this, "BrowserExecutionRole", { assumedBy: new iam.ServicePrincipal("bedrock-agentcore.amazonaws.com"), managedPolicies: [ iam.ManagedPolicy.fromAwsManagedPolicyName("AmazonBedrockAgentCoreBrowserExecutionRolePolicy"), ], });

// Create browser with custom execution role const browser = new agentcore.BrowserCustom(this, "MyBrowser", { browserCustomName: "my_browser", description: "Browser with custom execution role", networkConfiguration: agentcore.BrowserNetworkConfiguration.usingPublicNetwork(), executionRole: executionRole, });`

`$3`

// The browser construct automatically grants S3 permissions to the execution role // when recording is enabled, so no additional IAM configuration is needed`

`$3`

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 });`

`$3`

The Browser construct provides convenient methods for granting IAM permissions:

`typescript fixture=default // Create a browser const browser = new agentcore.BrowserCustom(this, "MyBrowser", { browserCustomName: "my_browser", description: "Browser for web automation", networkConfiguration: agentcore.BrowserNetworkConfiguration.usingPublicNetwork(), });

// Create a role that needs access to the browser const userRole = new iam.Role(this, "UserRole", { assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"), });

// Grant read permissions (Get and List actions) browser.grantRead(userRole);

// Grant use permissions (Start, Update, Stop actions) browser.grantUse(userRole);

// Grant specific custom permissions browser.grant(userRole, "bedrock-agentcore:GetBrowserSession");`

`Code Interpreter`

The Amazon Bedrock AgentCore Code Interpreter enables AI agents to write and execute code securely in sandbox environments, enhancing their accuracy and expanding their ability to solve complex end-to-end tasks. This is critical in Agentic AI applications where the agents may execute arbitrary code that can lead to data compromise or security risks. The AgentCore Code Interpreter tool provides secure code execution, which helps you avoid running into these issues.

For more information about code interpreter, please refer to the official documentation

`$3`

The Code Interpreter construct supports the following network modes:

1. Public Network Mode (CodeInterpreterNetworkMode.usingPublicNetwork()) - Default

- Allows internet access for package installation and external API calls - Suitable for development and testing environments - Enables downloading Python packages from PyPI

2. Sandbox Network Mode (CodeInterpreterNetworkMode.usingSandboxNetwork()) - Isolated network environment with no internet access - Suitable for production environments with strict security requirements - Only allows access to pre-installed packages and local resources

3. VPC (Virtual Private Cloud) (CodeInterpreterNetworkMode.usingVpc()) - Select whether to run the browser in a virtual private cloud (VPC). - By configuring VPC connectivity, you enable secure access to private resources such as databases, internal APIs, and services within your VPC.

For more information on VPC connectivity for Amazon Bedrock AgentCore Browser, please refer to the official documentation.

`$3`

| Name | Type | Required | Description | |------|------|----------|-------------| |codeInterpreterCustomName | string | No | The name of the code interpreter. Must start with a letter and can be up to 48 characters long. Pattern: [a-zA-Z][a-zA-Z0-9_]{0,47}. If not provided, a unique name will be auto-generated | |description | string| No | Optional description for the code interpreter. Can have up to 200 characters | |executionRole | iam.IRole| No | The IAM role that provides permissions for the code interpreter to access AWS services. A new role will be created if not provided | |networkConfiguration | CodeInterpreterNetworkConfiguration| No | Network configuration for code interpreter. Defaults to PUBLIC network mode | |tags | { [key: string]: string } | No | Tags to apply to the code interpreter resource |

`$3`

`typescript fixture=default // Create a basic code interpreter with public network access const codeInterpreter = new agentcore.CodeInterpreterCustom(this, "MyCodeInterpreter", { codeInterpreterCustomName: "my_code_interpreter", description: "A code interpreter for Python execution", });`

`$3`

`typescript fixture=default const codeInterpreter = new agentcore.CodeInterpreterCustom(this, "MyCodeInterpreter", { codeInterpreterCustomName: "my_sandbox_interpreter", description: "Code interpreter with isolated network access", networkConfiguration: agentcore.BrowserNetworkConfiguration.usingVpc(this, { vpc: new ec2.Vpc(this, 'VPC', { restrictDefaultSecurityGroup: false }), }), });`

Code Interpreter exposes a connections property. This property returns a connections object, which simplifies the process of defining and managing ingress and egress rules for security groups in your AWS CDK applications. Instead of directly manipulating security group rules, you interact with the Connections object of a construct, which then translates your connectivity requirements into the appropriate security group rules. For instance:

`typescript fixture=default const vpc = new ec2.Vpc(this, 'testVPC');

const codeInterpreter = new agentcore.CodeInterpreterCustom(this, "MyCodeInterpreter", { codeInterpreterCustomName: "my_sandbox_interpreter", description: "Code interpreter with isolated network access", networkConfiguration: agentcore.BrowserNetworkConfiguration.usingVpc(this, { vpc: vpc, }), });

codeInterpreter.connections.addSecurityGroup(new ec2.SecurityGroup(this, 'AdditionalGroup', { vpc }));`

`$3`

`typescript fixture=default // Create code interpreter with sandbox network mode (isolated) const codeInterpreter = new agentcore.CodeInterpreterCustom(this, "MyCodeInterpreter", { codeInterpreterCustomName: "my_sandbox_interpreter", description: "Code interpreter with isolated network access", networkConfiguration: agentcore.CodeInterpreterNetworkConfiguration.usingSandboxNetwork(), });`

`$3`

`typescript fixture=default // Create a custom execution role const executionRole = new iam.Role(this, "CodeInterpreterExecutionRole", { assumedBy: new iam.ServicePrincipal("bedrock-agentcore.amazonaws.com"), });

// Create code interpreter with custom execution role const codeInterpreter = new agentcore.CodeInterpreterCustom(this, "MyCodeInterpreter", { codeInterpreterCustomName: "my_code_interpreter", description: "Code interpreter with custom execution role", networkConfiguration: agentcore.CodeInterpreterNetworkConfiguration.usingPublicNetwork(), executionRole: executionRole, });`

`$3`

The Code Interpreter construct provides convenient methods for granting IAM permissions:

`typescript fixture=default // Create a code interpreter const codeInterpreter = new agentcore.CodeInterpreterCustom(this, "MyCodeInterpreter", { codeInterpreterCustomName: "my_code_interpreter", description: "Code interpreter for Python execution", networkConfiguration: agentcore.CodeInterpreterNetworkConfiguration.usingPublicNetwork(), });

// Create a role that needs access to the code interpreter const userRole = new iam.Role(this, "UserRole", { assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"), });

// Grant read permissions (Get and List actions) codeInterpreter.grantRead(userRole);

// Grant use permissions (Start, Invoke, Stop actions) codeInterpreter.grantUse(userRole);

// Grant specific custom permissions codeInterpreter.grant(userRole, "bedrock-agentcore:GetCodeInterpreterSession");`

`$3`

`Gateway`

The Gateway construct provides a way to create Amazon Bedrock Agent Core Gateways, which serve as integration points between agents and external services.

`$3`

| Name | Type | Required | Description | |------|------|----------|-------------| |gatewayName | string| No | The name of the gateway. Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen). Maximum 100 characters. If not provided, a unique name will be auto-generated | |description | string| No | Optional description for the gateway. Maximum 200 characters | |protocolConfiguration | IGatewayProtocolConfig| No | The protocol configuration for the gateway. Defaults to MCP protocol | |authorizerConfiguration | IGatewayAuthorizerConfig| No | The authorizer configuration for the gateway. Defaults to Cognito | |exceptionLevel | GatewayExceptionLevel| No | The verbosity of exception messages. Use DEBUG mode to see granular exception messages | |kmsKey | kms.IKey| No | The AWS KMS key used to encrypt data associated with the gateway | |role | iam.IRole| No | The IAM role that provides permissions for the gateway to access AWS services. A new role will be created if not provided | |tags | { [key: string]: string } | No | Tags for the gateway. A list of key:value pairs of tags to apply to this Gateway resource |

`$3`

The protocol configuration defaults to MCP and the inbound auth configuration uses Cognito (it is automatically created on your behalf).

`typescript fixture=default // Create a basic gateway with default MCP protocol and Cognito authorizer const gateway = new agentcore.Gateway(this, "MyGateway", { gatewayName: "my-gateway", });`

`$3`

Currently MCP is the only protocol available. To configure it, use the protocol property with McpProtocolConfiguration:

- Instructions: Guidance for how to use the gateway with your tools - Semantic search: Smart tool discovery that finds the right tools without typical limits. It improves accuracy by finding relevant tools based on context - Supported versions: Which MCP protocol versions the gateway can use

`typescript fixture=default const gateway = new agentcore.Gateway(this, "MyGateway", { gatewayName: "my-gateway", protocolConfiguration: new agentcore.McpProtocolConfiguration({ instructions: "Use this gateway to connect to external MCP tools", searchType: agentcore.McpGatewaySearchType.SEMANTIC, supportedVersions: [agentcore.MCPProtocolVersion.MCP_2025_03_26], }), });`

`$3`

Before you create your gateway, you must set up inbound authorization. Inbound authorization validates users who attempt to access targets through your AgentCore gateway. By default, if not provided, the construct will create and configure Cognito as the default identity provider (inbound Auth setup). AgentCore supports the following types of inbound authorization:

JSON Web Token (JWT) – A secure and compact token used for authorization. After creating the JWT, you specify it as the authorization configuration when you create the gateway. You can create a JWT with any of the identity providers at Provider setup and configuration.

You can configure a custom authorization provider using the authorizerConfiguration property with GatewayAuthorizer.usingCustomJwt(). You need to specify an OAuth discovery server and client IDs/audiences when you create the gateway. You can specify the following:

- Discovery Url — String that must match the pattern ^.+/\.well-known/openid-configuration$ for OpenID Connect discovery URLs - At least one of the below options depending on the chosen identity provider. - Allowed audiences — List of allowed audiences for JWT tokens - Allowed clients — List of allowed client identifiers - Allowed scopes — List of allowed scopes for JWT tokens - Custom claims — Optional custom claim validations (see Custom Claims Validation section below)

`typescript fixture=default

// Optional: Create custom claims (CustomClaimOperator and GatewayCustomClaim from agentcore) const customClaims = [ agentcore.GatewayCustomClaim.withStringValue('department', 'engineering'), agentcore.GatewayCustomClaim.withStringArrayValue('roles', ['admin'], agentcore.CustomClaimOperator.CONTAINS), agentcore.GatewayCustomClaim.withStringArrayValue('permissions', ['read', 'write'], agentcore.CustomClaimOperator.CONTAINS_ANY), ];

const gateway = new agentcore.Gateway(this, "MyGateway", { gatewayName: "my-gateway", authorizerConfiguration: agentcore.GatewayAuthorizer.usingCustomJwt({ discoveryUrl: "https://auth.example.com/.well-known/openid-configuration", allowedAudience: ["my-app"], allowedClients: ["my-client-id"], allowedScopes: ["read", "write"], customClaims: customClaims, // Optional custom claims }), });`

IAM – Authorizes through the credentials of the AWS IAM identity trying to access the gateway.

`typescript fixture=default const gateway = new agentcore.Gateway(this, "MyGateway", { gatewayName: "my-gateway", authorizerConfiguration: agentcore.GatewayAuthorizer.usingAwsIam(), });

// Grant access to a Lambda function's role const lambdaRole = new iam.Role(this, "LambdaRole", { assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"), });

// The Lambda needs permission to invoke the gateway gateway.grantInvoke(lambdaRole);`

Cognito with M2M (Machine-to-Machine) Authentication (Default) – When no authorizer is specified, the construct automatically creates a Cognito User Pool configured for OAuth 2.0 client credentials flow. This enables machine-to-machine authentication suitable for AI agents and service-to-service communication.

For more information, see Setting up Amazon Cognito for Gateway inbound authorization.

`typescript fixture=default // Create a gateway with default Cognito M2M authorizer const gateway = new agentcore.Gateway(this, "MyGateway", { gatewayName: "my-gateway", });

// Access the Cognito resources for authentication setup const userPool = gateway.userPool; const userPoolClient = gateway.userPoolClient;

// Get the token endpoint URL and OAuth scopes for client credentials flow const tokenEndpointUrl = gateway.tokenEndpointUrl; const oauthScopes = gateway.oauthScopes; // oauthScopes are in the format: ['{resourceServerId}/read', '{resourceServerId}/write']`

Using Cognito User Pool Explicitly with Custom Claims – You can also use an existing Cognito User Pool with custom claims:

`typescript fixture=default declare const userPool: cognito.UserPool; declare const userPoolClient: cognito.UserPoolClient;

const gateway = new agentcore.Gateway(this, "MyGateway", { gatewayName: "my-gateway", authorizerConfiguration: agentcore.GatewayAuthorizer.usingCognito({ userPool: userPool, allowedClients: [userPoolClient], allowedAudiences: ["audience1"], allowedScopes: ["read", "write"], customClaims: customClaims, // Optional custom claims }), });`

To authenticate with the gateway, request an access token using the client credentials flow and use it to call Gateway endpoints. For more information about the token endpoint, see The token issuer endpoint.

The following is an example of a token request using curl:

`bash curl -X POST "${TOKEN_ENDPOINT_URL}" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials" \ -d "client_id=${USER_POOL_CLIENT_ID}" \ -d "client_secret=${CLIENT_SECRET}" \ -d "scope=${OAUTH_SCOPES}"`

`$3`

You can provide a KMS key, and configure the authorizer as well as the protocol configuration.

``typescript fixture=default
// Create a KMS key for encryption
const encryptionKey = new kms.Key(this, "GatewayEncryptionKey", {
enableKeyRotation: true,
description: "KMS key for gateway encryption",
});

// Create gateway with KMS encryption
const gateway = new agentcore.Gateway(this, "MyGateway", {
gatewayName: "my-encrypted-gateway",
description: "Gateway with KMS encryption",
protocolConfiguration: new agentcore.McpProtocolConfiguration({
instructions: "Use this gateway to connect to external MCP tools",
searchType: agentcore.McpGatewaySearchType.SEMANTIC,
supportedVersions: [agentcore.MCPProtocolVersion.MCP_2025_03_26],
}),
authorizerConfiguration: a

Amazon Bedrock AgentCore Construct Library

---

!cdk-constructs: Experimental

---

This construct library facilitates the deployment of Bedrock AgentCore primitives, enabling you to create sophisticated AI applications that can interact with your systems and data sources.

> Note: Users need to ensure their CDK deployment role has the iam:CreateServiceLinkedRole permission for AgentCore service-linked roles.

AgentCore Runtime

$3

You can create additional endpoints in two ways:

1. Using Runtime.addEndpoint() - Convenient method when creating endpoints alongside the runtime.
2. Using RuntimeEndpoint - Flexible approach for existing runtimes.

$3

#### Option 1: Use an existing image in ECR

Reference an image available within ECR.

``typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

// Create runtime using the built image const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact });`

#### Option 2: Use a local asset

`typescript fixture=default const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromAsset( path.join(__dirname, "path to agent dockerfile directory") );

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, });`

#### Option 3: Use direct code deployment

For more information, please refer to the documentation.

// the bucket above needs to contain the agent code

const runtimeInstance = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, });`

#### Option 4: Use an ECR container image URI

`typescript fixture=default // Direct URI reference const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromImageUri( "123456789012.dkr.ecr.us-east-1.amazonaws.com/my-agent:v1.0.0" );

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, });`

You can also use CloudFormation parameters or references:

const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromImageUri( imageUriParam.valueAsString );

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, });`

`$3`

To grant the runtime permissions to invoke Bedrock models or inference profiles:

`typescript fixture=default // Note: This example uses @aws-cdk/aws-bedrock-alpha which must be installed separately declare const runtime: agentcore.Runtime;

// Define the Bedrock Foundation Model const model = bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_7_SONNET_V1_0;

// Grant the runtime permissions to invoke the model model.grantInvoke(runtime);

// Grant the runtime permissions to invoke the inference profile inferenceProfile.grantInvoke(runtime);`

`$3`

#### Managing Endpoints and Versions

##### Step 1: Initial Deployment

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0"), });`

##### Step 2: Creating Custom Endpoints

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0"), });

const prodEndpoint = runtime.addEndpoint("production", { version: "1", description: "Stable production endpoint - pinned to v1" });`

##### Step 3: Runtime Update Deployment

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const agentRuntimeArtifactNew = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v2.0.0");

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifactNew, });`

##### Step 4: Testing with Staging Endpoints

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const agentRuntimeArtifactNew = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v2.0.0");

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifactNew, });

const stagingEndpoint = runtime.addEndpoint("staging", { version: "2", description: "Staging environment for testing new version" });`

##### Step 5: Promoting to Production

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const agentRuntimeArtifactNew = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v2.0.0");

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifactNew, });

const prodEndpoint = runtime.addEndpoint("production", { version: "2", // New version added here description: "Stable production endpoint" });`

`$3`

RuntimeEndpoint can also be created as a standalone resource.

#### Example: Creating an endpoint for an existing runtime

`typescript fixture=default // Reference an existing runtime by its ID const existingRuntimeId = "abc123-runtime-id"; // The ID of an existing runtime

`$3`

#### IAM Authentication (Default)

IAM authentication is the default mode, when no authorizerConfiguration is set then the underlying service use IAM.

#### Cognito Authentication

To configure AWS Cognito User Pool authentication:

`typescript fixture=default declare const userPool: cognito.UserPool; declare const userPoolClient: cognito.UserPoolClient; declare const anotherUserPoolClient: cognito.UserPoolClient;

You can configure:

#### JWT Authentication

To configure custom JWT authentication with your own OpenID Connect (OIDC) provider:

You can configure:

Note: The discovery URL must end with /.well-known/openid-configuration.

##### Custom Claims Validation

Custom claims allow you to validate additional fields in JWT tokens beyond the standard audience, client, and scope validations. You can create custom claims using the RuntimeCustomClaim class:

Custom Claim Rules:

Example Use Cases:

#### OAuth Authentication

To configure OAuth 2.0 authentication:

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", { runtimeName: "myAgent", agentRuntimeArtifact: agentRuntimeArtifact, authorizerConfiguration: agentcore.RuntimeAuthorizerConfiguration.usingOAuth( "https://github.com/.well-known/openid-configuration", // Discovery URL (required) "oauth_client_123", // OAuth Client ID (required) ["audience1"], // Allowed Audiences (optional) ["openid", "profile"], // Allowed Scopes (optional) // Custom claims (optional) - see Custom Claims Validation section ), });`

#### Using a Custom IAM Role

`$3`

The AgentCore Runtime supports two network modes for deployment:

#### Public Network Mode (Default)

By default, runtimes are deployed in PUBLIC network mode, which provides internet access suitable for less sensitive or open-use scenarios:

#### VPC Network Mode

For enhanced security and network isolation, you can deploy your runtime within a VPC:

// Create or use an existing VPC const vpc = new ec2.Vpc(this, 'MyVpc', { maxAzs: 2, });

#### Managing Security Groups with VPC Configuration

When using VPC mode, the Runtime implements ec2.IConnectable, allowing you to manage network access using the connections property:

`typescript fixture=default const vpc = new ec2.Vpc(this, 'MyVpc', { maxAzs: 2, });

// Allow outbound HTTPS to anywhere (for external API calls) runtime.connections.allowToAnyIpv4(ec2.Port.tcp(443), 'Allow HTTPS outbound');`

`$3`

The Runtime construct provides convenient methods for granting IAM permissions to principals that need to invoke the runtime or manage its execution role.

// Create a runtime const runtime = new agentcore.Runtime(this, "MyRuntime", { runtimeName: "my_runtime", agentRuntimeArtifact: agentRuntimeArtifact, });

// Grant permission to invoke the runtime directly runtime.grantInvokeRuntime(invokerFunction);

// Grant permission to invoke the runtime on behalf of a user // (requires X-Amzn-Bedrock-AgentCore-Runtime-User-Id header) runtime.grantInvokeRuntimeForUser(invokerFunction);

// Grant both invoke permissions (most common use case) runtime.grantInvoke(invokerFunction);

// Grant specific custom permissions to the runtime's execution role runtime.grant(['bedrock:InvokeModel'], ['arn:aws:bedrock:::*']);

// Add a policy statement to the runtime's execution role runtime.addToRolePolicy(new iam.PolicyStatement({ actions: ['s3:GetObject'], resources: ['arn:aws:s3:::my-bucket/*'], }));`

`$3`

#### Lifecycle configuration

You can configure:

For additional information, please refer to the documentation.

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0");

#### Request header configuration

For additional information, please refer to the documentation.

`typescript fixture=default const repository = new ecr.Repository(this, "TestRepository", { repositoryName: "test-agent-runtime", });

const agentRuntimeArtifact = agentcore.AgentRuntimeArtifact.fromEcrRepository(repository, "v1.0.0");

`Browser`

Additional information about the browser tool can be found in the official documentation

`$3`

The Browser construct supports the following network modes:

1. Public Network Mode (BrowserNetworkMode.usingPublicNetwork()) - Default

2. VPC (Virtual Private Cloud) (BrowserNetworkMode.usingVpc())

For more information on VPC connectivity for Amazon Bedrock AgentCore Browser, please refer to the official documentation.

`$3`

`typescript fixture=default const vpc = new ec2.Vpc(this, 'testVPC');

const browser = new agentcore.BrowserCustom(this, 'test-browser', { browserCustomName: 'test_browser', networkConfiguration: agentcore.BrowserNetworkConfiguration.usingVpc(this, { vpc: vpc, }), });

browser.connections.addSecurityGroup(new ec2.SecurityGroup(this, 'AdditionalGroup', { vpc }));`

`$3`

// The browser construct automatically grants S3 permissions to the execution role // when recording is enabled, so no additional IAM configuration is needed`

`$3`

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 });`

`$3`

The Browser construct provides convenient methods for granting IAM permissions:

// Create a role that needs access to the browser const userRole = new iam.Role(this, "UserRole", { assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"), });

// Grant read permissions (Get and List actions) browser.grantRead(userRole);

// Grant use permissions (Start, Update, Stop actions) browser.grantUse(userRole);

// Grant specific custom permissions browser.grant(userRole, "bedrock-agentcore:GetBrowserSession");`

`Code Interpreter`

For more information about code interpreter, please refer to the official documentation

`$3`

The Code Interpreter construct supports the following network modes:

1. Public Network Mode (CodeInterpreterNetworkMode.usingPublicNetwork()) - Default

- Allows internet access for package installation and external API calls - Suitable for development and testing environments - Enables downloading Python packages from PyPI

For more information on VPC connectivity for Amazon Bedrock AgentCore Browser, please refer to the official documentation.

`$3`

`typescript fixture=default const vpc = new ec2.Vpc(this, 'testVPC');

codeInterpreter.connections.addSecurityGroup(new ec2.SecurityGroup(this, 'AdditionalGroup', { vpc }));`

`$3`

The Code Interpreter construct provides convenient methods for granting IAM permissions:

// Create a role that needs access to the code interpreter const userRole = new iam.Role(this, "UserRole", { assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"), });

// Grant read permissions (Get and List actions) codeInterpreter.grantRead(userRole);

// Grant use permissions (Start, Invoke, Stop actions) codeInterpreter.grantUse(userRole);

// Grant specific custom permissions codeInterpreter.grant(userRole, "bedrock-agentcore:GetCodeInterpreterSession");`

`$3`

`Gateway`

The Gateway construct provides a way to create Amazon Bedrock Agent Core Gateways, which serve as integration points between agents and external services.

`$3`

The protocol configuration defaults to MCP and the inbound auth configuration uses Cognito (it is automatically created on your behalf).

`typescript fixture=default // Create a basic gateway with default MCP protocol and Cognito authorizer const gateway = new agentcore.Gateway(this, "MyGateway", { gatewayName: "my-gateway", });`

`$3`

Currently MCP is the only protocol available. To configure it, use the protocol property with McpProtocolConfiguration:

`$3`

`typescript fixture=default

IAM – Authorizes through the credentials of the AWS IAM identity trying to access the gateway.

`typescript fixture=default const gateway = new agentcore.Gateway(this, "MyGateway", { gatewayName: "my-gateway", authorizerConfiguration: agentcore.GatewayAuthorizer.usingAwsIam(), });

// Grant access to a Lambda function's role const lambdaRole = new iam.Role(this, "LambdaRole", { assumedBy: new iam.ServicePrincipal("lambda.amazonaws.com"), });

// The Lambda needs permission to invoke the gateway gateway.grantInvoke(lambdaRole);`

For more information, see Setting up Amazon Cognito for Gateway inbound authorization.

`typescript fixture=default // Create a gateway with default Cognito M2M authorizer const gateway = new agentcore.Gateway(this, "MyGateway", { gatewayName: "my-gateway", });

// Access the Cognito resources for authentication setup const userPool = gateway.userPool; const userPoolClient = gateway.userPoolClient;

Using Cognito User Pool Explicitly with Custom Claims – You can also use an existing Cognito User Pool with custom claims:

`typescript fixture=default declare const userPool: cognito.UserPool; declare const userPoolClient: cognito.UserPoolClient;

The following is an example of a token request using curl:

`$3`

You can provide a KMS key, and configure the authorizer as well as the protocol configuration.

@aws-cdk/aws-bedrock-agentcore-alpha

Amazon Bedrock AgentCore Construct Library

Table of contents

AgentCore Runtime

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Browser

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Code Interpreter

$3

$3

$3

$3

$3

$3

$3

$3

Gateway

$3

$3

$3

$3

$3

@aws-cdk/aws-bedrock-agentcore-alpha

Amazon Bedrock AgentCore Construct Library

Table of contents

AgentCore Runtime

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Browser

$3

$3

$3

$3

$3

$3

$3

$3

$3

$3

Code Interpreter

$3

$3

$3

$3

$3

$3

$3

$3

Gateway

$3

$3

$3

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Browser`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Code Interpreter`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Gateway`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Browser`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Code Interpreter`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`$3`

`Gateway`

`$3`

`$3`

`$3`

`$3`

`$3`