Bedrock AgentCore Runtime

Note: This documentation is also available in a rendered format here.

Deploys Amazon Bedrock AgentCore Runtimes with custom Docker containers, VPC networking, JWT authentication, and lifecycle management. Supports both pre-built ECR images and building from local source code. Use this module when you need to run custom AI agent logic in your own containers with full control over the runtime environment and authentication.

Deployed Resources

This module deploys and integrates the following resources:

Bedrock AgentCore Runtime — Custom agent runtime deployed in VPC mode. Supports Docker containers from ECR or built from source at deploy time.
Bedrock AgentCore Runtime Endpoint (Optional) — API endpoint for invoking the agent runtime via Bedrock AgentCore APIs.
ECR Docker Image Asset — Container image built and pushed to ECR at deploy time (when using codePath).
IAM Execution Role + Managed Policy — Runtime execution role with permissions for ECR image access, CloudWatch Logs, X-Ray tracing, CloudWatch Metrics, Bedrock AgentCore workload identity tokens, and Bedrock model invocation. Can use an existing role via roleArn or auto-create one.
CloudWatch Log Group — Log group for runtime execution logs.
SSM Parameters — Runtime ARN, Runtime ID, Runtime Name, and optionally Endpoint ARN/ID stored in Parameter Store for cross-module reference.

Bedrock Builder — Deploy managed Bedrock Agents as an alternative to custom AgentCore runtimes
Bedrock Settings — Configure Bedrock model invocation audit logging for runtime model calls
Roles — Create IAM execution roles for AgentCore runtimes

Security/Compliance Details

This module is designed in alignment with MDAA security/compliance principles and CDK nag rulesets. Additional review is recommended prior to production deployment, ensuring organization-specific compliance requirements are met.

Encryption at Rest:
- CloudWatch log groups encrypted per account settings
- Container images stored in ECR with default encryption
Encryption in Transit:
- All runtime API communications use TLS
- X-Ray tracing data transmitted securely
Least Privilege:
- Execution role scoped to specific permissions for ECR access, CloudWatch Logs, X-Ray, and Bedrock model invocation
- Supports using an existing role or auto-creating one with minimal required permissions
Network Isolation:
- Runtimes deployed in VPC mode with no public internet access unless explicitly configured via VPC routing
- JWT authentication (custom or standard) controls runtime endpoint access

AWS Service Endpoints

The following VPC endpoints may be required if public AWS service endpoint connectivity is unavailable (e.g., private subnets without NAT gateway, firewalled environments, or PrivateLink-only architectures):

AWS Service	Endpoint Service Name	Type
Bedrock AgentCore	`com.amazonaws.{region}.bedrock-agent-runtime`	Interface
Bedrock Runtime	`com.amazonaws.{region}.bedrock-runtime`	Interface
ECR API	`com.amazonaws.{region}.ecr.api`	Interface
ECR Docker	`com.amazonaws.{region}.ecr.dkr`	Interface
CloudWatch Logs	`com.amazonaws.{region}.logs`	Interface
SSM Parameter Store	`com.amazonaws.{region}.ssm`	Interface
STS	`com.amazonaws.{region}.sts`	Interface
S3	`com.amazonaws.{region}.s3`	Gateway
X-Ray	`com.amazonaws.{region}.xray`	Interface

Configuration

MDAA Config

Add the following snippet to your mdaa.yaml under the modules: section of a domain/env in order to use this module:

bedrock-agentcore-runtime: # Module Name can be customized
  module_path: '@aws-mdaa/bedrock-agentcore-runtime' # Must match module NPM package name
  module_configs:
    - ./bedrock-agentcore-runtime.yaml # Filename/path can be customized

Module Config Samples and Variants

Copy the contents of the relevant sample config below into the ./bedrock-agentcore-runtime.yaml file referenced in the MDAA config snippet above.

Minimal Configuration

Contains only required properties for deploying an agent runtime with a pre-built container image and VPC networking. Start here for a quick proof-of-concept runtime using an existing ECR image.

sample-config-minimal.yaml

# Contents available via above link
# Minimal Bedrock AgentCore Runtime module configuration.
# Contains only required properties for deploying an agent runtime
# with a pre-built container image and VPC networking.

# Unique name for the Bedrock AgentCore Runtime
agentRuntimeName: testAgentRuntime
# Container deployment configuration specifying Docker image source
agentRuntimeArtifact:
  # Container configuration for the agent runtime Docker image
  containerConfiguration:
    # Pre-built container image URI from ECR
    containerUri: '{{account}}.dkr.ecr.{{region}}.amazonaws.com/test-runtime:latest'
