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

Language	Package
.NET	Amazon.CDK.AWS.Bedrock.Agentcore.Alpha
Go	github.com/aws/aws-cdk-go/awsbedrockagentcorealpha/v2
Java	software.amazon.awscdk.services.bedrock.agentcore.alpha
Python	aws_cdk.aws_bedrock_agentcore_alpha
TypeScript	@aws-cdk/aws-bedrock-agentcore-alpha

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

Table of contents

• AgentCore Runtime
  • Runtime Versioning
  • Runtime Endpoints
  • AgentCore Runtime Properties
  • Runtime Endpoint Properties
  • Creating a Runtime
    • Option 1: Use an existing image in ECR
    • Managing Endpoints and Versions
    • Option 2: Use a local asset
• Browser Custom tool
  • Browser properties
  • Browser Network modes
  • Basic Browser Creation
  • Browser IAM permissions
• Code Interpreter Custom tool
  • Code Interpreter properties
  • Code Interpreter Network Modes
  • Basic Code Interpreter Creation
  • Code Interpreter IAM permissions
• Gateway
  • Gateway Properties
  • Basic Gateway Creation
  • Protocol configuration
  • Inbound authorization
  • Gateway with KMS Encryption
  • Gateway with Custom Execution Role
  • Gateway IAM Permissions
• Gateway Target
  • Gateway Target Properties
  • Targets types
  • Outbound auth
  • Api schema
  • Basic Gateway Target Creation
    • Using addTarget methods (Recommended)
    • Using static factory methods
  • Lambda Target with Tool Schema
  • Smithy Model Target with OAuth
  • Gateway Target IAM Permissions
• Memory
  • Memory properties
  • Basic Memory Creation
  • LTM Memory Extraction Stategies
  • Memory Strategy Methods
• Amazon Bedrock AgentCore Construct Library
  • Table of contents
  • AgentCore Runtime
    • Runtime Endpoints
    • AgentCore Runtime Properties
    • Runtime Endpoint Properties
    • Creating a Runtime
      • Option 1: Use an existing image in ECR
      • Option 2: Use a local asset
      • Option 3: Use direct code deployment
    • Granting Permissions to Invoke Bedrock Models or Inference Profiles
    • Runtime Versioning
      • Managing Endpoints and Versions
        • Step 1: Initial Deployment
        • Step 2: Creating Custom Endpoints
        • Step 3: Runtime Update Deployment
        • Step 4: Testing with Staging Endpoints
        • Step 5: Promoting to Production
    • Creating Standalone Runtime Endpoints
      • Example: Creating an endpoint for an existing runtime
    • Runtime Authentication Configuration
      • IAM Authentication (Default)
      • Cognito Authentication
      • JWT Authentication
      • OAuth Authentication
      • Using a Custom IAM Role
    • Runtime Network Configuration
      • Public Network Mode (Default)
      • VPC Network Mode
      • Managing Security Groups with VPC Configuration
  • Browser
    • Browser Network modes
    • Browser Properties
    • Basic Browser Creation
    • Browser with Tags
    • Browser with VPC
    • Browser with Recording Configuration
    • Browser with Custom Execution Role
    • Browser with S3 Recording and Permissions
    • Browser IAM Permissions
  • Code Interpreter
    • Code Interpreter Network Modes
    • Code Interpreter Properties
    • Basic Code Interpreter Creation
    • Code Interpreter with VPC
    • Code Interpreter with Sandbox Network Mode
    • Code Interpreter with Custom Execution Role
    • Code Interpreter IAM Permissions
    • Code interpreter with tags
  • Memory
    • Memory Properties
    • Basic Memory Creation
    • LTM Memory Extraction Stategies
    • Memory with Built-in Strategies
    • Memory with custom Strategies
      • Memory with Custom Execution Role
    • Memory with self-managed Strategies
    • Memory Strategy Methods

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.

Runtime Endpoints

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.

AgentCore Runtime Properties

Name	Type	Required	Description
runtimeName	string	Yes	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
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

Runtime Endpoint Properties

Name	Type	Required	Description
endpointName	string	Yes	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
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

Creating a Runtime

Option 1: Use an existing image in ECR

Reference an image available within ECR.

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

Example not in your language?

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.

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

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

Example not in your language?

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.

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

Example not in your language?

Granting Permissions to Invoke Bedrock Models or Inference Profiles

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

// 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);

Example not in your language?

Runtime Versioning

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.

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

Example not in your language?

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.

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

Example not in your language?

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

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

Example not in your language?

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.

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

Example not in your language?

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.

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

Example not in your language?

Creating Standalone Runtime Endpoints

RuntimeEndpoint can also be created as a standalone resource.

Example: Creating an endpoint for an existing runtime

// 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"
});

Example not in your language?

Runtime Authentication Configuration

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:

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");

const runtime = new agentcore.Runtime(this, "MyAgentRuntime", {
  runtimeName: "myAgent",
  agentRuntimeArtifact: agentRuntimeArtifact,
  authorizerConfiguration: agentcore.RuntimeAuthorizerConfiguration.usingCognito(
    userPool, // User Pool (required)
    [userPoolClient, anotherUserPoolClient], // User Pool Clients
  ),
});

Example not in your language?

JWT Authentication

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

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

Example not in your language?

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

OAuth Authentication

