Amazon.CDK.AWS.Bedrock.Alpha

Amazon Bedrock 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-alpha

Amazon Bedrock is a fully managed service that offers a choice of high-performing foundation models (FMs) from leading AI companies and Amazon through a single API, along with a broad set of capabilities you need to build generative AI applications with security, privacy, and responsible AI.

This construct library facilitates the deployment of Bedrock Agents, Guardrails, Prompts, Inference Profiles and Knowledge Bases, enabling you to create sophisticated AI applications that can interact with your systems and data sources.

Table of contents

• Agents

  • Create an Agent
  • Action groups
  • Prepare the Agent
  • Prompt Override Configuration
  • Memory Configuration
  • Agent Collaboration
  • Custom Orchestration
  • Agent Alias

• Guardrails

  • Guardrail Properties

  • Filter Types

    • Content Filters
    • Denied Topics
    • Word Filters
    • PII Filters
    • Regex Filters
    • Contextual Grounding Filters

  • Guardrail Methods

  • Guardrail Permissions

  • Guardrail Metrics

  • Importing Guardrails

  • Guardrail Versioning

• Prompts

  • Prompt Variants
  • Basic Text Prompt
  • Chat Prompt
  • Agent Prompt
  • Prompt Properties
  • Prompt Version
  • Import Methods

• Inference Profiles

  • Using Inference Profiles
  • Types of Inference Profiles
  • Prompt Routers
  • Inference Profile Permissions
  • Inference Profiles Import Methods

• Knowledge Bases

  • Create a Vector Knowledge Base
  • Knowledge Base Properties
  • Knowledge Base Permissions
  • Knowledge Base Reflections
  • Importing Knowledge Bases

• Mixins

  • KnowledgeBaseOpenSearchServerlessStorage
  • KnowledgeBaseSupplementalDataStorage

Agents

Amazon Bedrock Agents allow generative AI applications to automate complex, multistep tasks by seamlessly integrating with your company's systems, APIs, and data sources. It uses the reasoning of foundation models (FMs), APIs, and data to break down user requests, gather relevant information, and efficiently complete tasks.

Create an Agent

Building an agent is straightforward and fast. The following example creates an Agent with a simple instruction and default prompts:

var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_HAIKU_V1_0,
    Instruction = "You are a helpful and friendly agent that answers questions about literature."
});

You can also create an agent with a guardrail:

// Create a guardrail to filter inappropriate content
var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails",
    Description = "Legal ethical guardrails."
});

guardrail.AddContentFilter(new ContentFilter {
    Type = ContentFilterType.SEXUAL,
    InputStrength = ContentFilterStrength.HIGH,
    OutputStrength = ContentFilterStrength.MEDIUM
});

// Create an agent with the guardrail
var agentWithGuardrail = new Agent(this, "AgentWithGuardrail", new AgentProps {
    FoundationModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_HAIKU_V1_0,
    Instruction = "You are a helpful and friendly agent that answers questions about literature.",
    Guardrail = guardrail
});

Agent Properties

The Bedrock Agent class supports the following properties.

Name	Type	Required	Description
name	string	No	The name of the agent. Defaults to a name generated by CDK
instruction	string	Yes	The instruction used by the agent that determines how it will perform its task. Must have a minimum of 40 characters
foundationModel	IBedrockInvokable	Yes	The foundation model used for orchestration by the agent
existingRole	iam.IRole	No	The existing IAM Role for the agent to use. Must have a trust policy allowing Bedrock service to assume the role. Defaults to a new created role
shouldPrepareAgent	boolean	No	Specifies whether to automatically update the DRAFT version of the agent after making changes. Defaults to false
idleSessionTTL	Duration	No	How long sessions should be kept open for the agent. Session expires if no conversation occurs during this time. Defaults to 1 hour
kmsKey	kms.IKey	No	The KMS key of the agent if custom encryption is configured. Defaults to AWS managed key
description	string	No	A description of the agent. Defaults to no description
actionGroups	AgentActionGroup[]	No	The Action Groups associated with the agent
guardrail	IGuardrail	No	The guardrail that will be associated with the agent. Defaults to no guardrail
memory	Memory	No	The type and configuration of the memory to maintain context across multiple sessions and recall past interactions. Defaults to no memory
promptOverrideConfiguration	PromptOverrideConfiguration	No	Overrides some prompt templates in different parts of an agent sequence configuration
userInputEnabled	boolean	No	Select whether the agent can prompt additional information from the user when it lacks enough information. Defaults to false
codeInterpreterEnabled	boolean	No	Select whether the agent can generate, run, and troubleshoot code when trying to complete a task. Defaults to false
forceDelete	boolean	No	Whether to delete the resource even if it's in use. Defaults to true
agentCollaboration	AgentCollaboration	No	Configuration for agent collaboration settings, including type and collaborators. This property allows you to define how the agent collaborates with other agents and what collaborators it can work with. Defaults to no agent collaboration configuration
customOrchestrationExecutor	CustomOrchestrationExecutor	No	The Lambda function to use for custom orchestration. If provided, orchestrationType is set to CUSTOM_ORCHESTRATION. If not provided, orchestrationType defaults to DEFAULT. Defaults to default orchestration

Action Groups

An action group defines functions your agent can call. The functions are Lambda functions. The action group uses an OpenAPI schema to tell the agent what your functions do and how to call them.

Action Group Properties

The AgentActionGroup class supports the following properties.

Name	Type	Required	Description
name	string	No	The name of the action group. Defaults to a name generated in the format 'action_group_quick_start_UUID'
description	string	No	A description of the action group
apiSchema	ApiSchema	No	The OpenAPI schema that defines the functions in the action group
executor	ActionGroupExecutor	No	The Lambda function that executes the actions in the group
enabled	boolean	No	Whether the action group is enabled. Defaults to true
forceDelete	boolean	No	Whether to delete the resource even if it's in use. Defaults to false
functionSchema	FunctionSchema	No	Defines functions that each define parameters that the agent needs to invoke from the user
parentActionGroupSignature	ParentActionGroupSignature	No	The AWS Defined signature for enabling certain capabilities in your agent

There are three ways to provide an API schema for your action group:

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

var actionGroupFunction = new Function(this, "ActionGroupFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_12,
    Handler = "index.handler",
    Code = Code.FromAsset(Join(__dirname, "../lambda/action-group"))
});

// When using ApiSchema.fromLocalAsset, you must bind the schema to a scope
var schema = ApiSchema.FromLocalAsset(Join(__dirname, "action-group.yaml"));
schema.Bind(this);

var actionGroup = new AgentActionGroup(new AgentActionGroupProps {
    Name = "query-library",
    Description = "Use these functions to get information about the books in the library.",
    Executor = ActionGroupExecutor.FromLambda(actionGroupFunction),
    Enabled = true,
    ApiSchema = schema
});

var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_HAIKU_V1_0,
    Instruction = "You are a helpful and friendly agent that answers questions about literature."
});

agent.AddActionGroup(actionGroup);

From an inline OpenAPI schema:

var inlineSchema = 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
");

var actionGroupFunction = new Function(this, "ActionGroupFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_12,
    Handler = "index.handler",
    Code = Code.FromAsset(Join(__dirname, "../lambda/action-group"))
});

var actionGroup = new AgentActionGroup(new AgentActionGroupProps {
    Name = "query-library",
    Description = "Use these functions to get information about the books in the library.",
    Executor = ActionGroupExecutor.FromLambda(actionGroupFunction),
    Enabled = true,
    ApiSchema = inlineSchema
});

var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_HAIKU_V1_0,
    Instruction = "You are a helpful and friendly agent that answers questions about literature."
});

agent.AddActionGroup(actionGroup);

From an existing S3 file:

var bucket = Bucket.FromBucketName(this, "ExistingBucket", "my-schema-bucket");
var s3Schema = ApiSchema.FromS3File(bucket, "schemas/action-group.yaml");

var actionGroupFunction = new Function(this, "ActionGroupFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_12,
    Handler = "index.handler",
    Code = Code.FromAsset(Join(__dirname, "../lambda/action-group"))
});

var actionGroup = new AgentActionGroup(new AgentActionGroupProps {
    Name = "query-library",
    Description = "Use these functions to get information about the books in the library.",
    Executor = ActionGroupExecutor.FromLambda(actionGroupFunction),
    Enabled = true,
    ApiSchema = s3Schema
});

var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_HAIKU_V1_0,
    Instruction = "You are a helpful and friendly agent that answers questions about literature."
});

agent.AddActionGroup(actionGroup);

Using FunctionSchema with Action Groups

As an alternative to using OpenAPI schemas, you can define functions directly using the FunctionSchema class. This approach provides a more structured way to define the functions that your agent can call.