# VPC network configuration for secure runtime deployment
networkConfiguration:
  # Security group IDs controlling inbound/outbound traffic
  # Often created by your VPC/networking stack.
  # Example SSM: ssm:/path/to/security-group/id
  securityGroups:
    - sg-12345678
  # Subnet IDs for runtime instance placement
  # Often created by your VPC/networking stack.
  # Example SSM: ssm:/path/to/subnet/id
  subnets:
    - subnet-12345678
# (Optional) Protocol-level configuration for agent runtime
# communication. Defines which protocol the agent runtime uses
# to communicate with clients.
# Valid values: MCP | HTTP | A2A
protocolConfiguration: 'HTTP'

Comprehensive Configuration (Pre-built Container Image)

Deploys an agent runtime using a pre-built ECR container image with VPC networking, JWT authentication, IAM policies, header forwarding, and lifecycle management. Start here when evaluating all available options for securing and managing a production AgentCore runtime.

sample-config-comprehensive.yaml

# Contents available via above link
# Sample config for the Bedrock AgentCore Runtime module.
# Deploys an agent runtime using a pre-built ECR container image with
# VPC networking, JWT authentication, IAM policies, header forwarding,
# and lifecycle management.

# Unique name for the Bedrock AgentCore Runtime
agentRuntimeName: testAgentRuntime
# (Optional) Description of the agent runtime's purpose and functionality
description: 'Test agent runtime for unit testing'
# (Optional) Existing IAM role ARN for runtime execution. If omitted,
# a new role is created with appropriate permissions.
roleArn: 'arn:{{partition}}:iam::{{account}}:role/test-runtime-role'
# Container deployment configuration specifying Docker image source.
# Use containerUri for pre-built ECR images or codePath to build
# from source.
agentRuntimeArtifact:
  # Container configuration for the agent runtime Docker image
  containerConfiguration:
    # Pre-built container image URI from ECR.
    # Mutually exclusive with codePath.
    containerUri: '{{account}}.dkr.ecr.{{region}}.amazonaws.com/test-runtime:latest'
    # (Optional) Target platform architecture for Docker image builds
    # (default: linux/arm64)
    platform: 'linux/amd64'
# (Optional) Key-value environment variables passed to the agent
# runtime container
environmentVariables:
  ENVIRONMENT: test
  LOG_LEVEL: DEBUG
# VPC network configuration for secure runtime deployment. MDAA
# enforces VPC mode for all runtimes to ensure network isolation.
networkConfiguration:
  # Security group IDs controlling inbound/outbound traffic for
  # runtime instances (1-16 items)
  # Often created by your VPC/networking stack.
  # Example SSM: ssm:/path/to/security-group/id
  securityGroups:
    - sg-12345678
    - sg-87654321
  # Subnet IDs for runtime instance placement enabling multi-AZ
  # deployment (1-16 items)
  # Often created by your VPC/networking stack.
  # Example SSM: ssm:/path/to/subnet/id
  subnets:
    - subnet-12345678
    - subnet-87654321
    - subnet-abcdef12
# (Optional) Session timeout and maximum lifetime settings for
# runtime instances (values 60-28800 seconds)
lifecycleConfiguration:
  # (Optional) Idle session timeout in seconds before automatic
  # termination (60-28800)
  idleRuntimeSessionTimeout: 3600
  # (Optional) Maximum session lifetime in seconds before forced
  # termination regardless of activity (60-28800)
  maxLifetime: 7200
# (Optional) Authentication configuration with support for custom
# JWT authorizers via OIDC
authorizerConfiguration:
  # (Optional) Custom JWT authorizer for token-based authentication
  # via OIDC
  customJwtAuthorizer:
    # OIDC discovery URL for JWT token validation. Must end with
    # /.well-known/openid-configuration.
    discoveryUrl: 'https://cognito-idp.{{region}}.amazonaws.com/{{region}}_test/.well-known/openid-configuration'
    # (Optional) Allowed audience values for JWT token validation
    allowedAudience:
      - 'test-client-id'
    # (Optional) Allowed client IDs for JWT token validation
    allowedClients:
      - 'test-client-app-1'
      - 'test-client-app-2'
