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

/** * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved. * * Licensed under the Apache License, Version 2.0 (the "License"). You may not use this file except in compliance * with the License. A copy of the License is located at * * http://www.apache.org/licenses/LICENSE-2.0 * * or in the 'license' file accompanying this file. This file is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES * OR CONDITIONS OF ANY KIND, express or implied. See the License for the specific language governing permissions * and limitations under the License. */ import { Duration, IResource, Resource } from 'aws-cdk-lib'; import { Construct } from 'constructs'; import { DimensionsMap, Metric, MetricOptions } from 'aws-cdk-lib/aws-cloudwatch'; import * as iam from 'aws-cdk-lib/aws-iam'; import * as kms from 'aws-cdk-lib/aws-kms'; import { IMemoryStrategy } from './memory-strategy'; /****************************************************************************** * Interface *****************************************************************************/ /** * Interface for Memory resources */ export interface IMemory extends IResource, iam.IGrantable { /** * The ARN of the memory resource * @attribute */ readonly memoryArn: string; /** * The id of the memory * @attribute */ readonly memoryId: string; /** * The IAM role that provides permissions for the memory to access AWS services. */ readonly executionRole?: iam.IRole; /** * Custom KMS key for encryption (if provided) */ readonly kmsKey?: kms.IKey; /** * The status of the memory * @attribute */ readonly status?: string; /** * Timestamp when the memory was last updated * @attribute */ readonly updatedAt?: string; /** * Timestamp when the memory was created * @attribute */ readonly createdAt?: string; /** * Grant the given principal identity permissions to perform actions on this memory. */ grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant; /** * Grant the given principal identity permissions to write content to this memory. */ grantWrite(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to read the contents of this memory. * Both Short-Term Memory (STM) and Long-Term Memory (LTM). */ grantRead(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to read the Short-Term Memory (STM) contents of this memory. */ grantReadShortTermMemory(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to read the Long-Term Memory (LTM) contents of this memory. */ grantReadLongTermMemory(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to delete content on this memory. */ grantDelete(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to delete Short-Term Memory (STM) content on this memory. */ grantDeleteShortTermMemory(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to delete Long-Term Memory (LTM) content on this memory. */ grantDeleteLongTermMemory(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to manage the control plane of this memory. */ grantAdmin(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to do every action on this memory. */ grantFullAccess(grantee: iam.IGrantable): iam.Grant; /** * Return the given named metric for this memory. */ metric(metricName: string, dimensions: DimensionsMap, props?: MetricOptions): Metric; /** * Return the given named metric related to the API operation performed on this memory. */ metricForApiOperation(metricName: string, operation: string, props?: MetricOptions): Metric; /** * Return a metric measuring the latency of a specific API operation performed on this memory. */ metricLatencyForApiOperation(operation: string, props?: MetricOptions): Metric; /** * Return a metric containing the total number of API requests made for a specific memory operation. */ metricInvocationsForApiOperation(operation: string, props?: MetricOptions): Metric; /** * Return a metric containing the number of errors for a specific API operation performed on this memory. */ metricErrorsForApiOperation(operation: string, props?: MetricOptions): Metric; /** * Returns the metric containing the number of created memory events and memory records. */ metricEventCreationCount(props?: MetricOptions): Metric; } /****************************************************************************** * ABSTRACT BASE CLASS *****************************************************************************/ /** * Abstract base class for a Memory. * Contains methods and attributes valid for Memories either created with CDK or imported. */ export declare abstract class MemoryBase extends Resource implements IMemory { abstract readonly memoryArn: string; abstract readonly memoryId: string; abstract readonly status?: string; abstract readonly updatedAt?: string; abstract readonly createdAt?: string; abstract readonly executionRole?: iam.IRole; abstract readonly kmsKey?: kms.IKey; /** * The principal to grant permissions to */ abstract readonly grantPrincipal: iam.IPrincipal; constructor(scope: Construct, id: string); /** * Grants IAM actions to the IAM Principal * @param grantee - The IAM principal to grant permissions to * @param actions - The actions to grant * @returns An IAM Grant object representing the granted permissions */ grant(grantee: iam.IGrantable, ...actions: string[]): iam.Grant; /** * Grant the given principal identity permissions to write content to short-term memory. * * @param grantee - The IAM principal to grant read permissions to * @default - Default grant configuration: * - actions: ['bedrock-agentcore:CreateEvent'] on this.memoryArn * @returns An IAM Grant object representing the granted permissions */ grantWrite(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to read the contents of this memory. * Both Short-Term Memory (STM) and Long-Term Memory (LTM). * * @param grantee - The IAM principal to grant read permissions to * @default - Default grant configuration: * - actions: ['bedrock-agentcore:GetMemoryRecord', 'bedrock-agentcore:RetrieveMemoryRecords', 'bedrock-agentcore:ListMemoryRecords', 'bedrock-agentcore:ListActors', 'bedrock-agentcore:ListSessions] on this.memoryArn * @returns An IAM Grant object representing the granted permissions */ grantRead(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to read the Short-Term Memory (STM) contents of this memory. * * @param grantee - The IAM principal to grant read permissions to * @default - Default grant configuration: * - actions: ['bedrock-agentcore:GetEvent', 'bedrock-agentcore:ListEvents', 'bedrock-agentcore:ListActors', 'bedrock-agentcore:ListSessions',] on this.memoryArn * @returns An IAM Grant object representing the granted permissions */ grantReadShortTermMemory(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to read the Long-Term Memory (LTM) contents of this memory. * * @param grantee - The IAM principal to grant read permissions to * @default - Default grant configuration: * - actions: ['bedrock-agentcore:GetMemoryRecord', 'bedrock-agentcore:RetrieveMemoryRecords', 'bedrock-agentcore:ListMemoryRecords', 'bedrock-agentcore:ListActors', 'bedrock-agentcore:ListSessions',] on this.memoryArn * @returns An IAM Grant object representing the granted permissions */ grantReadLongTermMemory(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to delete content on this memory. * * Both Short-Term Memory (STM) and Long-Term Memory (LTM). * * @param grantee - The IAM principal to grant delete permissions to * @default - Default grant configuration: * - actions: ['bedrock-agentcore:DeleteEvent', 'bedrock-agentcore:DeleteMemoryRecord'] on this.memoryArn * @returns An IAM Grant object representing the granted permissions */ grantDelete(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to delete Short-Term Memory (STM) content on this memory. * * @param grantee - The IAM principal to grant delete permissions to * @default - Default grant configuration: * - actions: ['bedrock-agentcore:DeleteEvent'] on this.memoryArn * @returns An IAM Grant object representing the granted permissions */ grantDeleteShortTermMemory(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to delete Long-Term Memory (LTM) content on this memory. * * @param grantee - The IAM principal to grant delete permissions to * @default - Default grant configuration: * - actions: ['bedrock-agentcore:DeleteMemoryRecord'] on this.memoryArn * @returns An IAM Grant object representing the granted permissions */ grantDeleteLongTermMemory(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to manage the control plane of this memory. * * @param grantee - The IAM principal to grant admin permissions to * @default - Default grant configuration: * - actions: ['bedrock-agentcore:CreateMemory', 'bedrock-agentcore:GetMemory', 'bedrock-agentcore:DeleteMemory', 'bedrock-agentcore:UpdateMemory'] on this.memoryArn * @returns An IAM Grant object representing the granted permissions */ grantAdmin(grantee: iam.IGrantable): iam.Grant; /** * Grant the given principal identity permissions to do every action on this memory. * * @param grantee - The IAM principal to grant full access permissions to * @default - Default grant configuration: * - actions: ['bedrock-agentcore:CreateEvent', 'bedrock-agentcore:GetEvent', 'bedrock-agentcore:DeleteEvent', 'bedrock-agentcore:GetMemoryRecord', 'bedrock-agentcore:RetrieveMemoryRecords', 'bedrock-agentcore:ListMemoryRecords', 'bedrock-agentcore:ListActors', 'bedrock-agentcore:ListSessions', 'bedrock-agentcore:CreateMemory', 'bedrock-agentcore:GetMemory', 'bedrock-agentcore:DeleteMemory', 'bedrock-agentcore:UpdateMemory'] on this.memoryArn * @returns An IAM Grant object representing the granted permissions */ grantFullAccess(grantee: iam.IGrantable): iam.Grant; /** * Return the given named metric for this memory. * * By default, the metric will be calculated as a sum over a period of 5 minutes. * You can customize this by using the `statistic` and `period` properties. */ metric(metricName: string, dimensions: DimensionsMap, props?: MetricOptions): Metric; /** * Return the given named metric related to the API operation performed on this memory. */ metricForApiOperation(metricName: string, operation: string, props?: MetricOptions): Metric; /** * Return a metric measuring the latency of a specific API operation performed on this memory. * * The latency metric represents the total time elapsed between receiving the request and sending * the final response token, measuring complete end-to-end processing time. * * For memory creation events specifically, this measures the time from the last CreateEvent * that met strategy criteria until memory storage is completed. * */ metricLatencyForApiOperation(operation: string, props?: MetricOptions): Metric; /** * Return a metric containing the total number of API requests made for a specific memory operation like * `CreateEvent`, `ListEvents`, `RetrieveMemoryRecords` ... */ metricInvocationsForApiOperation(operation: string, props?: MetricOptions): Metric; /** * Return a metric containing the number of errors for a specific API operation performed on this memory. */ metricErrorsForApiOperation(operation: string, props?: MetricOptions): Metric; /** * Returns the metric containing the number of short-term memory events. */ metricEventCreationCount(props?: MetricOptions): Metric; /** * Returns the metric containing the number of long-term memory records * created by the long-term extraction strategies. */ metricMemoryRecordCreationCount(props?: MetricOptions): Metric; /** * Internal method to create a metric. */ private configureMetric; } /****************************************************************************** * PROPS FOR NEW CONSTRUCT *****************************************************************************/ /** * Properties for creating a Memory resource */ export interface MemoryProps { /** * The name of the memory * Valid characters are a-z, A-Z, 0-9, _ (underscore) * The name must start with a letter and can be up to 48 characters long * Pattern: [a-zA-Z][a-zA-Z0-9_]{0,47} */ readonly memoryName: string; /** * Short-term memory expiration in days (between 7 and 365). * Sets the short-term (raw event) memory retention. * Events older than the specified duration will expire and no longer be stored. * @default - 90 days */ readonly expirationDuration?: Duration; /** * Optional description for the memory * Valid characters are a-z, A-Z, 0-9, _ (underscore), - (hyphen) and spaces * The description can have up to 200 characters * @default - No description */ readonly description?: string; /** * Custom KMS key to use for encryption. * @default - Your data is encrypted with a key that AWS owns and manages for you */ readonly kmsKey?: kms.IKey; /** * 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. * @default - No extraction strategies (short term memory only) */ readonly memoryStrategies?: IMemoryStrategy[]; /** * The IAM role that provides permissions for the memory to access AWS services * when using custom strategies. * * @default - A new role will be created. */ readonly executionRole?: iam.IRole; /** * Tags (optional) * A list of key:value pairs of tags to apply to this memory resource * * @default - no tags */ readonly tags?: { [key: string]: string; }; } /****************************************************************************** * ATTRS FOR IMPORTED CONSTRUCT *****************************************************************************/ /** * Attributes for specifying an imported Memory. */ export interface MemoryAttributes { /** * The ARN of the memory. * @attribute */ readonly memoryArn: string; /** * The ARN of the IAM role associated to the memory. * @attribute */ readonly roleArn: string; /** * When this memory was last updated. * @default undefined - No last updated timestamp is provided */ readonly updatedAt?: string; /** * Optional KMS encryption key associated with this memory * @default undefined - An AWS managed key is used */ readonly kmsKeyArn?: string; /** * The status of the memory. * @default undefined - No status is provided */ readonly status?: string; /** * The created timestamp of the memory. * @default undefined - No created timestamp is provided */ readonly createdAt?: string; } /****************************************************************************** * Class *****************************************************************************/ /** * Long-term memory store for extracted insights like user preferences, semantic facts and summaries. * Enables knowledge retention across sessions by storing user preferences (e.g. coding style), * semantic facts (e.g. learned info) and interaction summaries for context optimization. * * @see https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html * @resource AWS::BedrockAgentCore::Memory */ export declare class Memory extends MemoryBase { /** Uniquely identifies this class. */ static readonly PROPERTY_INJECTION_ID: string; /** * Static Method for importing an existing Bedrock AgentCore Memory. */ /** * Creates an Memory reference from an existing memory's attributes. * * @param scope - The construct scope * @param id - Identifier of the construct * @param attrs - Attributes of the existing browser custom * @returns An IBrowserCustom reference to the existing browser */ static fromMemoryAttributes(scope: Construct, id: string, attrs: MemoryAttributes): IMemory; /** * The ARN of the memory resource. * @attribute */ readonly memoryArn: string; /** * The name of the memory. * @attribute */ readonly memoryName: string; /** * The id of the memory. * @attribute */ readonly memoryId: string; /** * The expiration days of the memory. */ readonly expirationDuration?: Duration; /** * The failure reason of the browser * @attribute */ readonly failureReason?: string; /** * The description of the memory. */ readonly description?: string; /** * The execution role of the memory. */ readonly executionRole?: iam.IRole; /** * The status of the memory. */ readonly status?: string; /** * The created timestamp of the memory. */ readonly createdAt?: string; /** * The updated at timestamp of the memory. */ readonly updatedAt?: string; /** * Tags applied to this browser resource * A map of key-value pairs for resource tagging * @default - No tags applied */ readonly tags?: { [key: string]: string; }; /** * The principal to grant permissions to */ readonly grantPrincipal: iam.IPrincipal; /** * The KMS key used to encrypt the memory. */ readonly kmsKey?: kms.IKey; /** * The memory strategies used by the memory. * @attribute */ readonly memoryStrategies: IMemoryStrategy[]; private readonly __resource; constructor(scope: Construct, id: string, props: MemoryProps); /** * Add memory strategy to the memory. * @default - No memory strategies. */ addMemoryStrategy(memoryStrategy: IMemoryStrategy): void; /** * Creates execution role needed for the memory to access AWS services * @returns The created role * @internal This is an internal core function and should not be called directly. */ private _createMemoryRole; /** * Validates the memory tags format * @param tags The tags object to validate * @returns Array of validation error messages, empty if valid */ private _validateMemoryTags; /** * Validates the memory name format * @param name The memory name to validate * @returns Array of validation error messages, empty if valid */ private _validateMemoryName; /** * Validates the memory expiration days * @param expirationDays The memory expiration days to validate * @returns Array of validation error messages, empty if valid */ private _validateMemoryExpirationDays; /** * Render the memory strategies. * * @returns Array of MemoryStrategyProperty objects in CloudFormation format, or undefined if no strategies are defined * @default - undefined if no strategies are defined or array is empty * @internal This is an internal core function and should not be called directly. */ private _renderMemoryStrategies; }