aws-cdk.aws-bedrock-agentcore-alpha 2.224.0a0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Potentially problematic release.


This version of aws-cdk.aws-bedrock-agentcore-alpha might be problematic. Click here for more details.

@@ -0,0 +1,1131 @@
1
+ Metadata-Version: 2.1
2
+ Name: aws-cdk.aws-bedrock-agentcore-alpha
3
+ Version: 2.224.0a0
4
+ Summary: The CDK Construct Library for Amazon Bedrock
5
+ Home-page: https://github.com/aws/aws-cdk
6
+ Author: Amazon Web Services
7
+ License: Apache-2.0
8
+ Project-URL: Source, https://github.com/aws/aws-cdk.git
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Operating System :: OS Independent
11
+ Classifier: Programming Language :: JavaScript
12
+ Classifier: Programming Language :: Python :: 3 :: Only
13
+ Classifier: Programming Language :: Python :: 3.9
14
+ Classifier: Programming Language :: Python :: 3.10
15
+ Classifier: Programming Language :: Python :: 3.11
16
+ Classifier: Typing :: Typed
17
+ Classifier: Development Status :: 4 - Beta
18
+ Classifier: License :: OSI Approved
19
+ Classifier: Framework :: AWS CDK
20
+ Classifier: Framework :: AWS CDK :: 2
21
+ Requires-Python: ~=3.9
22
+ Description-Content-Type: text/markdown
23
+ License-File: LICENSE
24
+ License-File: NOTICE
25
+ Requires-Dist: aws-cdk-lib <3.0.0,>=2.224.0
26
+ Requires-Dist: aws-cdk.aws-bedrock-alpha ==2.224.0.a0
27
+ Requires-Dist: constructs <11.0.0,>=10.0.0
28
+ Requires-Dist: jsii <2.0.0,>=1.119.0
29
+ Requires-Dist: publication >=0.0.3
30
+ Requires-Dist: typeguard <4.3.0,>=2.13.3
31
+
32
+ # Amazon Bedrock AgentCore Construct Library
33
+
34
+ <!--BEGIN STABILITY BANNER-->---
35
+
36
+
37
+ ![cdk-constructs: Experimental](https://img.shields.io/badge/cdk--constructs-experimental-important.svg?style=for-the-badge)
38
+
39
+ > The APIs of higher level constructs in this module are experimental and under active development.
40
+ > They are subject to non-backward compatible changes or removal in any future version. These are
41
+ > not subject to the [Semantic Versioning](https://semver.org/) model and breaking changes will be
42
+ > announced in the release notes. This means that while you may use them, you may need to update
43
+ > your source code when upgrading to a newer version of this package.
44
+
45
+ ---
46
+ <!--END STABILITY BANNER-->
47
+
48
+ | **Language** | **Package** |
49
+ | :--------------------------------------------------------------------------------------------- | --------------------------------------- |
50
+ | ![Typescript Logo](https://docs.aws.amazon.com/cdk/api/latest/img/typescript32.png) TypeScript | `@aws-cdk/aws-bedrock-agentcore-alpha` |
51
+
52
+ [Amazon Bedrock AgentCore](https://aws.amazon.com/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.
53
+
54
+ 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.
55
+
56
+ ## Table of contents
57
+
58
+ * [AgentCore Runtime](#agentcore-runtime)
59
+
60
+ * [Runtime Versioning](#runtime-versioning)
61
+ * [Runtime Endpoints](#runtime-endpoints)
62
+ * [AgentCore Runtime Properties](#agentcore-runtime-properties)
63
+ * [Runtime Endpoint Properties](#runtime-endpoint-properties)
64
+ * [Creating a Runtime](#creating-a-runtime)
65
+
66
+ * [Option 1: Use an existing image in ECR](#option-1-use-an-existing-image-in-ecr)
67
+ * [Managing Endpoints and Versions](#managing-endpoints-and-versions)
68
+ * [Option 2: Use a local asset](#option-2-use-a-local-asset)
69
+ * [Browser Custom tool](#browser)
70
+
71
+ * [Browser properties](#browser-properties)
72
+ * [Browser Network modes](#browser-network-modes)
73
+ * [Basic Browser Creation](#basic-browser-creation)
74
+ * [Browser IAM permissions](#browser-iam-permissions)
75
+ * [Code Interpreter Custom tool](#code-interpreter)
76
+
77
+ * [Code Interpreter properties](#code-interpreter-properties)
78
+ * [Code Interpreter Network Modes](#code-interpreter-network-modes)
79
+ * [Basic Code Interpreter Creation](#basic-code-interpreter-creation)
80
+ * [Code Interpreter IAM permissions](#code-interpreter-iam-permissions)
81
+ * [Memory](#memory)
82
+
83
+ * [Memory properties](#memory-properties)
84
+ * [Basic Memory Creation](#basic-memory-creation)
85
+ * [LTM Memory Extraction Stategies](#ltm-memory-extraction-stategies)
86
+ * [Memory Strategy Methods](#memory-strategy-methods)
87
+
88
+ ## AgentCore Runtime
89
+
90
+ The AgentCore Runtime construct enables you to deploy containerized agents on Amazon Bedrock AgentCore.
91
+ This L2 construct simplifies runtime creation just pass your ECR repository name
92
+ and the construct handles all the configuration with sensible defaults.
93
+
94
+ ### Runtime Endpoints
95
+
96
+ Endpoints provide a stable way to invoke specific versions of your agent runtime, enabling controlled deployments across different environments.
97
+ When you create an agent runtime, Amazon Bedrock AgentCore automatically creates a "DEFAULT" endpoint which always points to the latest version
98
+ of runtime.
99
+
100
+ You can create additional endpoints in two ways:
101
+
102
+ 1. **Using Runtime.addEndpoint()** - Convenient method when creating endpoints alongside the runtime.
103
+ 2. **Using RuntimeEndpoint** - Flexible approach for existing runtimes.
104
+
105
+ For example, you might keep a "production" endpoint on a stable version while testing newer versions
106
+ through a "staging" endpoint. This separation allows you to test changes thoroughly before promoting them
107
+ to production by simply updating the endpoint to point to the newer version.
108
+
109
+ ### AgentCore Runtime Properties
110
+
111
+ | Name | Type | Required | Description |
112
+ |------|------|----------|-------------|
113
+ | `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 |
114
+ | `agentRuntimeArtifact` | `AgentRuntimeArtifact` | Yes | The artifact configuration for the agent runtime containing the container configuration with ECR URI |
115
+ | `executionRole` | `iam.IRole` | No | The IAM role that provides permissions for the agent runtime. If not provided, a role will be created automatically |
116
+ | `networkConfiguration` | `NetworkConfiguration` | No | Network configuration for the agent runtime. Defaults to `RuntimeNetworkConfiguration.usingPublicNetwork()` |
117
+ | `description` | `string` | No | Optional description for the agent runtime |
118
+ | `protocolConfiguration` | `ProtocolType` | No | Protocol configuration for the agent runtime. Defaults to `ProtocolType.HTTP` |
119
+ | `authorizerConfiguration` | `RuntimeAuthorizerConfiguration` | No | Authorizer configuration for the agent runtime. Use `RuntimeAuthorizerConfiguration` static methods to create configurations for IAM, Cognito, JWT, or OAuth authentication |
120
+ | `environmentVariables` | `{ [key: string]: string }` | No | Environment variables for the agent runtime. Maximum 50 environment variables |
121
+ | `tags` | `{ [key: string]: string }` | No | Tags for the agent runtime. A list of key:value pairs of tags to apply to this Runtime resource |
122
+
123
+ ### Runtime Endpoint Properties
124
+
125
+ | Name | Type | Required | Description |
126
+ |------|------|----------|-------------|
127
+ | `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 |
128
+ | `agentRuntimeId` | `string` | Yes | The Agent Runtime ID for this endpoint |
129
+ | `agentRuntimeVersion` | `string` | Yes | The Agent Runtime version for this endpoint. Must be between 1 and 5 characters long.|
130
+ | `description` | `string` | No | Optional description for the runtime endpoint |
131
+ | `tags` | `{ [key: string]: string }` | No | Tags for the runtime endpoint |
132
+
133
+ ### Creating a Runtime
134
+
135
+ #### Option 1: Use an existing image in ECR
136
+
137
+ Reference an image available within ECR.
138
+
139
+ ```python
140
+ repository = ecr.Repository(self, "TestRepository",
141
+ repository_name="test-agent-runtime"
142
+ )
143
+
144
+ # The runtime by default create ECR permission only for the repository available in the account the stack is being deployed
145
+ agent_runtime_artifact = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v1.0.0")
146
+
147
+ # Create runtime using the built image
148
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
149
+ runtime_name="myAgent",
150
+ agent_runtime_artifact=agent_runtime_artifact
151
+ )
152
+ ```
153
+
154
+ To grant the runtime permission to invoke a Bedrock model or inference profile:
155
+
156
+ ```python
157
+ # Note: This example uses @aws-cdk/aws-bedrock-alpha which must be installed separately
158
+ # runtime: agentcore.Runtime
159
+
160
+
161
+ # Create a cross-region inference profile for Claude 3.7 Sonnet
162
+ inference_profile = bedrock.CrossRegionInferenceProfile.from_config(
163
+ geo_region=bedrock.CrossRegionInferenceProfileRegion.US,
164
+ model=bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_7_SONNET_V1_0
165
+ )
166
+
167
+ # Grant the runtime permission to invoke the inference profile
168
+ inference_profile.grant_invoke(runtime)
169
+ ```
170
+
171
+ #### Option 2: Use a local asset
172
+
173
+ Reference a local directory containing a Dockerfile.
174
+ Images are built from a local Docker context directory (with a Dockerfile), uploaded to Amazon Elastic Container Registry (ECR)
175
+ by the CDK toolkit,and can be naturally referenced in your CDK app .
176
+
177
+ ```python
178
+ agent_runtime_artifact = agentcore.AgentRuntimeArtifact.from_asset(
179
+ path.join(__dirname, "path to agent dockerfile directory"))
180
+
181
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
182
+ runtime_name="myAgent",
183
+ agent_runtime_artifact=agent_runtime_artifact
184
+ )
185
+ ```
186
+
187
+ ### Runtime Versioning
188
+
189
+ Amazon Bedrock AgentCore automatically manages runtime versioning to ensure safe deployments and rollback capabilities.
190
+ When you create an agent runtime, AgentCore automatically creates version 1 (V1). Each subsequent update to the
191
+ runtime configuration (such as updating the container image, modifying network settings, or changing protocol configurations)
192
+ creates a new immutable version. These versions contain complete, self-contained configurations that can be referenced by endpoints,
193
+ allowing you to maintain different versions for different environments or gradually roll out updates.
194
+
195
+ #### Managing Endpoints and Versions
196
+
197
+ Amazon Bedrock AgentCore automatically manages runtime versioning to provide safe deployments and rollback capabilities. You can follow
198
+ the steps below to understand how to use versioning with runtime for controlled deployments across different environments.
199
+
200
+ ##### Step 1: Initial Deployment
201
+
202
+ When you first create an agent runtime, AgentCore automatically creates Version 1 of your runtime. At this point, a DEFAULT endpoint is
203
+ automatically created that points to Version 1. This DEFAULT endpoint serves as the main access point for your runtime.
204
+
205
+ ```python
206
+ repository = ecr.Repository(self, "TestRepository",
207
+ repository_name="test-agent-runtime"
208
+ )
209
+
210
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
211
+ runtime_name="myAgent",
212
+ agent_runtime_artifact=agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v1.0.0")
213
+ )
214
+ ```
215
+
216
+ ##### Step 2: Creating Custom Endpoints
217
+
218
+ After the initial deployment, you can create additional endpoints for different environments. For example, you might create a "production"
219
+ endpoint that explicitly points to Version 1. This allows you to maintain stable access points for specific environments while keeping the
220
+ flexibility to test newer versions elsewhere.
221
+
222
+ ```python
223
+ repository = ecr.Repository(self, "TestRepository",
224
+ repository_name="test-agent-runtime"
225
+ )
226
+
227
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
228
+ runtime_name="myAgent",
229
+ agent_runtime_artifact=agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v1.0.0")
230
+ )
231
+
232
+ prod_endpoint = runtime.add_endpoint("production",
233
+ version="1",
234
+ description="Stable production endpoint - pinned to v1"
235
+ )
236
+ ```
237
+
238
+ ##### Step 3: Runtime Update Deployment
239
+
240
+ When you update the runtime configuration (such as updating the container image, modifying network settings, or changing protocol
241
+ configurations), AgentCore automatically creates a new version (Version 2). Upon this update:
242
+
243
+ * Version 2 is created automatically with the new configuration
244
+ * The DEFAULT endpoint automatically updates to point to Version 2
245
+ * Any explicitly pinned endpoints (like the production endpoint) remain on their specified versions
246
+
247
+ ```python
248
+ repository = ecr.Repository(self, "TestRepository",
249
+ repository_name="test-agent-runtime"
250
+ )
251
+
252
+ agent_runtime_artifact_new = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v2.0.0")
253
+
254
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
255
+ runtime_name="myAgent",
256
+ agent_runtime_artifact=agent_runtime_artifact_new
257
+ )
258
+ ```
259
+
260
+ ##### Step 4: Testing with Staging Endpoints
261
+
262
+ Once Version 2 exists, you can create a staging endpoint that points to the new version. This staging endpoint allows you to test the
263
+ new version in a controlled environment before promoting it to production. This separation ensures that production traffic continues
264
+ to use the stable version while you validate the new version.
265
+
266
+ ```python
267
+ repository = ecr.Repository(self, "TestRepository",
268
+ repository_name="test-agent-runtime"
269
+ )
270
+
271
+ agent_runtime_artifact_new = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v2.0.0")
272
+
273
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
274
+ runtime_name="myAgent",
275
+ agent_runtime_artifact=agent_runtime_artifact_new
276
+ )
277
+
278
+ staging_endpoint = runtime.add_endpoint("staging",
279
+ version="2",
280
+ description="Staging environment for testing new version"
281
+ )
282
+ ```
283
+
284
+ ##### Step 5: Promoting to Production
285
+
286
+ After thoroughly testing the new version through the staging endpoint, you can update the production endpoint to point to Version 2.
287
+ This controlled promotion process ensures that you can validate changes before they affect production traffic.
288
+
289
+ ```python
290
+ repository = ecr.Repository(self, "TestRepository",
291
+ repository_name="test-agent-runtime"
292
+ )
293
+
294
+ agent_runtime_artifact_new = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v2.0.0")
295
+
296
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
297
+ runtime_name="myAgent",
298
+ agent_runtime_artifact=agent_runtime_artifact_new
299
+ )
300
+
301
+ prod_endpoint = runtime.add_endpoint("production",
302
+ version="2", # New version added here
303
+ description="Stable production endpoint"
304
+ )
305
+ ```
306
+
307
+ ### Creating Standalone Runtime Endpoints
308
+
309
+ RuntimeEndpoint can also be created as a standalone resource.
310
+
311
+ #### Example: Creating an endpoint for an existing runtime
312
+
313
+ ```python
314
+ # Reference an existing runtime by its ID
315
+ existing_runtime_id = "abc123-runtime-id" # The ID of an existing runtime
316
+
317
+ # Create a standalone endpoint
318
+ endpoint = agentcore.RuntimeEndpoint(self, "MyEndpoint",
319
+ endpoint_name="production",
320
+ agent_runtime_id=existing_runtime_id,
321
+ agent_runtime_version="1", # Specify which version to use
322
+ description="Production endpoint for existing runtime"
323
+ )
324
+ ```
325
+
326
+ ### Runtime Authentication Configuration
327
+
328
+ 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.
329
+
330
+ #### IAM Authentication (Default)
331
+
332
+ IAM authentication is the default mode, when no authorizerConfiguration is set then the underlying service use IAM.
333
+
334
+ #### Cognito Authentication
335
+
336
+ To configure AWS Cognito User Pool authentication:
337
+
338
+ ```python
339
+ # user_pool: cognito.UserPool
340
+ # user_pool_client: cognito.UserPoolClient
341
+ # another_user_pool_client: cognito.UserPoolClient
342
+
343
+
344
+ repository = ecr.Repository(self, "TestRepository",
345
+ repository_name="test-agent-runtime"
346
+ )
347
+ agent_runtime_artifact = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v1.0.0")
348
+
349
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
350
+ runtime_name="myAgent",
351
+ agent_runtime_artifact=agent_runtime_artifact,
352
+ authorizer_configuration=agentcore.RuntimeAuthorizerConfiguration.using_cognito(user_pool, [user_pool_client, another_user_pool_client])
353
+ )
354
+ ```
355
+
356
+ #### JWT Authentication
357
+
358
+ To configure custom JWT authentication with your own OpenID Connect (OIDC) provider:
359
+
360
+ ```python
361
+ repository = ecr.Repository(self, "TestRepository",
362
+ repository_name="test-agent-runtime"
363
+ )
364
+ agent_runtime_artifact = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v1.0.0")
365
+
366
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
367
+ runtime_name="myAgent",
368
+ agent_runtime_artifact=agent_runtime_artifact,
369
+ authorizer_configuration=agentcore.RuntimeAuthorizerConfiguration.using_jWT("https://example.com/.well-known/openid-configuration", ["client1", "client2"], ["audience1"])
370
+ )
371
+ ```
372
+
373
+ **Note**: The discovery URL must end with `/.well-known/openid-configuration`.
374
+
375
+ #### OAuth Authentication
376
+
377
+ To configure OAuth 2.0 authentication:
378
+
379
+ ```python
380
+ repository = ecr.Repository(self, "TestRepository",
381
+ repository_name="test-agent-runtime"
382
+ )
383
+ agent_runtime_artifact = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v1.0.0")
384
+
385
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
386
+ runtime_name="myAgent",
387
+ agent_runtime_artifact=agent_runtime_artifact,
388
+ authorizer_configuration=agentcore.RuntimeAuthorizerConfiguration.using_oAuth("https://github.com/.well-known/openid-configuration", "oauth_client_123")
389
+ )
390
+ ```
391
+
392
+ #### Using a Custom IAM Role
393
+
394
+ Instead of using the auto-created execution role, you can provide your own IAM role with specific permissions:
395
+ 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.
396
+
397
+ ### Runtime Network Configuration
398
+
399
+ The AgentCore Runtime supports two network modes for deployment:
400
+
401
+ #### Public Network Mode (Default)
402
+
403
+ By default, runtimes are deployed in PUBLIC network mode, which provides internet access suitable for less sensitive or open-use scenarios:
404
+
405
+ ```python
406
+ repository = ecr.Repository(self, "TestRepository",
407
+ repository_name="test-agent-runtime"
408
+ )
409
+ agent_runtime_artifact = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v1.0.0")
410
+
411
+ # Explicitly using public network (this is the default)
412
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
413
+ runtime_name="myAgent",
414
+ agent_runtime_artifact=agent_runtime_artifact,
415
+ network_configuration=agentcore.RuntimeNetworkConfiguration.using_public_network()
416
+ )
417
+ ```
418
+
419
+ #### VPC Network Mode
420
+
421
+ For enhanced security and network isolation, you can deploy your runtime within a VPC:
422
+
423
+ ```python
424
+ repository = ecr.Repository(self, "TestRepository",
425
+ repository_name="test-agent-runtime"
426
+ )
427
+ agent_runtime_artifact = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v1.0.0")
428
+
429
+ # Create or use an existing VPC
430
+ vpc = ec2.Vpc(self, "MyVpc",
431
+ max_azs=2
432
+ )
433
+
434
+ # Configure runtime with VPC
435
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
436
+ runtime_name="myAgent",
437
+ agent_runtime_artifact=agent_runtime_artifact,
438
+ network_configuration=agentcore.RuntimeNetworkConfiguration.using_vpc(self,
439
+ vpc=vpc,
440
+ vpc_subnets=ec2.SubnetSelection(subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS)
441
+ )
442
+ )
443
+ ```
444
+
445
+ #### Managing Security Groups with VPC Configuration
446
+
447
+ When using VPC mode, the Runtime implements `ec2.IConnectable`, allowing you to manage network access using the `connections` property:
448
+
449
+ ```python
450
+ vpc = ec2.Vpc(self, "MyVpc",
451
+ max_azs=2
452
+ )
453
+
454
+ repository = ecr.Repository(self, "TestRepository",
455
+ repository_name="test-agent-runtime"
456
+ )
457
+ agent_runtime_artifact = agentcore.AgentRuntimeArtifact.from_ecr_repository(repository, "v1.0.0")
458
+
459
+ # Create runtime with VPC configuration
460
+ runtime = agentcore.Runtime(self, "MyAgentRuntime",
461
+ runtime_name="myAgent",
462
+ agent_runtime_artifact=agent_runtime_artifact,
463
+ network_configuration=agentcore.RuntimeNetworkConfiguration.using_vpc(self,
464
+ vpc=vpc,
465
+ vpc_subnets=ec2.SubnetSelection(subnet_type=ec2.SubnetType.PRIVATE_WITH_EGRESS)
466
+ )
467
+ )
468
+
469
+ # Now you can manage network access using the connections property
470
+ # Allow inbound HTTPS traffic from a specific security group
471
+ web_server_security_group = ec2.SecurityGroup(self, "WebServerSG", vpc=vpc)
472
+ runtime.connections.allow_from(web_server_security_group, ec2.Port.tcp(443), "Allow HTTPS from web servers")
473
+
474
+ # Allow outbound connections to a database
475
+ database_security_group = ec2.SecurityGroup(self, "DatabaseSG", vpc=vpc)
476
+ runtime.connections.allow_to(database_security_group, ec2.Port.tcp(5432), "Allow PostgreSQL connection")
477
+
478
+ # Allow outbound HTTPS to anywhere (for external API calls)
479
+ runtime.connections.allow_to_any_ipv4(ec2.Port.tcp(443), "Allow HTTPS outbound")
480
+ ```
481
+
482
+ ## Browser
483
+
484
+ 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.
485
+
486
+ Additional information about the browser tool can be found in the [official documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/browser-tool.html)
487
+
488
+ ### Browser Network modes
489
+
490
+ The Browser construct supports the following network modes:
491
+
492
+ 1. **Public Network Mode** (`BrowserNetworkMode.usingPublicNetwork()`) - Default
493
+
494
+ * Allows internet access for web browsing and external API calls
495
+ * Suitable for scenarios where agents need to interact with publicly available websites
496
+ * Enables full web browsing capabilities
497
+ * VPC mode is not supported with this option
498
+ 2. **VPC (Virtual Private Cloud)** (`BrowserNetworkMode.usingVpc()`)
499
+
500
+ * Select whether to run the browser in a virtual private cloud (VPC).
501
+ * By configuring VPC connectivity, you enable secure access to private resources such as databases, internal APIs, and services within your VPC.
502
+
503
+ While the VPC itself is mandatory, these are optional:
504
+
505
+ * Subnets - if not provided, CDK will select appropriate subnets from the VPC
506
+ * Security Groups - if not provided, CDK will create a default security group
507
+ * Specific subnet selection criteria - you can let CDK choose automatically
508
+
509
+ For more information on VPC connectivity for Amazon Bedrock AgentCore Browser, please refer to the [official documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html).
510
+
511
+ ### Browser Properties
512
+
513
+ | Name | Type | Required | Description |
514
+ |------|------|----------|-------------|
515
+ | `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}` |
516
+ | `description` | `string` | No | Optional description for the browser. Can have up to 200 characters |
517
+ | `networkConfiguration` | `BrowserNetworkConfiguration` | No | Network configuration for browser. Defaults to PUBLIC network mode |
518
+ | `recordingConfig` | `RecordingConfig` | No | Recording configuration for browser. Defaults to no recording |
519
+ | `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 |
520
+ | `tags` | `{ [key: string]: string }` | No | Tags to apply to the browser resource |
521
+
522
+ ### Basic Browser Creation
523
+
524
+ ```python
525
+ # Create a basic browser with public network access
526
+ browser = agentcore.BrowserCustom(self, "MyBrowser",
527
+ browser_custom_name="my_browser",
528
+ description="A browser for web automation"
529
+ )
530
+ ```
531
+
532
+ ### Browser with Tags
533
+
534
+ ```python
535
+ # Create a browser with custom tags
536
+ browser = agentcore.BrowserCustom(self, "MyBrowser",
537
+ browser_custom_name="my_browser",
538
+ description="A browser for web automation with tags",
539
+ network_configuration=agentcore.BrowserNetworkConfiguration.using_public_network(),
540
+ tags={
541
+ "Environment": "Production",
542
+ "Team": "AI/ML",
543
+ "Project": "AgentCore"
544
+ }
545
+ )
546
+ ```
547
+
548
+ ### Browser with VPC
549
+
550
+ ```python
551
+ browser = agentcore.BrowserCustom(self, "BrowserVpcWithRecording",
552
+ browser_custom_name="browser_recording",
553
+ network_configuration=agentcore.BrowserNetworkConfiguration.using_vpc(self,
554
+ vpc=ec2.Vpc(self, "VPC", restrict_default_security_group=False)
555
+ )
556
+ )
557
+ ```
558
+
559
+ Browser exposes a [connections](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Connections.html) 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:
560
+
561
+ ```python
562
+ vpc = ec2.Vpc(self, "testVPC")
563
+
564
+ browser = agentcore.BrowserCustom(self, "test-browser",
565
+ browser_custom_name="test_browser",
566
+ network_configuration=agentcore.BrowserNetworkConfiguration.using_vpc(self,
567
+ vpc=vpc
568
+ )
569
+ )
570
+
571
+ browser.connections.add_security_group(ec2.SecurityGroup(self, "AdditionalGroup", vpc=vpc))
572
+ ```
573
+
574
+ 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.
575
+
576
+ ### Browser with Recording Configuration
577
+
578
+ ```python
579
+ # Create an S3 bucket for recordings
580
+ recording_bucket = s3.Bucket(self, "RecordingBucket",
581
+ bucket_name="my-browser-recordings",
582
+ removal_policy=RemovalPolicy.DESTROY
583
+ )
584
+
585
+ # Create browser with recording enabled
586
+ browser = agentcore.BrowserCustom(self, "MyBrowser",
587
+ browser_custom_name="my_browser",
588
+ description="Browser with recording enabled",
589
+ network_configuration=agentcore.BrowserNetworkConfiguration.using_public_network(),
590
+ recording_config=agentcore.RecordingConfig(
591
+ enabled=True,
592
+ s3_location=s3.Location(
593
+ bucket_name=recording_bucket.bucket_name,
594
+ object_key="browser-recordings/"
595
+ )
596
+ )
597
+ )
598
+ ```
599
+
600
+ ### Browser with Custom Execution Role
601
+
602
+ ```python
603
+ # Create a custom execution role
604
+ execution_role = iam.Role(self, "BrowserExecutionRole",
605
+ assumed_by=iam.ServicePrincipal("bedrock-agentcore.amazonaws.com"),
606
+ managed_policies=[
607
+ iam.ManagedPolicy.from_aws_managed_policy_name("AmazonBedrockAgentCoreBrowserExecutionRolePolicy")
608
+ ]
609
+ )
610
+
611
+ # Create browser with custom execution role
612
+ browser = agentcore.BrowserCustom(self, "MyBrowser",
613
+ browser_custom_name="my_browser",
614
+ description="Browser with custom execution role",
615
+ network_configuration=agentcore.BrowserNetworkConfiguration.using_public_network(),
616
+ execution_role=execution_role
617
+ )
618
+ ```
619
+
620
+ ### Browser with S3 Recording and Permissions
621
+
622
+ ```python
623
+ # Create an S3 bucket for recordings
624
+ recording_bucket = s3.Bucket(self, "RecordingBucket",
625
+ bucket_name="my-browser-recordings",
626
+ removal_policy=RemovalPolicy.DESTROY
627
+ )
628
+
629
+ # Create browser with recording enabled
630
+ browser = agentcore.BrowserCustom(self, "MyBrowser",
631
+ browser_custom_name="my_browser",
632
+ description="Browser with recording enabled",
633
+ network_configuration=agentcore.BrowserNetworkConfiguration.using_public_network(),
634
+ recording_config=agentcore.RecordingConfig(
635
+ enabled=True,
636
+ s3_location=s3.Location(
637
+ bucket_name=recording_bucket.bucket_name,
638
+ object_key="browser-recordings/"
639
+ )
640
+ )
641
+ )
642
+ ```
643
+
644
+ ### Browser IAM Permissions
645
+
646
+ The Browser construct provides convenient methods for granting IAM permissions:
647
+
648
+ ```python
649
+ # Create a browser
650
+ browser = agentcore.BrowserCustom(self, "MyBrowser",
651
+ browser_custom_name="my_browser",
652
+ description="Browser for web automation",
653
+ network_configuration=agentcore.BrowserNetworkConfiguration.using_public_network()
654
+ )
655
+
656
+ # Create a role that needs access to the browser
657
+ user_role = iam.Role(self, "UserRole",
658
+ assumed_by=iam.ServicePrincipal("lambda.amazonaws.com")
659
+ )
660
+
661
+ # Grant read permissions (Get and List actions)
662
+ browser.grant_read(user_role)
663
+
664
+ # Grant use permissions (Start, Update, Stop actions)
665
+ browser.grant_use(user_role)
666
+
667
+ # Grant specific custom permissions
668
+ browser.grant(user_role, "bedrock-agentcore:GetBrowserSession")
669
+ ```
670
+
671
+ ## Code Interpreter
672
+
673
+ 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.
674
+
675
+ For more information about code interpreter, please refer to the [official documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/code-interpreter-tool.html)
676
+
677
+ ### Code Interpreter Network Modes
678
+
679
+ The Code Interpreter construct supports the following network modes:
680
+
681
+ 1. **Public Network Mode** (`CodeInterpreterNetworkMode.usingPublicNetwork()`) - Default
682
+
683
+ * Allows internet access for package installation and external API calls
684
+ * Suitable for development and testing environments
685
+ * Enables downloading Python packages from PyPI
686
+ 2. **Sandbox Network Mode** (`CodeInterpreterNetworkMode.usingSandboxNetwork()`)
687
+
688
+ * Isolated network environment with no internet access
689
+ * Suitable for production environments with strict security requirements
690
+ * Only allows access to pre-installed packages and local resources
691
+ 3. **VPC (Virtual Private Cloud)** (`CodeInterpreterNetworkMode.usingVpc()`)
692
+
693
+ * Select whether to run the browser in a virtual private cloud (VPC).
694
+ * By configuring VPC connectivity, you enable secure access to private resources such as databases, internal APIs, and services within your VPC.
695
+
696
+ While the VPC itself is mandatory, these are optional:
697
+
698
+ * Subnets - if not provided, CDK will select appropriate subnets from the VPC
699
+ * Security Groups - if not provided, CDK will create a default security group
700
+ * Specific subnet selection criteria - you can let CDK choose automatically
701
+
702
+ For more information on VPC connectivity for Amazon Bedrock AgentCore Browser, please refer to the [official documentation](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agentcore-vpc.html).
703
+
704
+ ### Code Interpreter Properties
705
+
706
+ | Name | Type | Required | Description |
707
+ |------|------|----------|-------------|
708
+ | `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}` |
709
+ | `description` | `string` | No | Optional description for the code interpreter. Can have up to 200 characters |
710
+ | `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 |
711
+ | `networkConfiguration` | `CodeInterpreterNetworkConfiguration` | No | Network configuration for code interpreter. Defaults to PUBLIC network mode |
712
+ | `tags` | `{ [key: string]: string }` | No | Tags to apply to the code interpreter resource |
713
+
714
+ ### Basic Code Interpreter Creation
715
+
716
+ ```python
717
+ # Create a basic code interpreter with public network access
718
+ code_interpreter = agentcore.CodeInterpreterCustom(self, "MyCodeInterpreter",
719
+ code_interpreter_custom_name="my_code_interpreter",
720
+ description="A code interpreter for Python execution"
721
+ )
722
+ ```
723
+
724
+ ### Code Interpreter with VPC
725
+
726
+ ```python
727
+ code_interpreter = agentcore.CodeInterpreterCustom(self, "MyCodeInterpreter",
728
+ code_interpreter_custom_name="my_sandbox_interpreter",
729
+ description="Code interpreter with isolated network access",
730
+ network_configuration=agentcore.BrowserNetworkConfiguration.using_vpc(self,
731
+ vpc=ec2.Vpc(self, "VPC", restrict_default_security_group=False)
732
+ )
733
+ )
734
+ ```
735
+
736
+ Code Interpreter exposes a [connections](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.Connections.html) 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:
737
+
738
+ ```python
739
+ vpc = ec2.Vpc(self, "testVPC")
740
+
741
+ code_interpreter = agentcore.CodeInterpreterCustom(self, "MyCodeInterpreter",
742
+ code_interpreter_custom_name="my_sandbox_interpreter",
743
+ description="Code interpreter with isolated network access",
744
+ network_configuration=agentcore.BrowserNetworkConfiguration.using_vpc(self,
745
+ vpc=vpc
746
+ )
747
+ )
748
+
749
+ code_interpreter.connections.add_security_group(ec2.SecurityGroup(self, "AdditionalGroup", vpc=vpc))
750
+ ```
751
+
752
+ 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.
753
+
754
+ ### Code Interpreter with Sandbox Network Mode
755
+
756
+ ```python
757
+ # Create code interpreter with sandbox network mode (isolated)
758
+ code_interpreter = agentcore.CodeInterpreterCustom(self, "MyCodeInterpreter",
759
+ code_interpreter_custom_name="my_sandbox_interpreter",
760
+ description="Code interpreter with isolated network access",
761
+ network_configuration=agentcore.CodeInterpreterNetworkConfiguration.using_sandbox_network()
762
+ )
763
+ ```
764
+
765
+ ### Code Interpreter with Custom Execution Role
766
+
767
+ ```python
768
+ # Create a custom execution role
769
+ execution_role = iam.Role(self, "CodeInterpreterExecutionRole",
770
+ assumed_by=iam.ServicePrincipal("bedrock-agentcore.amazonaws.com")
771
+ )
772
+
773
+ # Create code interpreter with custom execution role
774
+ code_interpreter = agentcore.CodeInterpreterCustom(self, "MyCodeInterpreter",
775
+ code_interpreter_custom_name="my_code_interpreter",
776
+ description="Code interpreter with custom execution role",
777
+ network_configuration=agentcore.CodeInterpreterNetworkConfiguration.using_public_network(),
778
+ execution_role=execution_role
779
+ )
780
+ ```
781
+
782
+ ### Code Interpreter IAM Permissions
783
+
784
+ The Code Interpreter construct provides convenient methods for granting IAM permissions:
785
+
786
+ ```python
787
+ # Create a code interpreter
788
+ code_interpreter = agentcore.CodeInterpreterCustom(self, "MyCodeInterpreter",
789
+ code_interpreter_custom_name="my_code_interpreter",
790
+ description="Code interpreter for Python execution",
791
+ network_configuration=agentcore.CodeInterpreterNetworkConfiguration.using_public_network()
792
+ )
793
+
794
+ # Create a role that needs access to the code interpreter
795
+ user_role = iam.Role(self, "UserRole",
796
+ assumed_by=iam.ServicePrincipal("lambda.amazonaws.com")
797
+ )
798
+
799
+ # Grant read permissions (Get and List actions)
800
+ code_interpreter.grant_read(user_role)
801
+
802
+ # Grant use permissions (Start, Invoke, Stop actions)
803
+ code_interpreter.grant_use(user_role)
804
+
805
+ # Grant specific custom permissions
806
+ code_interpreter.grant(user_role, "bedrock-agentcore:GetCodeInterpreterSession")
807
+ ```
808
+
809
+ ### Code interpreter with tags
810
+
811
+ ```python
812
+ # Create code interpreter with sandbox network mode (isolated)
813
+ code_interpreter = agentcore.CodeInterpreterCustom(self, "MyCodeInterpreter",
814
+ code_interpreter_custom_name="my_sandbox_interpreter",
815
+ description="Code interpreter with isolated network access",
816
+ network_configuration=agentcore.CodeInterpreterNetworkConfiguration.using_public_network(),
817
+ tags={
818
+ "Environment": "Production",
819
+ "Team": "AI/ML",
820
+ "Project": "AgentCore"
821
+ }
822
+ )
823
+ ```
824
+
825
+ ## Memory
826
+
827
+ 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.
828
+
829
+ AgentCore Memory operates on two levels:
830
+
831
+ * **Short-Term Memory**: Immediate conversation context and session-based information that provides continuity within a single interaction or closely related sessions.
832
+ * **Long-Term Memory**: Persistent information extracted and stored across multiple conversations, including facts, preferences, and summaries that enable personalized experiences over time.
833
+
834
+ 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.
835
+
836
+ 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.
837
+
838
+ ### Memory Properties
839
+
840
+ | Name | Type | Required | Description |
841
+ |------|------|----------|-------------|
842
+ | `memoryName` | `string` | Yes | The name of the memory |
843
+ | `expirationDuration` | `Duration` | No | Short-term memory expiration in days (between 7 and 365). Default: 90 days |
844
+ | `description` | `string` | No | Optional description for the memory. Default: no description. |
845
+ | `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 |
846
+ | `memoryStrategies` | `MemoryStrategyBase[]` | No | Built-in extraction strategies to use for this memory. Default: No extraction strategies (short term memory only) |
847
+ | `executionRole` | `iam.IRole` | No | The IAM role that provides permissions for the memory to access AWS services. Default: A new role will be created. |
848
+ | `tags` | `{ [key: string]: string }` | No | Tags for memory. Default: no tags. |
849
+
850
+ ### Basic Memory Creation
851
+
852
+ Below you can find how to configure a simple short-term memory (STM) with no long-term memory extraction strategies.
853
+ Note how you set `expirationDuration`, which defines the time the events will be stored in the short-term memory before they expire.
854
+
855
+ ```python
856
+ # Create a basic memory with default settings, no LTM strategies
857
+ memory = agentcore.Memory(self, "MyMemory",
858
+ memory_name="my_memory",
859
+ description="A memory for storing user interactions for a period of 90 days",
860
+ expiration_duration=cdk.Duration.days(90)
861
+ )
862
+ ```
863
+
864
+ Basic Memory with Custom KMS Encryption
865
+
866
+ ```python
867
+ # Create a custom KMS key for encryption
868
+ encryption_key = kms.Key(self, "MemoryEncryptionKey",
869
+ enable_key_rotation=True,
870
+ description="KMS key for memory encryption"
871
+ )
872
+
873
+ # Create memory with custom encryption
874
+ memory = agentcore.Memory(self, "MyMemory",
875
+ memory_name="my_encrypted_memory",
876
+ description="Memory with custom KMS encryption",
877
+ expiration_duration=cdk.Duration.days(90),
878
+ kms_key=encryption_key
879
+ )
880
+ ```
881
+
882
+ ### LTM Memory Extraction Stategies
883
+
884
+ If you need long-term memory for context recall across sessions, you can setup memory extraction strategies
885
+ to extract the relevant memory from the raw events.
886
+
887
+ Amazon Bedrock AgentCore Memory has different memory strategies for extracting and organizing information:
888
+
889
+ * **Summarization**: to summarize interactions to preserve critical context and key insights.
890
+ * **Semantic Memory**: to extract general factual knowledge, concepts and meanings from raw conversations using vector embeddings.
891
+ This enables similarity-based retrieval of relevant facts and context.
892
+ * **User Preferences**: to extract user behavior patterns from raw conversations.
893
+
894
+ You can use built-in extraction strategies for quick setup, or create custom extraction strategies with specific models and prompt templates.
895
+
896
+ ### Memory with Built-in Strategies
897
+
898
+ The library provides three built-in LTM strategies. These are default strategies for organizing and extracting memory data,
899
+ each optimized for specific use cases.
900
+
901
+ For example: An agent helps multiple users with cloud storage setup. From these conversations,
902
+ see how each strategy processes users expressing confusion about account connection:
903
+
904
+ 1. **Summarization Strategy** (`MemoryStrategy.usingBuiltInSummarization()`)
905
+ This strategy compresses conversations into concise overviews, preserving essential context and key insights for quick recall.
906
+ Extracted memory example: Users confused by cloud setup during onboarding.
907
+
908
+ * Extracts concise summaries to preserve critical context and key insights
909
+ * Namespace: `/strategies/{memoryStrategyId}/actors/{actorId}/sessions/{sessionId}`
910
+ 2. **Semantic Memory Strategy** (`MemoryStrategy.usingBuiltInSemantic()`)
911
+ Distills general facts, concepts, and underlying meanings from raw conversational data, presenting the information in a context-independent format.
912
+ Extracted memory example: In-context learning = task-solving via examples, no training needed.
913
+
914
+ * Extracts general factual knowledge, concepts and meanings from raw conversations
915
+ * Namespace: `/strategies/{memoryStrategyId}/actors/{actorId}`
916
+ 3. **User Preference Strategy** (`MemoryStrategy.usingBuiltInUserPreference()`)
917
+ Captures individual preferences, interaction patterns, and personalized settings to enhance future experiences.
918
+ Extracted memory example: User needs clear guidance on cloud storage account connection during onboarding.
919
+
920
+ * Extracts user behavior patterns from raw conversations
921
+ * Namespace: `/strategies/{memoryStrategyId}/actors/{actorId}`
922
+
923
+ ```python
924
+ # Create memory with built-in strategies
925
+ memory = agentcore.Memory(self, "MyMemory",
926
+ memory_name="my_memory",
927
+ description="Memory with built-in strategies",
928
+ expiration_duration=cdk.Duration.days(90),
929
+ memory_strategies=[
930
+ agentcore.MemoryStrategy.using_built_in_summarization(),
931
+ agentcore.MemoryStrategy.using_built_in_semantic(),
932
+ agentcore.MemoryStrategy.using_built_in_user_preference()
933
+ ]
934
+ )
935
+ ```
936
+
937
+ The name generated for each built in memory strategy is as follows:
938
+
939
+ * For Summarization: `summary_builtin_cdk001`
940
+ * For Semantic:`semantic_builtin_cdk001>`
941
+ * For User Preferences: `preference_builtin_cdk001`
942
+
943
+ ### Memory with custom Strategies
944
+
945
+ With Long-Term Memory, organization is managed through Namespaces.
946
+
947
+ An `actor` refers to entity such as end users or agent/user combinations. For example, in a coding support chatbot,
948
+ the actor is usually the developer asking questions. Using the actor ID helps the system know which user the memory belongs to,
949
+ keeping each user's data separate and organized.
950
+
951
+ A `session` is usually a single conversation or interaction period between the user and the AI agent.
952
+ It groups all related messages and events that happen during that conversation.
953
+
954
+ A `namespace` is used to logically group and organize long-term memories. It ensures data stays neat, separate, and secure.
955
+
956
+ With AgentCore Memory, you need to add a namespace when you define a memory strategy. This namespace helps define where the long-term memory
957
+ 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.
958
+ This means that all long-term memories are scoped to their specific namespace, keeping them organized and preventing any mix-ups with other
959
+ users or sessions. You should use a hierarchical format separated by forward slashes /. This helps keep memories organized clearly. As needed,
960
+ you can choose to use the below pre-defined variables within braces in the namespace based on your applications' organization needs:
961
+
962
+ * `actorId` – Identifies who the long-term memory belongs to, such as a user
963
+ * `memoryStrategyId` – Shows which memory strategy is being used. This strategy identifier is auto-generated when you create a memory using CreateMemory operation.
964
+ * `sessionId` – Identifies which session or conversation the memory is from.
965
+
966
+ For example, if you define the following namespace as the input to your strategy in CreateMemory operation:
967
+
968
+ ```shell
969
+ /strategy/{memoryStrategyId}/actor/{actorId}/session/{sessionId}
970
+ ```
971
+
972
+ After memory creation, this namespace might look like:
973
+
974
+ ```shell
975
+ /strategy/summarization-93483043//actor/actor-9830m2w3/session/session-9330sds8
976
+ ```
977
+
978
+ You can customise the namespace, i.e. where the memories are stored by using the following methods:
979
+
980
+ 1. **Summarization Strategy** (`MemoryStrategy.usingSummarization(props)`)
981
+ 2. **Semantic Memory Strategy** (`MemoryStrategy.usingSemantic(props)`)
982
+ 3. **User Preference Strategy** (`MemoryStrategy.usingUserPreference(props)`)
983
+
984
+ ```python
985
+ # Create memory with built-in strategies
986
+ memory = agentcore.Memory(self, "MyMemory",
987
+ memory_name="my_memory",
988
+ description="Memory with built-in strategies",
989
+ expiration_duration=cdk.Duration.days(90),
990
+ memory_strategies=[
991
+ agentcore.MemoryStrategy.using_user_preference(
992
+ name="CustomerPreferences",
993
+ namespaces=["support/customer/{actorId}/preferences"]
994
+ ),
995
+ agentcore.MemoryStrategy.using_semantic(
996
+ name="CustomerSupportSemantic",
997
+ namespaces=["support/customer/{actorId}/semantic"]
998
+ )
999
+ ]
1000
+ )
1001
+ ```
1002
+
1003
+ Custom memory strategies let you tailor memory extraction and consolidation to your specific domain or use case.
1004
+ You can override the prompts for extracting and consolidating semantic, summary, or user preferences.
1005
+ You can also choose the model that you want to use for extraction and consolidation.
1006
+
1007
+ The custom prompts you create are appended to a non-editable system prompt.
1008
+
1009
+ Since a custom strategy requires you to invoke certain FMs, you need a role with appropriate permissions. For that, you can:
1010
+
1011
+ * Let the L2 construct create a minimum permission role for you when use L2 Bedrock Foundation Models.
1012
+ * Use a custom role with the overly permissive `AmazonBedrockAgentCoreMemoryBedrockModelInferenceExecutionRolePolicy` managed policy.
1013
+ * Use a custom role with your own custom policies.
1014
+
1015
+ #### Memory with Custom Execution Role
1016
+
1017
+ Keep in mind that memories that **do not** use custom strategies do not require a service role.
1018
+ So even if you provide it, it will be ignored as it will never be used.
1019
+
1020
+ ```python
1021
+ # Create a custom execution role
1022
+ execution_role = iam.Role(self, "MemoryExecutionRole",
1023
+ assumed_by=iam.ServicePrincipal("bedrock-agentcore.amazonaws.com"),
1024
+ managed_policies=[
1025
+ iam.ManagedPolicy.from_aws_managed_policy_name("AmazonBedrockAgentCoreMemoryBedrockModelInferenceExecutionRolePolicy")
1026
+ ]
1027
+ )
1028
+
1029
+ # Create memory with custom execution role
1030
+ memory = agentcore.Memory(self, "MyMemory",
1031
+ memory_name="my_memory",
1032
+ description="Memory with custom execution role",
1033
+ expiration_duration=cdk.Duration.days(90),
1034
+ execution_role=execution_role
1035
+ )
1036
+ ```
1037
+
1038
+ In customConsolidation and customExtraction, the model property uses the [@aws-cdk/aws-bedrock-alph](https://www.npmjs.com/package/@aws-cdk/aws-bedrock-alpha) library which must be installed separately.
1039
+
1040
+ ```python
1041
+ # Create a custom semantic memory strategy
1042
+ custom_semantic_strategy = agentcore.MemoryStrategy.using_semantic(
1043
+ name="customSemanticStrategy",
1044
+ description="Custom semantic memory strategy",
1045
+ namespaces=["/custom/strategies/{memoryStrategyId}/actors/{actorId}"],
1046
+ custom_consolidation=agentcore.OverrideConfig(
1047
+ model=bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0,
1048
+ append_to_prompt="Custom consolidation prompt for semantic memory"
1049
+ ),
1050
+ custom_extraction=agentcore.OverrideConfig(
1051
+ model=bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0,
1052
+ append_to_prompt="Custom extraction prompt for semantic memory"
1053
+ )
1054
+ )
1055
+
1056
+ # Create memory with custom strategy
1057
+ memory = agentcore.Memory(self, "MyMemory",
1058
+ memory_name="my-custom-memory",
1059
+ description="Memory with custom strategy",
1060
+ expiration_duration=cdk.Duration.days(90),
1061
+ memory_strategies=[custom_semantic_strategy]
1062
+ )
1063
+ ```
1064
+
1065
+ ### Memory with self-managed Strategies
1066
+
1067
+ A self-managed strategy in Amazon Bedrock AgentCore Memory gives you complete control over your memory extraction and consolidation pipelines.
1068
+ With a self-managed strategy, you can build custom memory processing workflows while leveraging Amazon Bedrock AgentCore for storage and retrieval.
1069
+
1070
+ For additional information, you can refer to the [developer guide for self managed strategies](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory-self-managed-strategies.html).
1071
+
1072
+ Create the required AWS resources including:
1073
+
1074
+ * an S3 bucket in your account where Amazon Bedrock AgentCore will deliver batched event payloads.
1075
+ * an SNS topic for job notifications. Use FIFO topics if processing order within sessions is important for your use case.
1076
+
1077
+ The construct will apply the correct permissions to the memory execution role to access these resources.
1078
+
1079
+ ```python
1080
+ bucket = s3.Bucket(self, "memoryBucket",
1081
+ bucket_name="test-memory",
1082
+ removal_policy=cdk.RemovalPolicy.DESTROY,
1083
+ auto_delete_objects=True
1084
+ )
1085
+
1086
+ topic = sns.Topic(self, "topic")
1087
+
1088
+ # Create a custom semantic memory strategy
1089
+ self_managed_strategy = agentcore.MemoryStrategy.using_self_managed(
1090
+ name="selfManagedStrategy",
1091
+ description="self managed memory strategy",
1092
+ historical_context_window_size=5,
1093
+ invocation_configuration=agentcore.InvocationConfiguration(
1094
+ topic=topic,
1095
+ s3_location=s3.Location(
1096
+ bucket_name=bucket.bucket_name,
1097
+ object_key="memory/"
1098
+ )
1099
+ ),
1100
+ trigger_conditions=agentcore.TriggerConditions(
1101
+ message_based_trigger=1,
1102
+ time_based_trigger=cdk.Duration.seconds(10),
1103
+ token_based_trigger=100
1104
+ )
1105
+ )
1106
+
1107
+ # Create memory with custom strategy
1108
+ memory = agentcore.Memory(self, "MyMemory",
1109
+ memory_name="my-custom-memory",
1110
+ description="Memory with custom strategy",
1111
+ expiration_duration=cdk.Duration.days(90),
1112
+ memory_strategies=[self_managed_strategy]
1113
+ )
1114
+ ```
1115
+
1116
+ ### Memory Strategy Methods
1117
+
1118
+ You can add new memory strategies to the memory construct using the `addMemoryStrategy()` method, for instance:
1119
+
1120
+ ```python
1121
+ # Create memory without initial strategies
1122
+ memory = agentcore.Memory(self, "test-memory",
1123
+ memory_name="test_memory_add_strategy",
1124
+ description="A test memory for testing addMemoryStrategy method",
1125
+ expiration_duration=cdk.Duration.days(90)
1126
+ )
1127
+
1128
+ # Add strategies after instantiation
1129
+ memory.add_memory_strategy(agentcore.MemoryStrategy.using_built_in_summarization())
1130
+ memory.add_memory_strategy(agentcore.MemoryStrategy.using_built_in_semantic())
1131
+ ```