To configure OAuth 2.0 authentication:

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.usingOAuth(
    "https://github.com/.well-known/openid-configuration",
    "oauth_client_123",
  ),
});

Example not in your language?

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.

Runtime Network Configuration

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:

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

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

Example not in your language?

VPC Network Mode

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

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

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

Example not in your language?

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:

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

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

// 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');

Example not in your language?

Runtime IAM Permissions

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

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

// 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/*'],
}));

Example not in your language?

Other configuration

Lifecycle configuration

The LifecycleConfiguration input parameter to CreateAgentRuntime lets you manage the lifecycle of runtime sessions and resources in Amazon Bedrock AgentCore Runtime. This configuration helps optimize resource utilization by automatically cleaning up idle sessions and preventing long-running instances from consuming resources indefinitely.

You can configure:

• idleRuntimeSessionTimeout: Timeout in seconds for idle runtime sessions. When a session remains idle for this duration, it will trigger termination. Termination can last up to 15 seconds due to logging and other process completion. Default: 900 seconds (15 minutes)
• maxLifetime: Maximum lifetime for the instance in seconds. Once reached, instances will initialize termination. Termination can last up to 15 seconds due to logging and other process completion. Default: 28800 seconds (8 hours)

For additional information, please refer to the documentation.

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

Example not in your language?

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.

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

Example not in your language?

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

Browser Network modes

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.

Browser Properties

Name	Type	Required	Description
browserCustomName	string	Yes	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}
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

Basic Browser Creation

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

Example not in your language?

Browser with Tags

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

Example not in your language?

Browser with VPC

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

Example not in your language?

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:

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

Example not in your language?

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.

Browser with Recording Configuration

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

Example not in your language?

Browser with Custom Execution Role

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

Example not in your language?

Browser with S3 Recording and Permissions

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

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

Example not in your language?

Browser with Browser signing

AI agents need to browse the web on your behalf. When your agent visits a website to gather information, complete a form, or verify data, it encounters the same defenses designed to stop unwanted bots: CAPTCHAs, rate limits, and outright blocks.

Amazon Bedrock AgentCore Browser supports Web Bot Auth. Web Bot Auth is a draft IETF protocol that gives agents verifiable cryptographic identities. When you enable Web Bot Auth in AgentCore Browser, the service issues cryptographic credentials that websites can verify. The agent presents these credentials with every request. The WAF may now additionally check the signature, confirm it matches a trusted directory, and allow the request through if verified bots are allowed by the domain owner and other WAF checks are clear.

To enable the browser to sign requests using the Web Bot Auth protocol, create a browser tool with the browserSigning configuration:

const browser = new agentcore.BrowserCustom(this, 'test-browser', {
  browserCustomName: 'test_browser',
  browserSigning: agentcore.BrowserSigning.ENABLED
});

Example not in your language?

Browser IAM Permissions

The Browser construct provides convenient methods for granting IAM permissions:

// 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");

Example not in your language?

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

Code Interpreter Network Modes

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.

   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.

Code Interpreter Properties

Name	Type	Required	Description
codeInterpreterCustomName	string	Yes	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}
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

Basic Code Interpreter Creation

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

Example not in your language?

Code Interpreter with VPC

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

Example not in your language?

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:

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

Example not in your language?

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.

Code Interpreter with Sandbox Network Mode

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

Example not in your language?

Code Interpreter with Custom Execution Role

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

Example not in your language?

Code Interpreter IAM Permissions

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

// 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");

Example not in your language?

Code interpreter with tags

// 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.usingPublicNetwork(),
  tags: {
    Environment: "Production",
    Team: "AI/ML",
    Project: "AgentCore",
  },
});

Example not in your language?

Gateway

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

Gateway Properties

Name	Type	Required	Description
gatewayName	string	Yes	The name of the gateway. Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen). Maximum 100 characters
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

Basic Gateway Creation

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

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

Example not in your language?

Protocol configuration

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

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

Example not in your language?

Inbound authorization

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 inboundAuthorizer 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

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

Example not in your language?

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

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

Example not in your language?

Gateway with KMS Encryption

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

// 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: agentcore.GatewayAuthorizer.usingCustomJwt({
    discoveryUrl: "https://auth.example.com/.well-known/openid-configuration",
    allowedAudience: ["my-app"],
    allowedClients: ["my-client-id"],
  }),
  kmsKey: encryptionKey,
  exceptionLevel: agentcore.GatewayExceptionLevel.DEBUG,
});

Example not in your language?

Gateway with Custom Execution Role

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

// Create gateway with custom execution role
const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
  description: "Gateway with custom execution role",
  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: agentcore.GatewayAuthorizer.usingCustomJwt({
    discoveryUrl: "https://auth.example.com/.well-known/openid-configuration",
    allowedAudience: ["my-app"],
    allowedClients: ["my-client-id"],
  }),
  role: executionRole,
});

Example not in your language?

Gateway IAM Permissions

The Gateway construct provides convenient methods for granting IAM permissions:

// Create a gateway
const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
  description: "Gateway for external service integration",
  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: agentcore.GatewayAuthorizer.usingCustomJwt({
    discoveryUrl: "https://auth.example.com/.well-known/openid-configuration",
    allowedAudience: ["my-app"],
    allowedClients: ["my-client-id"],
  }),
});

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

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

// Grant manage permissions (Create, Update, Delete actions)
gateway.grantManage(userRole);