var actionGroupFunction = new Function(this, "ActionGroupFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_12,
    Handler = "index.handler",
    Code = Code.FromAsset(Join(__dirname, "../lambda/action-group"))
});

// Define a function schema with parameters
var functionSchema = new FunctionSchema(new FunctionSchemaProps {
    Functions = new [] { new FunctionProps {
        Name = "searchBooks",
        Description = "Search for books in the library catalog",
        Parameters = new Dictionary<string, FunctionParameterProps> {
            { "query", new FunctionParameterProps {
                Type = ParameterType.STRING,
                Required = true,
                Description = "The search query string"
            } },
            { "maxResults", new FunctionParameterProps {
                Type = ParameterType.INTEGER,
                Required = false,
                Description = "Maximum number of results to return"
            } },
            { "includeOutOfPrint", new FunctionParameterProps {
                Type = ParameterType.BOOLEAN,
                Required = false,
                Description = "Whether to include out-of-print books"
            } }
        },
        RequireConfirmation = RequireConfirmation.DISABLED
    }, new FunctionProps {
        Name = "getBookDetails",
        Description = "Get detailed information about a specific book",
        Parameters = new Dictionary<string, FunctionParameterProps> {
            { "bookId", new FunctionParameterProps {
                Type = ParameterType.STRING,
                Required = true,
                Description = "The unique identifier of the book"
            } }
        },
        RequireConfirmation = RequireConfirmation.ENABLED
    } }
});

// Create an action group using the function schema
var actionGroup = new AgentActionGroup(new AgentActionGroupProps {
    Name = "library-functions",
    Description = "Functions for interacting with the library catalog",
    Executor = ActionGroupExecutor.FromLambda(actionGroupFunction),
    FunctionSchema = functionSchema,
    Enabled = true
});

var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_HAIKU_V1_0,
    Instruction = "You are a helpful and friendly agent that answers questions about literature.",
    ActionGroups = new [] { actionGroup }
});

The FunctionSchema approach offers several advantages:

• Type-safe definition of functions and parameters
• Built-in validation of parameter names, descriptions, and other properties
• Clear structure that maps directly to the AWS Bedrock API
• Support for parameter types including string, number, integer, boolean, array, and object
• Option to require user confirmation before executing specific functions

If you chose to load your schema file from S3, the construct will provide the necessary permissions to your agent's execution role to access the schema file from the specific bucket. Similar to performing the operation through the console, the agent execution role will get a permission like:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "AmazonBedrockAgentS3PolicyProd",
            "Effect": "Allow",
            "Action": [
                "s3:GetObject"
            ],
            "Resource": [
                "arn:aws:s3:::<BUCKET_NAME>/<OBJECT_KEY>"
            ],
            "Condition": {
                "StringEquals": {
                    "aws:ResourceAccount": "ACCOUNT_NUMBER"
                }
            }
        }
    ]
}

// create a bucket containing the input schema
var schemaBucket = new Bucket(this, "SchemaBucket", new BucketProps {
    EnforceSSL = true,
    Versioned = true,
    PublicReadAccess = false,
    BlockPublicAccess = BlockPublicAccess.BLOCK_ALL,
    Encryption = BucketEncryption.S3_MANAGED,
    RemovalPolicy = RemovalPolicy.DESTROY,
    AutoDeleteObjects = true
});

// deploy the local schema file to S3
var deployement = new BucketDeployment(this, "DeployWebsite", new BucketDeploymentProps {
    Sources = new [] { Source.Asset(Join(__dirname, "../inputschema")) },
    DestinationBucket = schemaBucket,
    DestinationKeyPrefix = "inputschema"
});

// create the agent
var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0,
    Instruction = "You are a helpful and friendly agent that answers questions about literature.",
    UserInputEnabled = true,
    ShouldPrepareAgent = true
});

// create a lambda function
var actionGroupFunction = new Function(this, "ActionGroupFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_12,
    Handler = "index.handler",
    Code = Code.FromAsset(Join(__dirname, "../lambda/action-group"))
});

// create an action group and read the schema file from S3
var actionGroup = new AgentActionGroup(new AgentActionGroupProps {
    Name = "query-library",
    Description = "Use these functions to get information about the books in the library.",
    Executor = ActionGroupExecutor.FromLambda(actionGroupFunction),
    Enabled = true,
    ApiSchema = ApiSchema.FromS3File(schemaBucket, "inputschema/action-group.yaml")
});

// add the action group to the agent
agent.AddActionGroup(actionGroup);

// add dependency for the agent on the s3 deployment
agent.Node.AddDependency(deployement);

Prepare the Agent

The Agent constructs take an optional parameter shouldPrepareAgent to indicate that the Agent should be prepared after any updates to an agent or action group. This may increase the time to create and update those resources. By default, this value is false.

Prepare Agent Properties

Name	Type	Required	Description
shouldPrepareAgent	boolean	No	Whether to automatically update the DRAFT version of the agent after making changes. Defaults to false

Creating an agent alias will not prepare the agent, so if you create an alias using the AgentAlias resource then you should set shouldPrepareAgent to true.

Prompt Override Configuration

Bedrock Agents allows you to customize the prompts and LLM configuration for different steps in the agent sequence. The implementation provides type-safe configurations for each step type, ensuring correct usage at compile time.

Prompt Override Configuration Properties

Name	Type	Required	Description
steps	PromptStepConfiguration[]	Yes	Array of step configurations for different parts of the agent sequence
parser	lambda.IFunction	No	Lambda function for custom parsing of agent responses

Prompt Step Configuration Properties

Each step in the steps array supports the following properties:

Name	Type	Required	Description
stepType	AgentStepType	Yes	The type of step being configured (PRE_PROCESSING, ORCHESTRATION, POST_PROCESSING, ROUTING_CLASSIFIER, MEMORY_SUMMARIZATION, KNOWLEDGE_BASE_RESPONSE_GENERATION)
stepEnabled	boolean	No	Whether this step is enabled. Defaults to true
customPromptTemplate	string	No	Custom prompt template to use for this step
inferenceConfig	InferenceConfiguration	No	Configuration for model inference parameters
foundationModel	BedrockFoundationModel	No	Alternative foundation model to use for this step (only valid for ROUTING_CLASSIFIER step)
useCustomParser	boolean	No	Whether to use a custom parser for this step. Requires parser to be provided in PromptOverrideConfiguration

Inference Configuration Properties

When providing inferenceConfig, the following properties are supported:

Name	Type	Required	Description
temperature	number	No	Controls randomness in the model's output (0.0-1.0)
topP	number	No	Controls diversity via nucleus sampling (0.0-1.0)
topK	number	No	Controls diversity by limiting the cumulative probability
maximumLength	number	No	Maximum length of generated text
stopSequences	string[]	No	Sequences where the model should stop generating

The following steps can be configured:

• PRE_PROCESSING: Prepares the user input for orchestration
• ORCHESTRATION: Main step that determines the agent's actions
• POST_PROCESSING: Refines the agent's response
• ROUTING_CLASSIFIER: Classifies and routes requests to appropriate collaborators
• MEMORY_SUMMARIZATION: Summarizes conversation history for memory retention
• KNOWLEDGE_BASE_RESPONSE_GENERATION: Generates responses using knowledge base content

Example with pre-processing configuration:

var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.AMAZON_NOVA_LITE_V1,
    Instruction = "You are a helpful assistant.",
    PromptOverrideConfiguration = PromptOverrideConfiguration.FromSteps(new [] { new PromptStepConfigBase {
        StepType = AgentStepType.PRE_PROCESSING,
        StepEnabled = true,
        CustomPromptTemplate = "Your custom prompt template here",
        InferenceConfig = new InferenceConfiguration {
            Temperature = 0,
            TopP = 1,
            TopK = 250,
            MaximumLength = 1,
            StopSequences = new [] { @"

                Human:" }
        }
    } })
});

Example with routing classifier and foundation model:

var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.AMAZON_NOVA_LITE_V1,
    Instruction = "You are a helpful assistant.",
    PromptOverrideConfiguration = PromptOverrideConfiguration.FromSteps(new [] { (PromptRoutingClassifierConfigCustomParser)new PromptRoutingClassifierConfigCustomParser {
        StepType = AgentStepType.ROUTING_CLASSIFIER,
        StepEnabled = true,
        CustomPromptTemplate = "Your routing template here",
        FoundationModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_V2
    } })
});

Using a custom Lambda parser:

var parserFunction = new Function(this, "ParserFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_10,
    Handler = "index.handler",
    Code = Code.FromAsset("lambda")
});

