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 Resource-Based Policy (Optional) — Resource-based policy restricting runtime invocations to traffic originating from the configured VPC. Created when enforceVpcOnly is true.
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.
KMS Key — Customer-managed encryption key for the CloudWatch log groups.
CloudWatch Data Protection Policy — PII masking policy applied to the log groups on ingestion. Extendable via dataProtection.additionalIdentifiers.
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 are always encrypted with a module-created customer-managed KMS key (built-in, cannot be disabled)
- CloudWatch Data Protection always masks a built-in comprehensive set of PII identifiers on log ingestion (built-in, cannot be disabled; extendable via dataProtection.additionalIdentifiers)
- 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:
  # (Optional) VPC ID for resource-based policy condition.
  # Required when enforceVpcOnly is true.
  vpcId: vpc-0123456789abcdef0
  # 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
# (Optional) Enforce VPC-only invocation via resource-based policy.
# Requires networkConfiguration.vpcId when true.
enforceVpcOnly: true
# (Optional) CloudWatch Logs retention period in days for the runtime log group.
logRetentionDays: 90
# CMK encryption and CloudWatch Data Protection (PII masking) are always-on,
# built-in behavior for this module and cannot be disabled. The built-in set
# (EmailAddress, CreditCardNumber, Ssn-US, Name, Address, PhoneNumber-US,
# IpAddress) is always masked; users with logs:Unmask can still access unmasked data.
# (Optional) Add extra data identifiers on top of the built-in set. This is
# additive only — it cannot remove or weaken the built-in masking.
dataProtection:
  additionalIdentifiers:
    - 'DriversLicense-US'
    - 'PassportNumber-US'

Model-Scoped Permissions Variant

Restricts the execution role's Bedrock model invocation permissions to specific model ARNs. Choose this variant when you need least-privilege access — for example, limiting agents to specific models for cost control, compliance, or blast radius reduction.

sample-config-model-scoped.yaml

# Contents available via above link
# Bedrock AgentCore Runtime configuration with model ARN scoping.
# Demonstrates restricting the execution role's Bedrock model invocation
# permissions to specific model ARNs (least privilege).

# 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
  securityGroups:
    - sg-12345678
  # Subnet IDs for runtime instance placement
  subnets:
    - subnet-12345678
# IAM resource ARN patterns for Bedrock model invocation.
# Supports wildcards. When omitted, all foundation models are allowed (broad default).
allowedModelArns:
  - 'arn:{{partition}}:bedrock:{{region}}::foundation-model/anthropic.claude-sonnet-4-6-20250514-v1:0'
  - 'arn:{{partition}}:bedrock:{{region}}::foundation-model/anthropic.claude-haiku-*'
# Protocol configuration
protocolConfiguration: 'HTTP'

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'

VPC-Only Enforcement Variant

Restricts runtime invocations to traffic originating from the configured VPC using a resource-based policy. Choose this variant when JWT/OAuth callers must be restricted to VPC-only access — SCPs and VPC endpoint policies cannot restrict non-IAM principals, so a resource-based policy with an aws:SourceVpc condition is required.

sample-config-resource-policy.yaml

# Contents available via above link
# Bedrock AgentCore Runtime with VPC-only enforcement.
# Demonstrates restricting JWT/OAuth callers to VPC-only invocation.
#
# Why: SCPs and VPC endpoint policies cannot restrict OAuth/JWT callers
# because they are not IAM principals. MDAA auto-generates a resource-based
# policy with an aws:SourceVpc condition to enforce this restriction.

# Unique name for the Bedrock AgentCore Runtime
agentRuntimeName: testAgentRuntime
# Container deployment configuration
agentRuntimeArtifact:
  containerConfiguration:
    containerUri: '{{account}}.dkr.ecr.{{region}}.amazonaws.com/test-runtime:latest'
# VPC network configuration for secure runtime deployment.
# vpcId is required when enforceVpcOnly is true.
networkConfiguration:
  vpcId: vpc-0123456789abcdef0
  securityGroups:
    - sg-12345678
  subnets:
    - subnet-12345678
    - subnet-87654321
# JWT authentication configuration
authorizerConfiguration:
  customJwtAuthorizer:
    discoveryUrl: 'https://cognito-idp.{{region}}.amazonaws.com/{{region}}_test/.well-known/openid-configuration'
    allowedAudience:
      - 'test-client-id'
# Enforce VPC-only invocation. MDAA auto-generates a resource-based policy
# restricting invocations to traffic from the VPC specified above.
enforceVpcOnly: true

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