// Grant specific custom permissions
gateway.grant(userRole, "bedrock-agentcore:GetGateway");

Example not in your language?

Gateway Target

After Creating gateways, you can add targets which define the tools that your gateway will host. Gateway supports multiple target types including Lambda functions and API specifications (either OpenAPI schemas or Smithy models). Gateway allows you to attach multiple targets to a Gateway and you can change the targets / tools attached to a gateway at any point. Each target can have its own credential provider attached enabling you to securely access targets whether they need IAM, API Key, or OAuth credentials.

Gateway Target Properties

Name	Type	Required	Description
gatewayTargetName	string	Yes	The name of the gateway target. Valid characters are a-z, A-Z, 0-9, _ (underscore) and - (hyphen)
description	string	No	Optional description for the gateway target. Maximum 200 characters
gateway	IGateway	Yes	The gateway this target belongs to
targetConfiguration	ITargetConfiguration	Yes	The target configuration (Lambda, OpenAPI, or Smithy). Note: Users typically don't create this directly. When using convenience methods like GatewayTarget.forLambda(), GatewayTarget.forOpenApi(), GatewayTarget.forSmithy() or the gateway's addLambdaTarget(), addOpenApiTarget(), addSmithyTarget() methods, this configuration is created internally for you. Only needed when using the GatewayTarget constructor directly for advanced scenarios.
credentialProviderConfigurations	IGatewayCredentialProvider[]	No	Credential providers for authentication. Defaults to [GatewayCredentialProvider.fromIamRole()]. Use GatewayCredentialProvider.fromApiKeyIdentityArn(), GatewayCredentialProvider.fromOauthIdentityArn(), or GatewayCredentialProvider.fromIamRole()
validateOpenApiSchema	boolean	No	(OpenAPI targets only) Whether to validate the OpenAPI schema at synthesis time. Defaults to true. Only applies to inline and local asset schemas. For more information refer here https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway-schema-openapi.html

This approach gives you full control over the configuration but is typically not necessary for most use cases.

Targets types

You can create the following targets types:

Lambda Target: Lambda targets allow you to connect your gateway to AWS Lambda functions that implement your tools. This is useful when you want to execute custom code in response to tool invocations.

• Supports GATEWAY_IAM_ROLE credential provider only
• Ideal for custom serverless function integration
• Need tool schema (tool schema is a blueprint that describes the functions your Lambda provides to AI agents). The construct provide 3 ways to upload a tool schema to Lambda target
• When using the default IAM authentication (no credentialProviderConfigurations specified), the construct automatocally grants the gateway role permission to invoke your Lambda function (lambda:InvokeFunction).

OpenAPI Schema Target : OpenAPI widely used standard for describing RESTful APIs. Gateway supports OpenAPI 3.0 specifications for defining API targets. It connects to REST APIs using OpenAPI specifications

• Supports OAUTH and API_KEY credential providers (Do not support IAM, you must provide credentialProviderConfigurations)
• Ideal for integrating with external REST services
• Need API schema. The construct provide 3 ways to upload a API schema to OpenAPI target

Smithy Model Target : Smithy is a language for defining services and software development kits (SDKs). Smithy models provide a more structured approach to defining APIs compared to OpenAPI, and are particularly useful for connecting to AWS services. AgentCore Gateway supports built-in AWS service models only. It connects to services using Smithy model definitions

• Supports OAUTH and API_KEY credential providers
• Ideal for AWS service integrations
• Need API schema. The construct provide 3 ways to upload a API schema to Smity target
• When using the default IAM authentication (no credentialProviderConfigurations specified), The construct only grants permission to read the Smithy schema file from S3. You MUST manually grant permissions for the gateway role to invoke the actual Smithy API endpoints

Note: For Smithy model targets that access AWS services, your Gateway's execution role needs permissions to access those services. For example, for a DynamoDB target, your execution role needs permissions to perform DynamoDB operations. This is not managed by the construct due to the large number of options. Please refer to Smithy Model Permission for example.

MCP Server Target: Model Context Protocol (MCP) servers provide external tools, data access, and custom functions for AI agents. MCP servers enable agents to interact with external systems and services through a standardized protocol. Gateway automatically discovers and indexes available tools from MCP servers through synchronization.

Key Features:

• Requires explicit authentication configuration (OAuth2 recommended, empty array for NoAuth)
• Ideal for connecting to external MCP-compliant servers
• The endpoint must use HTTPS protocol
• Supported MCP protocol versions: 2025-06-18, 2025-03-26
• Automatic tool discovery through synchronization

Synchronization Behavior:

MCP Server targets require synchronization to discover and index available tools:

• Implicit Synchronization (Automatic): Tool discovery happens automatically during:

  • Target creation (CreateGatewayTarget)
  • Target updates (UpdateGatewayTarget)
  • The Gateway calls the MCP server's tools/list endpoint and indexes tools without user intervention

• Explicit Synchronization (Manual): When the MCP server's tools change independently (new tools added, schemas modified, tools removed):

  • The Gateway's tool catalog becomes stale
  • Call the SynchronizeGatewayTargets API to refresh the catalog
  • Use the grantSync() method to grant permissions to Lambda functions, CI/CD pipelines, or scheduled tasks that will trigger synchronization

Authentication & Permissions:

When using OAuth2, the Gateway service role automatically receives:

• bedrock-agentcore:GetWorkloadAccessToken
• bedrock-agentcore:GetResourceOauth2Token
• secretsmanager:GetSecretValue
• KMS decrypt (if secrets are encrypted)

For explicit synchronization, use grantSync() to grant bedrock-agentcore:SynchronizeGatewayTargets permission to your operator roles.

For more information, refer to the MCP Server Target documentation.

Understanding Tool Naming

When tools are exposed through gateway targets, AgentCore Gateway prefixes each tool name with the target name to ensure uniqueness across multiple targets. This is important to understand when building your application logic.

Naming Pattern:

Example:

If your target is named my-lambda-target and provides a tool called calculate_price, agents will discover and invoke it as my-lambda-target__calculate_price.

Important Considerations:

• For Lambda Targets: Your Lambda handler must strip the target name prefix before processing the tool request. The full tool name (with prefix) is sent in the event.
• For MCP Server Targets: The MCP server receives tool calls with the prefixed name from the gateway.
• For OpenAPI/Smithy Targets: The gateway handles the prefix automatically when mapping to API operations based on the operationId.

This naming convention ensures that:

• Tools from different targets don't collide even if they have the same name
• Agents can access tools from multiple targets through a single gateway
• Tool names remain unique in the unified tool catalog

For more details, see the Gateway Tool Naming Documentation.

Tools schema For Lambda target

The lambda target need tools schema to understand the fuunction lambda provides. You can upload the tool schema by following 3 ways:

• From a local asset file

const toolSchema = agentcore.ToolSchema.fromLocalAsset(
    path.join(__dirname, "schemas", "my-tool-schema.json")
  );

Example not in your language?

• From an existing S3 file:

const toolSchema = agentcore.ToolSchema.fromS3File(
    s3.Bucket.fromBucketName(this, "SchemasBucket", "my-schemas-bucket"),
    "tools/complex-tool-schema.json",
    "123456789012"
  );

Example not in your language?

• From Inline:

const toolSchema = agentcore.ToolSchema.fromInline([{
      name: "hello_world",
      description: "A simple hello world tool",
      inputSchema: {
        type: agentcore.SchemaDefinitionType.OBJECT,
        properties: {
          name: {
            type: agentcore.SchemaDefinitionType.STRING,
            description: "The name to greet",
          },
        },
        required: ["name"],
      },
    }]);

Example not in your language?

Api schema For OpenAPI and Smithy target

The OpenAPI and Smithy target need API Schema. The Gateway construct provide three ways to upload API schema for your target:

• From a local asset file (requires binding to scope):

// When using ApiSchema.fromLocalAsset, you must bind the schema to a scope
const schema = agentcore.ApiSchema.fromLocalAsset(path.join(__dirname, "mySchema.yml"));

schema.bind(this);

Example not in your language?

• From an inline schema:

const inlineSchema = agentcore.ApiSchema.fromInline(`
openapi: 3.0.3
info:
  title: Library API
  version: 1.0.0
paths:
  /search:
    get:
      summary: Search for books
      operationId: searchBooks
      parameters:
        - name: query
          in: query
          required: true
          schema:
            type: string
`);

Example not in your language?

• From an existing S3 file:

const bucket = s3.Bucket.fromBucketName(this, "ExistingBucket", "my-schema-bucket");
const s3Schema = agentcore.ApiSchema.fromS3File(bucket, "schemas/action-group.yaml");

Example not in your language?

Outbound auth

Outbound authorization lets Amazon Bedrock AgentCore gateways securely access gateway targets on behalf of users authenticated and authorized during Inbound Auth.

AgentCore Gateway supports the following types of outbound authorization:

IAM-based outbound authorization – The gateway uses its execution role to authenticate with AWS services. This is the default and most common approach for Lambda targets and AWS service integrations.

2-legged OAuth (OAuth 2LO) – Use OAuth 2.0 two-legged flow (2LO) for targets that require OAuth authentication. The gateway authenticates on its own behalf, not on behalf of a user.

API key – Use the AgentCore service/AWS console to generate an API key to authenticate access to the gateway target.

**Note > You need to set up the outbound identity before you can create a gateway target.

Basic Gateway Target Creation

You can create targets in two ways: using the static factory methods on GatewayTarget or using the convenient addTarget methods on the gateway instance.

Using addTarget methods (Recommended)

Below are the examples on how you can create Lambda , Smity and OpenAPI target using addTarget method.

// Create a gateway first
const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

const lambdaFunction = new lambda.Function(this, "MyFunction", {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: "index.handler",
  code: lambda.Code.fromInline(`
    exports.handler = async (event) => {
      return {
        statusCode: 200,
        body: JSON.stringify({ message: 'Hello from Lambda!' })
      };
    };
  `),
});

const lambdaTarget = gateway.addLambdaTarget("MyLambdaTarget", {
  gatewayTargetName: "my-lambda-target",
  description: "Lambda function target",
  lambdaFunction: lambdaFunction,
  toolSchema: agentcore.ToolSchema.fromInline([
    {
      name: "hello_world",
      description: "A simple hello world tool",
      inputSchema: {
        type: agentcore.SchemaDefinitionType.OBJECT,
        properties: {
          name: {
            type: agentcore.SchemaDefinitionType.STRING,
            description: "The name to greet",
          },
        },
        required: ["name"],
      },
    },
  ]),
});

Example not in your language?

• OpenAPI Target

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