var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.AMAZON_NOVA_LITE_V1,
    Instruction = "You are a helpful assistant.",
    PromptOverrideConfiguration = PromptOverrideConfiguration.WithCustomParser(new CustomParserProps {
        Parser = parserFunction,
        PreProcessingStep = new PromptPreProcessingConfigCustomParser {
            StepType = AgentStepType.PRE_PROCESSING,
            UseCustomParser = true
        }
    })
});

Foundation models can only be specified for the ROUTING_CLASSIFIER step.

Memory Configuration

Agents can maintain context across multiple sessions and recall past interactions using memory. This feature is useful for creating a more coherent conversational experience.

Memory Configuration Properties

Name	Type	Required	Description
maxRecentSessions	number	No	Maximum number of recent session summaries to retain
memoryDuration	Duration	No	How long to retain session summaries

Example:

var agent = new Agent(this, "MyAgent", new AgentProps {
    AgentName = "MyAgent",
    Instruction = "Your instruction here",
    FoundationModel = BedrockFoundationModel.AMAZON_NOVA_LITE_V1,
    Memory = Memory.SessionSummary(new SessionSummaryMemoryProps {
        MaxRecentSessions = 10,  // Keep the last 10 session summaries
        MemoryDuration = Duration.Days(20)
    })
});

Agent Collaboration

Agent Collaboration enables multiple Bedrock Agents to work together on complex tasks. This feature allows agents to specialize in different areas and collaborate to provide more comprehensive responses to user queries.

Agent Collaboration Properties

Name	Type	Required	Description
type	AgentCollaboratorType	Yes	Type of collaboration (SUPERVISOR or PEER)
collaborators	AgentCollaborator[]	Yes	List of agent collaborators

Agent Collaborator Properties

Name	Type	Required	Description
agentAlias	AgentAlias	Yes	The agent alias to collaborate with
collaborationInstruction	string	Yes	Instructions for how to collaborate with this agent
collaboratorName	string	Yes	Name of the collaborator
relayConversationHistory	boolean	No	Whether to relay conversation history to the collaborator. Defaults to false

Example:

// Create a specialized agent
var customerSupportAgent = new Agent(this, "CustomerSupportAgent", new AgentProps {
    Instruction = "You specialize in answering customer support questions.",
    FoundationModel = BedrockFoundationModel.AMAZON_NOVA_LITE_V1
});

// Create an agent alias
var customerSupportAlias = new AgentAlias(this, "CustomerSupportAlias", new AgentAliasProps {
    Agent = customerSupportAgent,
    AgentAliasName = "production"
});

// Create a main agent that collaborates with the specialized agent
var mainAgent = new Agent(this, "MainAgent", new AgentProps {
    Instruction = "You route specialized questions to other agents.",
    FoundationModel = BedrockFoundationModel.AMAZON_NOVA_LITE_V1,
    AgentCollaboration = new Dictionary<string, object> {
        { "type", AgentCollaboratorType.SUPERVISOR },
        { "collaborators", new [] {
            new AgentCollaborator(new AgentCollaboratorProps {
                AgentAlias = customerSupportAlias,
                CollaborationInstruction = "Route customer support questions to this agent.",
                CollaboratorName = "CustomerSupport",
                RelayConversationHistory = true
            }) } }
    }
});

Custom Orchestration

Custom Orchestration allows you to override the default agent orchestration flow with your own Lambda function. This enables more control over how the agent processes user inputs and invokes action groups.

When you provide a customOrchestrationExecutor, the agent's orchestrationType is automatically set to CUSTOM_ORCHESTRATION. If no customOrchestrationExecutor is provided, the orchestrationType defaults to DEFAULT, using Amazon Bedrock's built-in orchestration.

Custom Orchestration Properties

Name	Type	Required	Description
function	lambda.IFunction	Yes	The Lambda function that implements the custom orchestration logic

Example:

var orchestrationFunction = new Function(this, "OrchestrationFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_10,
    Handler = "index.handler",
    Code = Code.FromAsset("lambda/orchestration")
});

var agent = new Agent(this, "CustomOrchestrationAgent", new AgentProps {
    Instruction = "You are a helpful assistant with custom orchestration logic.",
    FoundationModel = BedrockFoundationModel.AMAZON_NOVA_LITE_V1,
    CustomOrchestrationExecutor = CustomOrchestrationExecutor.FromLambda(orchestrationFunction)
});

Agent Alias

After you have sufficiently iterated on your working draft and are satisfied with the behavior of your agent, you can set it up for deployment and integration into your application by creating aliases.

To deploy your agent, you need to create an alias. During alias creation, Amazon Bedrock automatically creates a version of your agent. The alias points to this newly created version. You can point the alias to a previously created version if necessary. You then configure your application to make API calls to that alias.

By default, the Agent resource creates a test alias named 'AgentTestAlias' that points to the 'DRAFT' version. This test alias is accessible via the testAlias property of the agent. You can also create additional aliases for different environments using the AgentAlias construct.

Agent Alias Properties

Name	Type	Required	Description
agent	Agent	Yes	The agent to create an alias for
agentAliasName	string	No	The name of the agent alias. Defaults to a name generated by CDK
description	string	No	A description of the agent alias. Defaults to no description
routingConfiguration	AgentAliasRoutingConfiguration	No	Configuration for routing traffic between agent versions
agentVersion	string	No	The version of the agent to use. If not specified, a new version is created

When redeploying an agent with changes, you must ensure the agent version is updated to avoid deployment failures with "agent already exists" errors. The recommended way to handle this is to include the lastUpdated property in the agent's description, which automatically updates whenever the agent is modified. This ensures a new version is created on each deployment.

Example:

var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_HAIKU_V1_0,
    Instruction = "You are a helpful and friendly agent that answers questions about literature."
});

var agentAlias = new AgentAlias(this, "myAlias", new AgentAliasProps {
    AgentAliasName = "production",
    Agent = agent,
    Description = $"Production version of my agent. Created at {agent.lastUpdated}"
});

Guardrails

Amazon Bedrock's Guardrails feature enables you to implement robust governance and control mechanisms for your generative AI applications, ensuring alignment with your specific use cases and responsible AI policies. Guardrails empowers you to create multiple tailored policy configurations, each designed to address the unique requirements and constraints of different use cases. These policy configurations can then be seamlessly applied across multiple foundation models (FMs) and Agents, ensuring a consistent user experience and standardizing safety, security, and privacy controls throughout your generative AI ecosystem.

With Guardrails, you can define and enforce granular, customizable policies to precisely govern the behavior of your generative AI applications. You can configure the following policies in a guardrail to avoid undesirable and harmful content and remove sensitive information for privacy protection.

Content filters – Adjust filter strengths to block input prompts or model responses containing harmful content. Denied topics – Define a set of topics that are undesirable in the context of your application. These topics will be blocked if detected in user queries or model responses. Word filters – Configure filters to block undesirable words, phrases, and profanity. Such words can include offensive terms, competitor names etc. Sensitive information filters – Block or mask sensitive information such as personally identifiable information (PII) or custom regex in user inputs and model responses. You can create a Guardrail with a minimum blockedInputMessaging, blockedOutputsMessaging and default content filter policy.

Basic Guardrail Creation

TypeScript

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails",
    Description = "Legal ethical guardrails."
});

Guardrail Properties

Property	Type	Required	Description
guardrailName	string	Yes	The name of the guardrail
description	string	No	The description of the guardrail
blockedInputMessaging	string	No	The message to return when the guardrail blocks a prompt. Default: "Sorry, your query violates our usage policy."
blockedOutputsMessaging	string	No	The message to return when the guardrail blocks a model response. Default: "Sorry, I am unable to answer your question because of our usage policy."
kmsKey	IKey	No	A custom KMS key to use for encrypting data. Default: Your data is encrypted by default with a key that AWS owns and manages for you.
crossRegionConfig	GuardrailCrossRegionConfigProperty	No	The cross-region configuration for the guardrail. This enables cross-region inference for enhanced language support and filtering capabilities. Default: No cross-region configuration
contentFilters	ContentFilter[]	No	The content filters to apply to the guardrail
contentFiltersTierConfig	TierConfig	No	The tier configuration to apply to content filters. Default: TierConfig.CLASSIC
deniedTopics	Topic[]	No	Up to 30 denied topics to block user inputs or model responses associated with the topic
topicsTierConfig	TierConfig	No	The tier configuration to apply to topic filters. Default: TierConfig.CLASSIC
wordFilters	string[]	No	The word filters to apply to the guardrail
managedWordListFilters	ManagedWordFilterType[]	No	The managed word filters to apply to the guardrail
piiFilters	PIIFilter[]	No	The PII filters to apply to the guardrail
regexFilters	RegexFilter[]	No	The regular expression (regex) filters to apply to the guardrail
contextualGroundingFilters	ContextualGroundingFilter[]	No	The contextual grounding filters to apply to the guardrail