# (Optional) IAM policies to attach to the runtime execution role.
# Supports managed policy ARNs and inline policy documents
# (mutually exclusive per entry).
policies:
  # Policy using a managed policy ARN
  - # (Optional) ARN of an existing managed policy to attach to the
    # runtime role. Mutually exclusive with policyDocument.
    policyArn: 'arn:{{partition}}:iam::aws:policy/AmazonS3ReadOnlyAccess'
  # Policy using an inline policy document
  - # (Optional) Inline policy document for custom permissions on the
    # runtime role. Mutually exclusive with policyArn.
    policyDocument:
      # IAM policy statements (at least one required)
      Statement:
        - # (Optional) Statement identifier for tracking and management
          Sid: AllowS3Access
          # Effect of the policy statement (enum: Allow, Deny)
          Effect: Allow
          # IAM actions to allow or deny
          Action:
            - 's3:GetObject'
            - 's3:ListBucket'
          # AWS resource ARNs this statement applies to
          Resource:
            - 'arn:{{partition}}:s3:::test-bucket'
            - 'arn:{{partition}}:s3:::test-bucket/*'
          # (Optional) Conditions for when the policy statement is in effect
          Condition: {}
        - # Statement demonstrating Deny effect
          Sid: DenyUnencryptedUploads
          # Effect of the policy statement (enum: Allow, Deny)
          Effect: Deny
          # IAM actions to deny
          Action: 's3:PutObject'
          # AWS resource ARNs this statement applies to
          Resource: 'arn:{{partition}}:s3:::test-bucket/*'
          # (Optional) Conditions for when the policy statement is in effect
          Condition: {}
# (Optional) Protocol-level configuration for agent runtime
# communication. Defines which protocol the agent runtime uses
# to communicate with clients.
# Valid values: MCP | HTTP | A2A
protocolConfiguration: 'MCP'
# (Optional) HTTP headers to forward to agent runtime instances
# (1-20 headers)
requestHeaderConfiguration:
  # (Optional) HTTP header names to forward to the agent runtime
  requestHeaderAllowlist:
    - 'X-Custom-Header'
    - 'X-Request-Id'
  # (Optional) Allowed headers
  allowedHeaders:
    - 'Authorization'
    - 'Content-Type'
# (Optional) Endpoint configuration for invoking the agent runtime
# via Bedrock AgentCore API
runtimeEndpoint:
  # (Optional) Endpoint name for API access identification
  # (alphanumeric and underscores, max 48 chars)
  name: test_runtime_endpoint
  # (Optional) Description of the runtime endpoint
  description: 'Test runtime endpoint'
  # (Optional) Specific agent runtime version for the endpoint
  agentRuntimeVersion: '1.0.0'
# (Optional) Enable XRay Transaction Search Configuration (singleton per account-region)
enableTransactionSearch: true

Local Code Path Variant

Builds the container image from a local Dockerfile instead of referencing a pre-built ECR image. Choose this variant when developing custom agent runtimes from source code and you want CDK to build and push the image at deploy time. Also demonstrates the alternative jwtAuthorizer (vs customJwtAuthorizer in the comprehensive config).

sample-config-codepath.yaml

# Contents available via above link
# Variant config for Bedrock AgentCore Runtime using codePath.
# Builds the container image from a local Dockerfile instead of
# referencing a pre-built ECR image. Use this approach when
# developing custom agent runtimes from source code.

# Unique name for the Bedrock AgentCore Runtime
agentRuntimeName: testAgentRuntimeCodePath
# Container deployment configuration building from source code
agentRuntimeArtifact:
  # Container configuration for the agent runtime Docker image
  containerConfiguration:
    # Local directory path containing Dockerfile and agent code.
    # Mutually exclusive with containerUri.
    codePath: './runtime-src'
    # (Optional) Target platform architecture for Docker image builds
    # (default: linux/arm64)
    platform: 'linux/arm64'
# VPC network configuration for secure runtime deployment
networkConfiguration:
  # Security group IDs (1-16 items)
  # Often created by your VPC/networking stack.
  # Example SSM: ssm:/path/to/security-group/id
  securityGroups:
    - sg-12345678
  # Subnet IDs (1-16 items)
  # Often created by your VPC/networking stack.
  # Example SSM: ssm:/path/to/subnet/id
  subnets:
    - subnet-12345678
# (Optional) Protocol-level configuration for agent runtime
# communication. Defines which protocol the agent runtime uses
# to communicate with clients.
  # Valid values: MCP | HTTP | A2A
protocolConfiguration: 'MCP'
# (Optional) Authentication via jwtAuthorizer (alternative to
# customJwtAuthorizer)
authorizerConfiguration:
  # (Optional) JWT authorizer configuration for token-based
  # authentication via OIDC
  jwtAuthorizer:
    # OIDC discovery URL for JWT token validation
    discoveryUrl: 'https://cognito-idp.{{region}}.amazonaws.com/{{region}}_test/.well-known/openid-configuration'
    # (Optional) Allowed audience values for JWT token validation
    allowedAudience:
      - 'test-audience'
    # (Optional) Allowed client IDs for JWT token validation
    allowedClients:
      - 'test-client-app'

Troubleshooting

For common deployment issues and their solutions, see TROUBLESHOOTING.md.

Common issues:

X-Ray Transaction Search Config Already Exists - AlreadyExists error during deployment
Cross-Account ECR Access Denied - Failed to pull image error in cloudwatch logs

Config Schema Docs