// These ARNs are returned when creating the API key credential provider via Console or API
const apiKeyProviderArn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/abc123/apikeycredentialprovider/my-apikey"
const apiKeySecretArn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-apikey-secret-abc123"

const bucket = s3.Bucket.fromBucketName(this, "ExistingBucket", "my-schema-bucket");
const s3mySchema = agentcore.ApiSchema.fromS3File(bucket, "schemas/myschema.yaml");

// Add an OpenAPI target directly to the gateway
const target = gateway.addOpenApiTarget("MyTarget", {
  gatewayTargetName: "my-api-target",
  description: "Target for external API integration",
  apiSchema: s3mySchema,
  credentialProviderConfigurations: [
    agentcore.GatewayCredentialProvider.fromApiKeyIdentityArn({
      providerArn: apiKeyProviderArn,
      secretArn: apiKeySecretArn,
      credentialLocation: agentcore.ApiKeyCredentialLocation.header({
        credentialParameterName: "X-API-Key",
      }),
    }),
  ],
});

// This make sure your s3 bucket is available before target
target.node.addDependency(bucket);

Example not in your language?

• Smithy Target

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

const smithySchema = agentcore.ApiSchema.fromLocalAsset(
  path.join(__dirname, "models", "smithy-model.json")
);
smithySchema.bind(this);

const smithyTarget = gateway.addSmithyTarget("MySmithyTarget", {
  gatewayTargetName: "my-smithy-target",
  description: "Smithy model target",
  smithyModel: smithySchema,

});

Example not in your language?

• MCP Server Target

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

// OAuth2 authentication (recommended)
// Note: Create the OAuth provider using AWS console or Identity L2 construct when available
const oauthProviderArn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/abc123/oauth2credentialprovider/my-oauth";
const oauthSecretArn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-oauth-secret-abc123";

// Add an MCP server target directly to the gateway
const mcpTarget = gateway.addMcpServerTarget("MyMcpServer", {
  gatewayTargetName: "my-mcp-server",
  description: "External MCP server integration",
  endpoint: "https://my-mcp-server.example.com",
  credentialProviderConfigurations: [
    agentcore.GatewayCredentialProvider.fromOauthIdentityArn({
      providerArn: oauthProviderArn,
      secretArn: oauthSecretArn,
      scopes:['mcp-runtime-server/invoke']
    }),
  ],
});

// Grant sync permission to a Lambda function that will trigger synchronization
const syncFunction = new lambda.Function(this, "SyncFunction", {
  runtime: lambda.Runtime.PYTHON_3_12,
  handler: "index.handler",
  code: lambda.Code.fromInline(`
import boto3

def handler(event, context):
    client = boto3.client('bedrock-agentcore')
    response = client.synchronize_gateway_targets(
        gatewayIdentifier=event['gatewayId'],
        targetIds=[event['targetId']]
    )
    return response
  `),
});

mcpTarget.grantSync(syncFunction);

Example not in your language?

Using static factory methods

Create Gateway target using static convienence method.

• Lambda Target

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

const lambdaFunction = new lambda.Function(this, "MyFunction", {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: "index.handler",
  code: lambda.Code.fromInline(`
        exports.handler = async (event) => {
            return {
                statusCode: 200,
                body: JSON.stringify({ message: 'Hello from Lambda!' })
            };
        };
    `),
});

// Create a gateway target with Lambda and tool schema
const target = agentcore.GatewayTarget.forLambda(this, "MyLambdaTarget", {
  gatewayTargetName: "my-lambda-target",
  description: "Target for Lambda function integration",
  gateway: gateway,
  lambdaFunction: lambdaFunction,
  toolSchema: agentcore.ToolSchema.fromLocalAsset(
    path.join(__dirname, "schemas", "my-tool-schema.json")
  ),
});

Example not in your language?

• OpenAPI Target

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

// outbound auth (Use AWS console to create it, Once Identity L2 construct is available you can use it to create identity)
const apiKeyIdentityArn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/abc123/apikeycredentialprovider/my-apikey"
const apiKeySecretArn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-apikey-secret-abc123"

const opneapiSchema = agentcore.ApiSchema.fromLocalAsset(path.join(__dirname, "mySchema.yml"));
opneapiSchema.bind(this);

// Create a gateway target with OpenAPI Schema
const target = agentcore.GatewayTarget.forOpenApi(this, "MyTarget", {
  gatewayTargetName: "my-api-target",
  description: "Target for external API integration",
  gateway: gateway,  // Note: you need to pass the gateway reference
  apiSchema: opneapiSchema,
  credentialProviderConfigurations: [
    agentcore.GatewayCredentialProvider.fromApiKeyIdentityArn({
     providerArn: apiKeyIdentityArn,
     secretArn: apiKeySecretArn
    }),
  ],
});

Example not in your language?

• Smithy Target

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

const smithySchema = agentcore.ApiSchema.fromLocalAsset(
  path.join(__dirname, "models", "smithy-model.json")
);
smithySchema.bind(this);

// Create a gateway target with Smithy Model and OAuth
const target = agentcore.GatewayTarget.forSmithy(this, "MySmithyTarget", {
  gatewayTargetName: "my-smithy-target",
  description: "Target for Smithy model integration",
  gateway: gateway,
  smithyModel: smithySchema,
});

Example not in your language?

• MCP Server Target

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