Filter Types

Content Filters

Content filters allow you to block input prompts or model responses containing harmful content. You can adjust the filter strength and configure separate actions for input and output.

Content Filter Configuration

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails",
    // Configure tier for content filters (optional)
    ContentFiltersTierConfig = TierConfig.STANDARD
});

guardrail.AddContentFilter(new ContentFilter {
    Type = ContentFilterType.SEXUAL,
    InputStrength = ContentFilterStrength.HIGH,
    OutputStrength = ContentFilterStrength.MEDIUM,
    // props below are optional
    InputAction = GuardrailAction.BLOCK,
    InputEnabled = true,
    OutputAction = GuardrailAction.NONE,
    OutputEnabled = true,
    InputModalities = new [] { ModalityType.TEXT, ModalityType.IMAGE },
    OutputModalities = new [] { ModalityType.TEXT }
});

Available content filter types:

• SEXUAL: Describes input prompts and model responses that indicates sexual interest, activity, or arousal
• VIOLENCE: Describes input prompts and model responses that includes glorification of or threats to inflict physical pain
• HATE: Describes input prompts and model responses that discriminate, criticize, insult, denounce, or dehumanize a person or group
• INSULTS: Describes input prompts and model responses that includes demeaning, humiliating, mocking, insulting, or belittling language
• MISCONDUCT: Describes input prompts and model responses that seeks or provides information about engaging in misconduct activity
• PROMPT_ATTACK: Enable to detect and block user inputs attempting to override system instructions

Available content filter strengths:

• NONE: No filtering
• LOW: Light filtering
• MEDIUM: Moderate filtering
• HIGH: Strict filtering

Available guardrail actions:

• BLOCK: Blocks the content from being processed
• ANONYMIZE: Masks the content with an identifier tag
• NONE: Takes no action

Warning: the ANONYMIZE action is not available in all configurations. Please refer to the documentation of each filter to see which ones support

Available modality types:

• TEXT: Text modality for content filters
• IMAGE: Image modality for content filters

Tier Configuration

Guardrails support tier configurations that determine the level of language support and robustness for content and topic filters. You can configure separate tier settings for content filters and topic filters.

Tier Configuration Options

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails",
    // Configure tier for content filters
    ContentFiltersTierConfig = TierConfig.STANDARD,
    // Configure tier for topic filters
    TopicsTierConfig = TierConfig.CLASSIC
});

Available tier configurations:

• CLASSIC: Provides established guardrails functionality supporting English, French, and Spanish languages
• STANDARD: Provides a more robust solution than the CLASSIC tier and has more comprehensive language support. This tier requires that your guardrail use cross-Region inference

Note: The STANDARD tier provides enhanced language support and more comprehensive filtering capabilities, but requires cross-Region inference to be enabled for your guardrail.

Cross-Region Configuration

You can configure a system-defined guardrail profile to use with your guardrail. Guardrail profiles define the destination AWS Regions where guardrail inference requests can be automatically routed. Using guardrail profiles helps maintain guardrail performance and reliability when demand increases.

Cross-Region Configuration Properties

Property	Type	Required	Description
guardrailProfileArn	string	Yes	The ARN of the system-defined guardrail profile that defines the destination AWS Regions where guardrail inference requests can be automatically routed

Cross-Region Configuration Example

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails",
    Description = "Guardrail with cross-region configuration for enhanced language support",
    CrossRegionConfig = new GuardrailCrossRegionConfigProperty {
        GuardrailProfileArn = "arn:aws:bedrock:us-east-1:123456789012:guardrail-profile/my-profile"
    },
    // Use STANDARD tier for enhanced capabilities
    ContentFiltersTierConfig = TierConfig.STANDARD,
    TopicsTierConfig = TierConfig.STANDARD
});

Note: Cross-region configuration is required when using the STANDARD tier for content and topic filters. It helps maintain guardrail performance and reliability when demand increases by automatically routing inference requests to appropriate regions.

You will need to provide the necessary permissions for cross region: https://docs.aws.amazon.com/bedrock/latest/userguide/guardrail-profiles-permissions.html .

Denied Topics

Denied topics allow you to define a set of topics that are undesirable in the context of your application. These topics will be blocked if detected in user queries or model responses. You can configure separate actions for input and output.

Denied Topic Configuration

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails",
    // Configure tier for topic filters (optional)
    TopicsTierConfig = TierConfig.STANDARD
});

// Use a predefined topic
guardrail.AddDeniedTopicFilter(Topic.FINANCIAL_ADVICE);

// Create a custom topic with input/output actions
guardrail.AddDeniedTopicFilter(Topic.Custom(new CustomTopicProps {
    Name = "Legal_Advice",
    Definition = "Offering guidance or suggestions on legal matters, legal actions, interpretation of laws, or legal rights and responsibilities.",
    Examples = new [] { "Can I sue someone for this?", "What are my legal rights in this situation?", "Is this action against the law?", "What should I do to file a legal complaint?", "Can you explain this law to me?" },
    // props below are optional
    InputAction = GuardrailAction.BLOCK,
    InputEnabled = true,
    OutputAction = GuardrailAction.NONE,
    OutputEnabled = true
}));

Word Filters

Word filters allow you to block specific words, phrases, or profanity in user inputs and model responses. You can configure separate actions for input and output.

Word Filter Configuration

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails"
});

// Add managed word list with input/output actions
guardrail.AddManagedWordListFilter(new ManagedWordFilter {
    Type = ManagedWordFilterType.PROFANITY,
    InputAction = GuardrailAction.BLOCK,
    InputEnabled = true,
    OutputAction = GuardrailAction.NONE,
    OutputEnabled = true
});

// Add individual words
guardrail.AddWordFilter(new WordFilter { Text = "drugs" });
guardrail.AddWordFilter(new WordFilter { Text = "competitor" });

// Add words from a file
guardrail.AddWordFilterFromFile("./scripts/wordsPolicy.csv");

PII Filters

PII filters allow you to detect and handle personally identifiable information in user inputs and model responses. You can configure separate actions for input and output.

The PII types are organized into enum-like classes for better type safety and transpilation compatibility:

• GeneralPIIType: General PII types like addresses, emails, names, phone numbers
• FinancePIIType: Financial information like credit card numbers, PINs, SWIFT codes
• InformationTechnologyPIIType: IT-related data like URLs, IP addresses, AWS keys
• USASpecificPIIType: US-specific identifiers like SSNs, passport numbers
• CanadaSpecificPIIType: Canada-specific identifiers like health numbers, SINs
• UKSpecificPIIType: UK-specific identifiers like NHS numbers, NI numbers

PII Filter Configuration

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails"
});

// Add PII filter for addresses with input/output actions
guardrail.AddPIIFilter(new PIIFilter {
    Type = GeneralPIIType.ADDRESS,
    Action = GuardrailAction.BLOCK,
    // below props are optional
    InputAction = GuardrailAction.BLOCK,
    InputEnabled = true,
    OutputAction = GuardrailAction.ANONYMIZE,
    OutputEnabled = true
});

// Add PII filter for credit card numbers with input/output actions
guardrail.AddPIIFilter(new PIIFilter {
    Type = FinancePIIType.CREDIT_DEBIT_CARD_NUMBER,
    Action = GuardrailAction.BLOCK,
    // below props are optional
    InputAction = GuardrailAction.BLOCK,
    InputEnabled = true,
    OutputAction = GuardrailAction.ANONYMIZE,
    OutputEnabled = true
});

// Add PII filter for email addresses
guardrail.AddPIIFilter(new PIIFilter {
    Type = GeneralPIIType.EMAIL,
    Action = GuardrailAction.ANONYMIZE
});

// Add PII filter for US Social Security Numbers
guardrail.AddPIIFilter(new PIIFilter {
    Type = USASpecificPIIType.US_SOCIAL_SECURITY_NUMBER,
    Action = GuardrailAction.BLOCK
});

// Add PII filter for IP addresses
guardrail.AddPIIFilter(new PIIFilter {
    Type = InformationTechnologyPIIType.IP_ADDRESS,
    Action = GuardrailAction.ANONYMIZE
});

Available PII Types

GeneralPIIType:

• ADDRESS: Physical addresses
• AGE: Individual's age
• DRIVER_ID: Driver's license numbers
• EMAIL: Email addresses
• LICENSE_PLATE: Vehicle license plates
• NAME: Individual names
• PASSWORD: Passwords
• PHONE: Phone numbers
• USERNAME: User account names
• VEHICLE_IDENTIFICATION_NUMBER: Vehicle VINs

FinancePIIType:

• CREDIT_DEBIT_CARD_CVV: Card verification codes
• CREDIT_DEBIT_CARD_EXPIRY: Card expiration dates
• CREDIT_DEBIT_CARD_NUMBER: Credit/debit card numbers
• PIN: Personal identification numbers
• SWIFT_CODE: Bank SWIFT codes
• INTERNATIONAL_BANK_ACCOUNT_NUMBER: IBAN numbers

InformationTechnologyPIIType:

• URL: Web addresses
• IP_ADDRESS: IPv4 addresses
• MAC_ADDRESS: Network interface MAC addresses
• AWS_ACCESS_KEY: AWS access key IDs
• AWS_SECRET_KEY: AWS secret access keys

USASpecificPIIType:

• US_BANK_ACCOUNT_NUMBER: US bank account numbers
• US_BANK_ROUTING_NUMBER: US bank routing numbers
• US_INDIVIDUAL_TAX_IDENTIFICATION_NUMBER: US ITINs
• US_PASSPORT_NUMBER: US passport numbers
• US_SOCIAL_SECURITY_NUMBER: US Social Security Numbers

CanadaSpecificPIIType:

• CA_HEALTH_NUMBER: Canadian Health Service Numbers
• CA_SOCIAL_INSURANCE_NUMBER: Canadian Social Insurance Numbers

UKSpecificPIIType:

• UK_NATIONAL_HEALTH_SERVICE_NUMBER: UK NHS numbers
• UK_NATIONAL_INSURANCE_NUMBER: UK National Insurance numbers
• UK_UNIQUE_TAXPAYER_REFERENCE_NUMBER: UK UTR numbers

Regex Filters

Regex filters allow you to detect and handle custom patterns in user inputs and model responses. You can configure separate actions for input and output.

Regex Filter Configuration

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails"
});
// Add regex filter with input/output actions
guardrail.AddRegexFilter(new RegexFilter {
    Name = "TestRegexFilter",
    Pattern = "test-pattern",
    Action = GuardrailAction.ANONYMIZE,
    // below props are optional
    Description = "This is a test regex filter",
    InputAction = GuardrailAction.BLOCK,
    InputEnabled = true,
    OutputAction = GuardrailAction.ANONYMIZE,
    OutputEnabled = true
});

Contextual Grounding Filters

Contextual grounding filters allow you to ensure that model responses are factually correct and relevant to the user's query. You can configure the action and enable/disable the filter.

Contextual Grounding Filter Configuration

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails"
});
// Add contextual grounding filter with action and enabled flag
guardrail.AddContextualGroundingFilter(new ContextualGroundingFilter {
    Type = ContextualGroundingFilterType.GROUNDING,
    Threshold = 0.8,
    // the properties below are optional
    Action = GuardrailAction.BLOCK,
    Enabled = true
});

Guardrail Methods

Method	Description
addContentFilter()	Adds a content filter to the guardrail
addDeniedTopicFilter()	Adds a denied topic filter to the guardrail
addWordFilter()	Adds a word filter to the guardrail
addManagedWordListFilter()	Adds a managed word list filter to the guardrail
addWordFilterFromFile()	Adds word filters from a file to the guardrail
addPIIFilter()	Adds a PII filter to the guardrail
addRegexFilter()	Adds a regex filter to the guardrail
addContextualGroundingFilter()	Adds a contextual grounding filter to the guardrail
createVersion()	Creates a new version of the guardrail

Guardrail Permissions

Guardrails provide methods to grant permissions to other resources that need to interact with the guardrail.

Permission Methods

Method	Description	Parameters
grant(grantee, ...actions)	Grants the given principal identity permissions to perform actions on this guardrail	grantee: The principal to grant permissions to
actions: The actions to grant (e.g., bedrock:GetGuardrail, bedrock:ListGuardrails)
grantApply(grantee)	Grants the given identity permissions to apply the guardrail	grantee: The principal to grant permissions to

Permission Examples

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails"
});

var lambdaFunction = new Function(this, "testLambda", new FunctionProps {
    Runtime = Runtime.PYTHON_3_12,
    Handler = "index.handler",
    Code = Code.FromAsset(Join(__dirname, "../lambda/my-code"))
});

// Grant specific permissions to a Lambda function
guardrail.Grant(lambdaFunction, "bedrock:GetGuardrail", "bedrock:ListGuardrails");

// Grant permissions to apply the guardrail
guardrail.GrantApply(lambdaFunction);

Guardrail Metrics

Amazon Bedrock provides metrics for your guardrails, allowing you to monitor their effectiveness and usage. These metrics are available in CloudWatch and can be used to create dashboards and alarms.

Metrics Examples

using Amazon.CDK.AWS.CloudWatch;


var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails"
});
// Get a specific metric for this guardrail
var invocationsMetric = guardrail.MetricInvocations(new MetricOptions {
    Statistic = "Sum",
    Period = Duration.Minutes(5)
});

// Create a CloudWatch alarm for high invocation latency
// Create a CloudWatch alarm for high invocation latency
new Alarm(this, "HighLatencyAlarm", new AlarmProps {
    Metric = guardrail.MetricInvocationLatency(),
    Threshold = 1000,  // 1 second
    EvaluationPeriods = 3
});

// Get metrics for all guardrails
var allInvocationsMetric = Guardrail.MetricAllInvocations();

Importing Guardrails

You can import existing guardrails using the fromGuardrailAttributes or fromCfnGuardrail methods.

Import Configuration

Stack stack;

var cmk = new Key(this, "cmk", new KeyProps { });
// Import an existing guardrail by ARN
var importedGuardrail = Guardrail.FromGuardrailAttributes(stack, "TestGuardrail", new GuardrailAttributes {
    GuardrailArn = "arn:aws:bedrock:us-east-1:123456789012:guardrail/oygh3o8g7rtl",
    GuardrailVersion = "1",  //optional
    KmsKey = cmk
});

using Amazon.CDK.AWS.Bedrock;

// Import a guardrail created through the L1 CDK CfnGuardrail construct
var l1guardrail = new CfnGuardrail(this, "MyCfnGuardrail", new CfnGuardrailProps {
    BlockedInputMessaging = "blockedInputMessaging",
    BlockedOutputsMessaging = "blockedOutputsMessaging",
    Name = "namemycfnguardrails",
    WordPolicyConfig = new WordPolicyConfigProperty {
        WordsConfig = new [] { new WordConfigProperty {
            Text = "drugs"
        } }
    }
});

var importedGuardrail = Guardrail.FromCfnGuardrail(l1guardrail);

Guardrail Versioning

Guardrails support versioning, allowing you to track changes and maintain multiple versions of your guardrail configurations.

Version Configuration

var guardrail = new Guardrail(this, "bedrockGuardrails", new GuardrailProps {
    GuardrailName = "my-BedrockGuardrails"
});
// Create a new version of the guardrail
guardrail.CreateVersion("testversion");

Prompts

Amazon Bedrock provides the ability to create and save prompts using Prompt management so that you can save time by applying the same prompt to different workflows. You can include variables in the prompt so that you can adjust the prompt for different use case.

The Prompt resource allows you to create a new prompt.

Prompt Variants

Prompt variants in the context of Amazon Bedrock refer to alternative configurations of a prompt, including its message or the model and inference configurations used. Prompt variants are the building blocks of prompts - you must create at least one prompt variant to create a prompt. Prompt variants allow you to create different versions of a prompt, test them, and save the variant that works best for your use case.

There are three types of prompt variants:

• Basic Text Prompt: Simple text-based prompts for straightforward interactions
• Chat variant: Conversational prompts that support system messages, user/assistant message history, and tools
• Agent variant: Prompts designed to work with Bedrock Agents

Basic Text Prompt

Text prompts are the simplest form of prompts, consisting of plain text instructions with optional variables. They are ideal for straightforward tasks like summarization, content generation, or question answering where you need a direct text-based interaction with the model.

var cmk = new Key(this, "cmk", new KeyProps { });
var claudeModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_SONNET_V1_0;

var variant1 = PromptVariant.Text(new TextPromptVariantProps {
    VariantName = "variant1",
    Model = claudeModel,
    PromptVariables = new [] { "topic" },
    PromptText = "This is my first text prompt. Please summarize our conversation on: {{topic}}.",
    InferenceConfiguration = PromptInferenceConfiguration.Text(new PromptInferenceConfigurationProps {
        Temperature = 1,
        TopP = 0.999,
        MaxTokens = 2000
    })
});

var prompt1 = new Prompt(this, "prompt1", new PromptProps {
    PromptName = "prompt1",
    Description = "my first prompt",
    DefaultVariant = variant1,
    Variants = new [] { variant1 },
    KmsKey = cmk
});

Chat Prompt

Use this template type when the model supports the Converse API or the Anthropic Claude Messages API. This allows you to include a System prompt and previous User messages and Assistant messages for context.

var cmk = new Key(this, "cmk", new KeyProps { });

var variantChat = PromptVariant.Chat(new ChatPromptVariantProps {
    VariantName = "variant1",
    Model = BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0,
    Messages = new [] { ChatMessage.User("From now on, you speak Japanese!"), ChatMessage.Assistant("Konnichiwa!"), ChatMessage.User("From now on, you speak {{language}}!") },
    System = "You are a helpful assistant that only speaks the language you`re told.",
    PromptVariables = new [] { "language" },
    ToolConfiguration = new ToolConfiguration {
        ToolChoice = ToolChoice.AUTO,
        Tools = new [] { Tool.Function(new FunctionToolProps {
            Name = "top_song",
            Description = "Get the most popular song played on a radio station.",
            InputSchema = new Dictionary<string, object> {
                { "type", "object" },
                { "properties", new Struct {
                    Sign = new Struct {
                        Type = "string",
                        Description = "The call sign for the radio station for which you want the most popular song. Example calls signs are WZPZ and WKR."
                    }
                } },
                { "required", new [] { "sign" } }
            }
        }) }
    }
});

new Prompt(this, "prompt1", new PromptProps {
    PromptName = "prompt-chat",
    Description = "my first chat prompt",
    DefaultVariant = variantChat,
    Variants = new [] { variantChat },
    KmsKey = cmk
});

Agent Prompt

Agent prompts are designed to work with Bedrock Agents, allowing you to create prompts that can be used by agents to perform specific tasks. Agent prompts use text prompts as their foundation and can reference agent aliases and include custom instructions for how the agent should behave.

var cmk = new Key(this, "cmk", new KeyProps { });

// Assuming you have an existing agent and alias
var agent = Agent.FromAgentAttributes(this, "ImportedAgent", new AgentAttributes {
    AgentArn = "arn:aws:bedrock:region:account:agent/agent-id",
    RoleArn = "arn:aws:iam::account:role/agent-role"
});

var agentAlias = AgentAlias.FromAttributes(this, "ImportedAlias", new AgentAliasAttributes {
    AliasId = "alias-id",
    AliasName = "my-alias",
    AgentVersion = "1",
    Agent = agent
});

var agentVariant = PromptVariant.Agent(new AgentPromptVariantProps {
    VariantName = "agent-variant",
    Model = BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0,
    AgentAlias = agentAlias,
    PromptText = "Use the agent to help with: {{task}}. Please be thorough and provide detailed explanations.",
    PromptVariables = new [] { "task" }
});

new Prompt(this, "agentPrompt", new PromptProps {
    PromptName = "agent-prompt",
    Description = "Prompt for agent interactions",
    DefaultVariant = agentVariant,
    Variants = new [] { agentVariant },
    KmsKey = cmk
});

Prompt Properties

Property	Type	Required	Description
promptName	string	Yes	The name of the prompt
description	string	No	A description of the prompt
defaultVariant	PromptVariant	Yes	The default variant to use for the prompt
variants	PromptVariant[]	No	Additional variants for the prompt
kmsKey	kms.IKey	No	The KMS key to use for encrypting the prompt. Defaults to AWS managed key
tags	Record<string, string>	No	Tags to apply to the prompt

Prompt Version

A prompt version is a snapshot of a prompt at a specific point in time that you create when you are satisfied with a set of configurations. Versions allow you to deploy your prompt and easily switch between different configurations for your prompt and update your application with the most appropriate version for your use-case.

You can create a Prompt version by using the PromptVersion class or by using the .createVersion(..) on a Prompt object. It is recommended to use the .createVersion(..) method. It uses a hash based mechanism to update the version whenever a certain configuration property changes.

var cmk = new Key(this, "cmk", new KeyProps { });
var claudeModel = BedrockFoundationModel.ANTHROPIC_CLAUDE_SONNET_V1_0;

var variant1 = PromptVariant.Text(new TextPromptVariantProps {
    VariantName = "variant1",
    Model = claudeModel,
    PromptVariables = new [] { "topic" },
    PromptText = "This is my first text prompt. Please summarize our conversation on: {{topic}}.",
    InferenceConfiguration = PromptInferenceConfiguration.Text(new PromptInferenceConfigurationProps {
        Temperature = 1,
        TopP = 0.999,
        MaxTokens = 2000
    })
});

var prompt1 = new Prompt(this, "prompt1", new PromptProps {
    PromptName = "prompt1",
    Description = "my first prompt",
    DefaultVariant = variant1,
    Variants = new [] { variant1 },
    KmsKey = cmk
});

var promptVersion = new PromptVersion(this, "MyPromptVersion", new PromptVersionProps {
    Prompt = prompt1,
    Description = "my first version"
});
//or alternatively:
// const promptVersion = prompt1.createVersion('my first version');
var versionString = promptVersion.Version;

Import Methods

You can use the fromPromptAttributes method to import an existing Bedrock Prompt into your CDK application.

// Import an existing prompt by ARN
var importedPrompt = Prompt.FromPromptAttributes(this, "ImportedPrompt", new PromptAttributes {
    PromptArn = "arn:aws:bedrock:region:account:prompt/prompt-id",
    KmsKey = Key.FromKeyArn(this, "ImportedKey", "arn:aws:kms:region:account:key/key-id"),  // optional
    PromptVersion = "1"
});

Inference Profiles

Amazon Bedrock Inference Profiles provide a way to manage and optimize inference configurations for your foundation models. They allow you to define reusable configurations that can be applied across different prompts and agents.

Using Inference Profiles

Inference profiles can be used with prompts and agents to maintain consistent inference configurations across your application.

With Agents

// Create a cross-region inference profile
var crossRegionProfile = CrossRegionInferenceProfile.FromConfig(new CrossRegionInferenceProfileProps {
    GeoRegion = CrossRegionInferenceProfileRegion.US,
    Model = BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0
});

// Use the cross-region profile with an agent
var agent = new Agent(this, "Agent", new AgentProps {
    FoundationModel = crossRegionProfile,
    Instruction = "You are a helpful and friendly agent that answers questions about agriculture."
});

With Prompts

// Create a prompt router for intelligent model selection
var promptRouter = PromptRouter.FromDefaultId(DefaultPromptRouterIdentifier.ANTHROPIC_CLAUDE_V1, "us-east-1");

// Use the prompt router with a prompt variant
var variant = PromptVariant.Text(new TextPromptVariantProps {
    VariantName = "variant1",
    PromptText = "What is the capital of France?",
    Model = promptRouter
});

new Prompt(this, "Prompt", new PromptProps {
    PromptName = "prompt-router-test",
    Variants = new [] { variant }
});

Types of Inference Profiles

Amazon Bedrock offers two types of inference profiles:

Application Inference Profiles

Application inference profiles are user-defined profiles that help you track costs and model usage. They can be created for a single region or for multiple regions using a cross-region inference profile.

Single Region Application Profile

// Create an application inference profile for one Region
var appProfile = new ApplicationInferenceProfile(this, "MyApplicationProfile", new ApplicationInferenceProfileProps {
    ApplicationInferenceProfileName = "claude-3-sonnet-v1",
    ModelSource = BedrockFoundationModel.ANTHROPIC_CLAUDE_SONNET_V1_0,
    Description = "Application profile for cost tracking",
    Tags = new Dictionary<string, string> {
        { "Environment", "Production" }
    }
});

Multi-Region Application Profile

// Create a cross-region inference profile
var crossRegionProfile = CrossRegionInferenceProfile.FromConfig(new CrossRegionInferenceProfileProps {
    GeoRegion = CrossRegionInferenceProfileRegion.US,
    Model = BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V2_0
});

// Create an application inference profile across regions
var appProfile = new ApplicationInferenceProfile(this, "MyMultiRegionProfile", new ApplicationInferenceProfileProps {
    ApplicationInferenceProfileName = "claude-35-sonnet-v2-multi-region",
    ModelSource = crossRegionProfile,
    Description = "Multi-region application profile for cost tracking"
});

System Defined Inference Profiles

Cross-region inference enables you to seamlessly manage unplanned traffic bursts by utilizing compute across different AWS Regions. With cross-region inference, you can distribute traffic across multiple AWS Regions, enabling higher throughput and enhanced resilience during periods of peak demands.

Before using a CrossRegionInferenceProfile, ensure that you have access to the models and regions defined in the inference profiles. For instance, if you use the system defined inference profile "us.anthropic.claude-3-5-sonnet-20241022-v2:0", inference requests will be routed to US East (Virginia) us-east-1, US East (Ohio) us-east-2 and US West (Oregon) us-west-2. Thus, you need to have model access enabled in those regions for the model anthropic.claude-3-5-sonnet-20241022-v2:0.