// OAuth2 authentication (recommended)
// Note: Create the OAuth provider using AWS console or Identity L2 construct when available
const oauthProviderArn = "arn:aws:bedrock-agentcore:us-east-1:123456789012:token-vault/abc123/oauth2credentialprovider/my-oauth";
const oauthSecretArn = "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-oauth-secret-abc123";

// Create a gateway target with MCP Server
const mcpTarget = agentcore.GatewayTarget.forMcpServer(this, "MyMcpServer", {
  gatewayTargetName: "my-mcp-server",
  description: "External MCP server integration",
  gateway: gateway,
  endpoint: "https://my-mcp-server.example.com",
  credentialProviderConfigurations: [
    agentcore.GatewayCredentialProvider.fromOauthIdentityArn({
      providerArn: oauthProviderArn,
      secretArn: oauthSecretArn,
      scopes:['mcp-runtime-server/invoke']
    }),
  ],
});

Example not in your language?

Advanced Usage: Direct Configuration for gateway target

For advanced use cases where you need full control over the target configuration, you can create configurations manually using the static factory methods and use the GatewayTarget constructor directly.

Configuration Factory Methods

Each target type has a corresponding configuration class with a static create() method:

• Lambda: LambdaTargetConfiguration.create(lambdaFunction, toolSchema)
• OpenAPI: OpenApiTargetConfiguration.create(apiSchema, validateSchema?)
• Smithy: SmithyTargetConfiguration.create(smithyModel)

Example: Lambda Target with Custom Configuration

const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

const myLambdaFunction = new lambda.Function(this, "MyFunction", {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: "index.handler",
  code: lambda.Code.fromInline(`
    exports.handler = async (event) => ({ statusCode: 200 });
  `),
});

const myToolSchema = agentcore.ToolSchema.fromInline([{
  name: "my_tool",
  description: "My custom tool",
  inputSchema: {
    type: agentcore.SchemaDefinitionType.OBJECT,
    properties: {},
  },
}]);

// Create a custom Lambda configuration
const customConfig = agentcore.LambdaTargetConfiguration.create(
  myLambdaFunction,
  myToolSchema
);

// Use the GatewayTarget constructor directly
const target = new agentcore.GatewayTarget(this, "AdvancedTarget", {
  gateway: gateway,
  gatewayTargetName: "advanced-target",
  targetConfiguration: customConfig,  // Manually created configuration
  credentialProviderConfigurations: [
    agentcore.GatewayCredentialProvider.fromIamRole()
  ]
});

Example not in your language?

This approach gives you full control over the configuration but is typically not necessary for most use cases. The convenience methods (GatewayTarget.forLambda(), GatewayTarget.forOpenApi(), GatewayTarget.forSmithy()) handle all of this internally.

Gateway Target IAM Permissions

The Gateway Target construct provides convenient methods for granting IAM permissions:

// Create a gateway and target
const gateway = new agentcore.Gateway(this, "MyGateway", {
  gatewayName: "my-gateway",
});

const smithySchema = agentcore.ApiSchema.fromLocalAsset(
  path.join(__dirname, "models", "smithy-model.json")
);
smithySchema.bind(this);

// Create a gateway target with Smithy Model and OAuth
const target = agentcore.GatewayTarget.forSmithy(this, "MySmithyTarget", {
  gatewayTargetName: "my-smithy-target",
  description: "Target for Smithy model integration",
  gateway: gateway,
  smithyModel: smithySchema,
});

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

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

// Grant manage permissions (Create, Update, Delete actions)
target.grantManage(userRole);

// Grant specific custom permissions
target.grant(userRole, "bedrock-agentcore:GetGatewayTarget");

// Grants permission to invoke this Gateway
gateway.grantInvoke(userRole);

Example not in your language?

Memory

Memory is a critical component of intelligence. While Large Language Models (LLMs) have impressive capabilities, they lack persistent memory across conversations. Amazon Bedrock AgentCore Memory addresses this limitation by providing a managed service that enables AI agents to maintain context over time, remember important facts, and deliver consistent, personalized experiences.

AgentCore Memory operates on two levels:

• Short-Term Memory: Immediate conversation context and session-based information that provides continuity within a single interaction or closely related sessions.
• Long-Term Memory: Persistent information extracted and stored across multiple conversations, including facts, preferences, and summaries that enable personalized experiences over time.

When you interact with the memory via the CreateEvent API, you store interactions in Short-Term Memory (STM) instantly. These interactions can include everything from user messages, assistant responses, to tool actions.

To write to long-term memory, you need to configure extraction strategies which define how and where to store information from conversations for future use. These strategies are asynchronously processed from raw events after every few turns based on the strategy that was selected. You can't create long term memory records directly, as they are extracted asynchronously by AgentCore Memory.

Memory Properties

Name	Type	Required	Description
memoryName	string	Yes	The name of the memory
expirationDuration	Duration	No	Short-term memory expiration in days (between 7 and 365). Default: 90 days
description	string	No	Optional description for the memory. Default: no description.
kmsKey	IKey	No	Custom KMS key to use for encryption. Default: Your data is encrypted with a key that AWS owns and manages for you
memoryStrategies	MemoryStrategyBase[]	No	Built-in extraction strategies to use for this memory. Default: No extraction strategies (short term memory only)
executionRole	iam.IRole	No	The IAM role that provides permissions for the memory to access AWS services. Default: A new role will be created.
tags	{ [key: string]: string }	No	Tags for memory. Default: no tags.