System Defined Profile Configuration

var crossRegionProfile = CrossRegionInferenceProfile.FromConfig(new CrossRegionInferenceProfileProps {
    GeoRegion = CrossRegionInferenceProfileRegion.US,
    Model = BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V2_0
});

Prompt Routers

Amazon Bedrock intelligent prompt routing provides a single serverless endpoint for efficiently routing requests between different foundational models within the same model family. It can help you optimize for response quality and cost. They offer a comprehensive solution for managing multiple AI models through a single serverless endpoint, simplifying the process for you. Intelligent prompt routing predicts the performance of each model for each request, and dynamically routes each request to the model that it predicts is most likely to give the desired response at the lowest cost.

Default and Custom Prompt Routers

// Use a default prompt router
var variant = PromptVariant.Text(new TextPromptVariantProps {
    VariantName = "variant1",
    PromptText = "What is the capital of France?",
    Model = PromptRouter.FromDefaultId(DefaultPromptRouterIdentifier.ANTHROPIC_CLAUDE_V1, "us-east-1")
});

new Prompt(this, "Prompt", new PromptProps {
    PromptName = "prompt-router-test",
    Variants = new [] { variant }
});

Inference Profile Permissions

Use the grantProfileUsage method to grant appropriate permissions to resources that need to use the inference profile.

Granting Profile Usage Permissions

// Create an application inference profile
var profile = new ApplicationInferenceProfile(this, "MyProfile", new ApplicationInferenceProfileProps {
    ApplicationInferenceProfileName = "my-profile",
    ModelSource = BedrockFoundationModel.ANTHROPIC_CLAUDE_SONNET_4_5_V1_0
});

// Create a Lambda function
var lambdaFunction = new Function(this, "MyFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_11,
    Handler = "index.handler",
    Code = Code.FromInline("def handler(event, context): return \"Hello\"")
});

// Grant the Lambda function permission to use the inference profile
profile.GrantProfileUsage(lambdaFunction);

// Use a system defined inference profile
var crossRegionProfile = CrossRegionInferenceProfile.FromConfig(new CrossRegionInferenceProfileProps {
    GeoRegion = CrossRegionInferenceProfileRegion.US,
    Model = BedrockFoundationModel.ANTHROPIC_CLAUDE_SONNET_4_5_V1_0
});

// Grant permissions to use the cross-region inference profile
crossRegionProfile.GrantProfileUsage(lambdaFunction);

The grantProfileUsage method adds the necessary IAM permissions to the resource, allowing it to use the inference profile. This includes permissions to call bedrock:GetInferenceProfile and bedrock:ListInferenceProfiles actions on the inference profile resource.

Inference Profiles Import Methods

You can import existing application inference profiles using the following methods:

// Import an inference profile through attributes
var importedProfile = ApplicationInferenceProfile.FromApplicationInferenceProfileAttributes(this, "ImportedProfile", new ApplicationInferenceProfileAttributes {
    InferenceProfileArn = "arn:aws:bedrock:us-east-1:123456789012:application-inference-profile/my-profile-id",
    InferenceProfileIdentifier = "my-profile-id"
});

You can also import an application inference profile from an existing L1 CloudFormation construct:

// Create or reference an existing L1 CfnApplicationInferenceProfile
var cfnProfile = new CfnApplicationInferenceProfile(this, "CfnProfile", new CfnApplicationInferenceProfileProps {
    InferenceProfileName = "my-cfn-profile",
    ModelSource = new InferenceProfileModelSourceProperty {
        CopyFrom = BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0.InvokableArn
    },
    Description = "Profile created via L1 construct"
});

// Import the L1 construct as an L2 ApplicationInferenceProfile
var importedFromCfn = ApplicationInferenceProfile.FromCfnApplicationInferenceProfile(cfnProfile);

// Grant permissions to use the imported profile
var lambdaFunction = new Function(this, "MyFunction", new FunctionProps {
    Runtime = Runtime.PYTHON_3_11,
    Handler = "index.handler",
    Code = Code.FromInline("def handler(event, context): return \"Hello\"")
});

importedFromCfn.GrantProfileUsage(lambdaFunction);

Knowledge Bases

Amazon Bedrock Knowledge Bases give foundation models and agents contextual information from your own data sources (Retrieval Augmented Generation). A vector knowledge base converts your documents into vector embeddings with an embeddings model, stores them in a vector store, and retrieves the most relevant chunks for a query.

Create a Vector Knowledge Base

Create a KnowledgeBase and choose its type with a KnowledgeBaseType factory method. A vector knowledge base, created with KnowledgeBaseType.vector(), needs an embeddings model and a vector store. The vector store must already exist: create the OpenSearch Serverless collection and its vector index, then reference them.

ICollectionRef collection;


var knowledgeBase = new KnowledgeBase(this, "KnowledgeBase", new KnowledgeBaseProps {
    Type = KnowledgeBaseType.Vector(new VectorKnowledgeBaseTypeProps {
        EmbeddingsModel = BedrockFoundationModel.TITAN_EMBED_TEXT_V2_1024,
        VectorStore = VectorStore.OpenSearchServerless(new OpenSearchServerlessVectorStoreProps {
            Collection = collection,
            VectorIndexName = "bedrock-knowledge-base-default-index",
            VectorField = "bedrock-knowledge-base-default-vector",
            TextField = "AMAZON_BEDROCK_TEXT_CHUNK",
            MetadataField = "AMAZON_BEDROCK_METADATA"
        })
    })
});

The construct creates a service role trusted by bedrock.amazonaws.com, scoped to knowledge bases in your account, and grants it permission to invoke the embeddings model and to access the collection (aoss:APIAccessAll).

Specify the index name and the names of its vector, text and metadata fields exactly as they are defined in your index:

ICollectionRef collection;


var vectorStore = VectorStore.OpenSearchServerless(new OpenSearchServerlessVectorStoreProps {
    Collection = collection,
    VectorIndexName = "product-docs",
    VectorField = "embedding",
    TextField = "chunk",
    MetadataField = "metadata"
});

The vector index should use the faiss engine, as the Amazon Bedrock User Guide instructs, and a knn_vector field whose dimension matches the embeddings model (for example 1024 for TITAN_EMBED_TEXT_V2_1024). The collection's data access policy must also allow the knowledge base role to read and write documents in the index; the construct cannot create either of these for you. See Prerequisites for your own vector store in the Amazon Bedrock User Guide.

Knowledge Base Properties

ICollectionRef collection;
Role role;
IBucket multimodalBucket;


new KnowledgeBase(this, "KnowledgeBase", new KnowledgeBaseProps {
    KnowledgeBaseName = "product-documentation",
    Description = "Product manuals and release notes",
    Type = KnowledgeBaseType.Vector(new VectorKnowledgeBaseTypeProps {
        EmbeddingsModel = BedrockFoundationModel.COHERE_EMBED_MULTILINGUAL_V3,
        // Store binary vectors: less precise, but cheaper to store and search
        VectorType = VectorType.BINARY,
        VectorStore = VectorStore.OpenSearchServerless(new OpenSearchServerlessVectorStoreProps {
            Collection = collection,
            VectorIndexName = "bedrock-knowledge-base-default-index",
            VectorField = "bedrock-knowledge-base-default-vector",
            TextField = "AMAZON_BEDROCK_TEXT_CHUNK",
            MetadataField = "AMAZON_BEDROCK_METADATA"
        }),
        // Where images, audio and video extracted from multimodal documents are stored
        SupplementalDataStorageBucket = multimodalBucket
    }),
    // Bring your own service role; the model and vector store permissions are added to it
    Role = role,
    Tags = new Dictionary<string, string> {
        { "Team", "Documentation" }
    }
});

KnowledgeBase properties:

Property	Required	Description
type	Yes	The type of the knowledge base and its type-specific configuration; created with a KnowledgeBaseType factory method
knowledgeBaseName	No	1-100 letters, digits, hyphens and underscores; no consecutive hyphens or underscores. Defaults to a generated name
description	No	1-200 characters
role	No	Service role assumed by Amazon Bedrock. Defaults to a new role
tags	No	Tags applied to the knowledge base

KnowledgeBaseType.vector() properties:

Property	Required	Description
embeddingsModel	Yes	A BedrockFoundationModel with supportsKnowledgeBase set to true. Changing it replaces the knowledge base
vectorStore	Yes	Where embeddings are stored; created with a VectorStore factory method. Changing it replaces the knowledge base
vectorType	No	VectorType.FLOATING_POINT or VectorType.BINARY; the embeddings model must support it. Defaults to floating-point
supplementalDataStorageBucket	No	S3 bucket in which multimedia content extracted from multimodal documents is stored; Amazon Bedrock manages the layout within the bucket, and the service role is granted access to it. Required for multimodal ingestion

Knowledge Base Permissions

Permissions to query a knowledge base are granted through the grants property. retrieveAndGenerate applies to all knowledge bases because the bedrock:RetrieveAndGenerate action does not support resource-level permissions; combine it with retrieve to scope the retrieval step to this knowledge base. Generating a response also requires bedrock:InvokeModel on the generation model, which BedrockFoundationModel.grantInvoke() provides.

IKnowledgeBase knowledgeBase;
Role role;


// Retrieve chunks from this knowledge base
knowledgeBase.Grants.Retrieve(role);

// Retrieve chunks and generate a response with a foundation model
knowledgeBase.Grants.RetrieveAndGenerate(role);
BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0.GrantInvoke(role);

// Download or view the source documents behind Retrieve results (GetDocumentContent)
knowledgeBase.Grants.GetDocumentContent(role);

To add permissions to the knowledge base service role, for example to let it read a data source, use addToRolePolicy(). For an imported knowledge base whose role was not provided, the statement cannot be applied and a warning is emitted with the statement to add manually.

IKnowledgeBase knowledgeBase;


knowledgeBase.AddToRolePolicy(new PolicyStatement(new PolicyStatementProps {
    Actions = new [] { "s3:GetObject", "s3:ListBucket" },
    Resources = new [] { "arn:aws:s3:::my-documents", "arn:aws:s3:::my-documents/*" }
}));

Knowledge Base Reflections

The reflections facade resolves the underlying CfnKnowledgeBase from the construct tree. Use it to read CloudFormation attributes such as Status, FailureReasons, CreatedAt and UpdatedAt. Accessing reflections.knowledgeBase throws for imported knowledge bases, because they have no underlying resource in the app.

IKnowledgeBase knowledgeBase;


var cfnKnowledgeBase = knowledgeBase.Reflections.KnowledgeBase;
var status = cfnKnowledgeBase.AttrStatus;

Importing Knowledge Bases

Reference a knowledge base created outside of this stack by ARN or by ID. Provide the service role if constructs in this stack need to grant permissions to it.

Role role;


var byArn = KnowledgeBase.FromKnowledgeBaseArn(this, "ImportedByArn", "arn:aws:bedrock:us-east-1:123456789012:knowledge-base/KB12345678");

// Assumed to be in the same account and region as this stack
var byId = KnowledgeBase.FromKnowledgeBaseId(this, "ImportedById", "KB12345678");

var withRole = KnowledgeBase.FromKnowledgeBaseAttributes(this, "ImportedWithRole", new KnowledgeBaseAttributes {
    KnowledgeBaseArn = "arn:aws:bedrock:us-east-1:123456789012:knowledge-base/KB12345678",
    Role = role
});

Mixins

Mixins add a feature to an L1 or L2 construct with .with(). See the mixins overview in the aws-cdk-lib documentation.

The mixins grant permissions to the knowledge base's role. On a CfnKnowledgeBase, roleArn must reference an iam.Role defined in your app; for an imported role or one used with withoutPolicyUpdates(), use KnowledgeBase.

KnowledgeBaseTypeConfiguration

Configures a knowledge base as a KnowledgeBaseType. This applies the type-specific configuration that the type property of KnowledgeBase applies, so you can configure a CfnKnowledgeBase from the same KnowledgeBaseType you would pass to the L2.

ICollectionRef collection;
Role role;


new CfnKnowledgeBase(this, "KnowledgeBase", new CfnKnowledgeBaseProps {
    Name = "product-documentation",
    RoleArn = role.RoleArn,
    KnowledgeBaseConfiguration = new KnowledgeBaseConfigurationProperty { Type = "VECTOR" }
}).With(new Mixins.KnowledgeBaseTypeConfiguration(KnowledgeBaseType.Vector(new VectorKnowledgeBaseTypeProps {
    EmbeddingsModel = BedrockFoundationModel.TITAN_EMBED_TEXT_V2_1024,
    VectorStore = VectorStore.OpenSearchServerless(new OpenSearchServerlessVectorStoreProps {
        Collection = collection,
        VectorIndexName = "bedrock-knowledge-base-default-index",
        VectorField = "bedrock-knowledge-base-default-vector",
        TextField = "AMAZON_BEDROCK_TEXT_CHUNK",
        MetadataField = "AMAZON_BEDROCK_METADATA"
    })
})));

To configure only some features, apply the individual mixins below instead.

KnowledgeBaseEmbeddingsModel

Configures the embeddings model of a vector knowledge base. This is the mixin that the embeddingsModel and vectorType properties of KnowledgeBaseType.vector() apply for you; use it directly when you build a knowledge base from the L1 construct.

Role role;


new CfnKnowledgeBase(this, "KnowledgeBase", new CfnKnowledgeBaseProps {
    Name = "product-documentation",
    RoleArn = role.RoleArn,
    KnowledgeBaseConfiguration = new KnowledgeBaseConfigurationProperty { Type = "VECTOR" }
}).With(new Mixins.KnowledgeBaseEmbeddingsModel(new KnowledgeBaseEmbeddingsModelProps {
    EmbeddingsModel = BedrockFoundationModel.TITAN_EMBED_TEXT_V2_1024
}));

Applying the mixin:

• sets EmbeddingModelArn and EmbeddingDataType (defaults to FLOAT32) on the knowledge base's VectorKnowledgeBaseConfiguration, and Dimensions for models with a configurable dimension. It merges with the existing configuration, and fails at synthesis if the knowledge base is not of type VECTOR.
• throws if the model does not support knowledge bases or the vector type.
• grants the role referenced by the knowledge base's roleArn bedrock:InvokeModel* and bedrock:GetFoundationModel on the model, and makes the knowledge base depend on that policy.

KnowledgeBaseOpenSearchServerlessStorage

Configures an AWS::Bedrock::KnowledgeBase to use an existing Amazon OpenSearch Serverless vector index as its vector store. This is the mixin that VectorStore.openSearchServerless() applies for you; use it directly when you build a knowledge base from the L1 construct.

ICollectionRef collection;
Role role;


new CfnKnowledgeBase(this, "KnowledgeBase", new CfnKnowledgeBaseProps {
    Name = "product-documentation",
    RoleArn = role.RoleArn,
    KnowledgeBaseConfiguration = new KnowledgeBaseConfigurationProperty {
        Type = "VECTOR",
        VectorKnowledgeBaseConfiguration = new VectorKnowledgeBaseConfigurationProperty {
            EmbeddingModelArn = BedrockFoundationModel.TITAN_EMBED_TEXT_V2_1024.ModelArn
        }
    }
}).With(new Mixins.KnowledgeBaseOpenSearchServerlessStorage(new KnowledgeBaseOpenSearchServerlessStorageProps {
    Collection = collection,
    VectorIndexName = "bedrock-knowledge-base-default-index",
    VectorField = "bedrock-knowledge-base-default-vector",
    TextField = "AMAZON_BEDROCK_TEXT_CHUNK",
    MetadataField = "AMAZON_BEDROCK_METADATA"
}));

Applying the mixin:

• sets StorageConfiguration to type OPENSEARCH_SERVERLESS with the given collection, index name and field mapping. The mixin does not merge with an existing storage configuration: it throws if the knowledge base already has one, and fails at synthesis if the knowledge base is not of type VECTOR.
• grants aoss:APIAccessAll on the collection to the role referenced by the knowledge base's roleArn and makes the knowledge base depend on that policy.

It does not create the index or the collection's data access policy.

KnowledgeBaseSupplementalDataStorage

Configures the Amazon S3 bucket in which a vector knowledge base stores the images, audio and video segments it extracts from multimodal documents. This is the mixin that the supplementalDataStorageBucket property of KnowledgeBaseType.vector() applies for you; use it directly when you build a knowledge base from the L1 construct.

CfnKnowledgeBase knowledgeBase;
IBucket bucket;


knowledgeBase.With(new Mixins.KnowledgeBaseSupplementalDataStorage(new KnowledgeBaseSupplementalDataStorageProps {
    Bucket = bucket
}));

Applying the mixin:

• sets SupplementalDataStorageConfiguration on the knowledge base's VectorKnowledgeBaseConfiguration, merging with the existing configuration and replacing any supplemental data storage location already configured. It fails at synthesis if the knowledge base is not of type VECTOR.
• grants the role referenced by the knowledge base's roleArn s3:ListBucket on the bucket and s3:GetObject, s3:PutObject and s3:DeleteObject on its objects, and makes the knowledge base depend on that policy.

Multimodal ingestion also requires a data source configured with a multimodal parser; see Choosing your multimodal processing approach.