Basic Memory Creation

Below you can find how to configure a simple short-term memory (STM) with no long-term memory extraction strategies. Note how you set expirationDuration, which defines the time the events will be stored in the short-term memory before they expire.

// Create a basic memory with default settings, no LTM strategies
const memory = new agentcore.Memory(this, "MyMemory", {
  memoryName: "my_memory",
  description: "A memory for storing user interactions for a period of 90 days",
  expirationDuration: cdk.Duration.days(90),
});

Example not in your language?

Basic Memory with Custom KMS Encryption

// Create a custom KMS key for encryption
const encryptionKey = new kms.Key(this, "MemoryEncryptionKey", {
  enableKeyRotation: true,
  description: "KMS key for memory encryption",
});

// Create memory with custom encryption
const memory = new agentcore.Memory(this, "MyMemory", {
  memoryName: "my_encrypted_memory",
  description: "Memory with custom KMS encryption",
  expirationDuration: cdk.Duration.days(90),
  kmsKey: encryptionKey,
});

Example not in your language?

LTM Memory Extraction Stategies

If you need long-term memory for context recall across sessions, you can setup memory extraction strategies to extract the relevant memory from the raw events.

Amazon Bedrock AgentCore Memory has different memory strategies for extracting and organizing information:

• Summarization: to summarize interactions to preserve critical context and key insights.
• Semantic Memory: to extract general factual knowledge, concepts and meanings from raw conversations using vector embeddings. This enables similarity-based retrieval of relevant facts and context.
• User Preferences: to extract user behavior patterns from raw conversations.

You can use built-in extraction strategies for quick setup, or create custom extraction strategies with specific models and prompt templates.

Memory with Built-in Strategies

The library provides three built-in LTM strategies. These are default strategies for organizing and extracting memory data, each optimized for specific use cases.

For example: An agent helps multiple users with cloud storage setup. From these conversations, see how each strategy processes users expressing confusion about account connection:

1. Summarization Strategy (MemoryStrategy.usingBuiltInSummarization()) This strategy compresses conversations into concise overviews, preserving essential context and key insights for quick recall. Extracted memory example: Users confused by cloud setup during onboarding.

   • Extracts concise summaries to preserve critical context and key insights
   • Namespace: /strategies/{memoryStrategyId}/actors/{actorId}/sessions/{sessionId}

2. Semantic Memory Strategy (MemoryStrategy.usingBuiltInSemantic()) Distills general facts, concepts, and underlying meanings from raw conversational data, presenting the information in a context-independent format. Extracted memory example: In-context learning = task-solving via examples, no training needed.

   • Extracts general factual knowledge, concepts and meanings from raw conversations
   • Namespace: /strategies/{memoryStrategyId}/actors/{actorId}

3. User Preference Strategy (MemoryStrategy.usingBuiltInUserPreference()) Captures individual preferences, interaction patterns, and personalized settings to enhance future experiences. Extracted memory example: User needs clear guidance on cloud storage account connection during onboarding.

   • Extracts user behavior patterns from raw conversations
   • Namespace: /strategies/{memoryStrategyId}/actors/{actorId}

// Create memory with built-in strategies
const memory = new agentcore.Memory(this, "MyMemory", {
  memoryName: "my_memory",
  description: "Memory with built-in strategies",
  expirationDuration: cdk.Duration.days(90),
  memoryStrategies: [
    agentcore.MemoryStrategy.usingBuiltInSummarization(),
    agentcore.MemoryStrategy.usingBuiltInSemantic(),
    agentcore.MemoryStrategy.usingBuiltInUserPreference(),
  ],
});

Example not in your language?

The name generated for each built in memory strategy is as follows:

• For Summarization: summary_builtin_cdk001
• For Semantic:semantic_builtin_cdk001>
• For User Preferences: preference_builtin_cdk001

Memory with custom Strategies

With Long-Term Memory, organization is managed through Namespaces.

An actor refers to entity such as end users or agent/user combinations. For example, in a coding support chatbot, the actor is usually the developer asking questions. Using the actor ID helps the system know which user the memory belongs to, keeping each user's data separate and organized.

A session is usually a single conversation or interaction period between the user and the AI agent. It groups all related messages and events that happen during that conversation.

A namespace is used to logically group and organize long-term memories. It ensures data stays neat, separate, and secure.

With AgentCore Memory, you need to add a namespace when you define a memory strategy. This namespace helps define where the long-term memory will be logically grouped. Every time a new long-term memory is extracted using this memory strategy, it is saved under the namespace you set. This means that all long-term memories are scoped to their specific namespace, keeping them organized and preventing any mix-ups with other users or sessions. You should use a hierarchical format separated by forward slashes /. This helps keep memories organized clearly. As needed, you can choose to use the below pre-defined variables within braces in the namespace based on your applications' organization needs:

• actorId – Identifies who the long-term memory belongs to, such as a user
• memoryStrategyId – Shows which memory strategy is being used. This strategy identifier is auto-generated when you create a memory using CreateMemory operation.
• sessionId – Identifies which session or conversation the memory is from.

For example, if you define the following namespace as the input to your strategy in CreateMemory operation:

/strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}

Example not in your language?

After memory creation, this namespace might look like:

/strategy/summarization-93483043//actor/actor-9830m2w3/session/session-9330sds8

Example not in your language?

You can customise the namespace, i.e. where the memories are stored by using the following methods:

1. Summarization Strategy (MemoryStrategy.usingSummarization(props))
2. Semantic Memory Strategy (MemoryStrategy.usingSemantic(props))
3. User Preference Strategy (MemoryStrategy.usingUserPreference(props))

// Create memory with built-in strategies
const memory = new agentcore.Memory(this, "MyMemory", {
  memoryName: "my_memory",
  description: "Memory with built-in strategies",
  expirationDuration: cdk.Duration.days(90),
  memoryStrategies: [
    agentcore.MemoryStrategy.usingUserPreference({
        name: "CustomerPreferences",
        namespaces: ["support/customer/{actorId}/preferences"]
    }),
    agentcore.MemoryStrategy.usingSemantic({
        name: "CustomerSupportSemantic",
        namespaces: ["support/customer/{actorId}/semantic"]
    }),
  ],
});

Example not in your language?

Custom memory strategies let you tailor memory extraction and consolidation to your specific domain or use case. You can override the prompts for extracting and consolidating semantic, summary, or user preferences. You can also choose the model that you want to use for extraction and consolidation.

The custom prompts you create are appended to a non-editable system prompt.

Since a custom strategy requires you to invoke certain FMs, you need a role with appropriate permissions. For that, you can:

• Let the L2 construct create a minimum permission role for you when use L2 Bedrock Foundation Models.
• Use a custom role with the overly permissive AmazonBedrockAgentCoreMemoryBedrockModelInferenceExecutionRolePolicy managed policy.
• Use a custom role with your own custom policies.

Memory with Custom Execution Role

Keep in mind that memories that do not use custom strategies do not require a service role. So even if you provide it, it will be ignored as it will never be used.

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

// Create memory with custom execution role
const memory = new agentcore.Memory(this, "MyMemory", {
  memoryName: "my_memory",
  description: "Memory with custom execution role",
  expirationDuration: cdk.Duration.days(90),
  executionRole: executionRole,
});

Example not in your language?

In customConsolidation and customExtraction, the model property uses the @aws-cdk/aws-bedrock-alph library which must be installed separately.

// Create a custom semantic memory strategy
const customSemanticStrategy = agentcore.MemoryStrategy.usingSemantic({
  name: "customSemanticStrategy",
  description: "Custom semantic memory strategy",
  namespaces: ["/custom/strategies/{memoryStrategyId}/actors/{actorId}"],
  customConsolidation: {
    model: bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0,
    appendToPrompt: "Custom consolidation prompt for semantic memory",
  },
  customExtraction: {
    model: bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0,
    appendToPrompt: "Custom extraction prompt for semantic memory",
  },
});

// Create memory with custom strategy
const memory = new agentcore.Memory(this, "MyMemory", {
  memoryName: "my-custom-memory",
  description: "Memory with custom strategy",
  expirationDuration: cdk.Duration.days(90),
  memoryStrategies: [customSemanticStrategy],
});

Example not in your language?

Memory with self-managed Strategies

A self-managed strategy in Amazon Bedrock AgentCore Memory gives you complete control over your memory extraction and consolidation pipelines. With a self-managed strategy, you can build custom memory processing workflows while leveraging Amazon Bedrock AgentCore for storage and retrieval.

For additional information, you can refer to the developer guide for self managed strategies.

Create the required AWS resources including:

• an S3 bucket in your account where Amazon Bedrock AgentCore will deliver batched event payloads.
• an SNS topic for job notifications. Use FIFO topics if processing order within sessions is important for your use case.

The construct will apply the correct permissions to the memory execution role to access these resources.

const bucket = new s3.Bucket(this, 'memoryBucket', {
  bucketName: 'test-memory',
  removalPolicy: cdk.RemovalPolicy.DESTROY,
  autoDeleteObjects: true,
});

const topic = new sns.Topic(this, 'topic');

// Create a custom semantic memory strategy
const selfManagedStrategy = agentcore.MemoryStrategy.usingSelfManaged({
  name: "selfManagedStrategy",
  description: "self managed memory strategy",
  historicalContextWindowSize: 5,
  invocationConfiguration: {
    topic: topic,
    s3Location: {
      bucketName: bucket.bucketName,
      objectKey: 'memory/',
    }
  },
  triggerConditions: {
    messageBasedTrigger: 1,
    timeBasedTrigger: cdk.Duration.seconds(10),
    tokenBasedTrigger: 100
  }
});

// Create memory with custom strategy
const memory = new agentcore.Memory(this, "MyMemory", {
  memoryName: "my-custom-memory",
  description: "Memory with custom strategy",
  expirationDuration: cdk.Duration.days(90),
  memoryStrategies: [selfManagedStrategy],
});

Example not in your language?

Memory Strategy Methods

You can add new memory strategies to the memory construct using the addMemoryStrategy() method, for instance:

// Create memory without initial strategies
const memory = new agentcore.Memory(this, "test-memory", {
  memoryName: "test_memory_add_strategy",
  description: "A test memory for testing addMemoryStrategy method",
  expirationDuration: cdk.Duration.days(90),
});

// Add strategies after instantiation
memory.addMemoryStrategy(agentcore.MemoryStrategy.usingBuiltInSummarization());
memory.addMemoryStrategy(agentcore.MemoryStrategy.usingBuiltInSemantic());

Example not in your language?