From adb76925990fdd09618d7572194b1a68b247b327 Mon Sep 17 00:00:00 2001 From: Dinesh Sajwan Date: Thu, 30 Jan 2025 11:18:03 -0500 Subject: [PATCH] chore(documentation): updated bedrock readme file (#924) * chore(documentation): updated bedrock readme file --------- Co-authored-by: dinsajwa --- src/cdk-lib/bedrock/README.md | 198 +++++++++++++++++++++++++++++++--- 1 file changed, 186 insertions(+), 12 deletions(-) diff --git a/src/cdk-lib/bedrock/README.md b/src/cdk-lib/bedrock/README.md index 9f95e873..7a3611e1 100644 --- a/src/cdk-lib/bedrock/README.md +++ b/src/cdk-lib/bedrock/README.md @@ -19,9 +19,9 @@ | ![Typescript Logo](https://docs.aws.amazon.com/cdk/api/latest/img/typescript32.png) TypeScript | `@cdklabs/generative-ai-cdk-constructs` | | ![Python Logo](https://docs.aws.amazon.com/cdk/api/latest/img/python32.png) Python | `cdklabs.generative_ai_cdk_constructs` | -[Amazon Bedrock](https://aws.amazon.com/bedrock/) is a fully managed service that offers a choice of foundation models (FMs) along with a broad set of capabilities for building generative AI applications. +[Amazon Bedrock](https://aws.amazon.com/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 includes CloudFormation L1 resources to deploy Bedrock features. +This construct library facilitates the deployment of Knowledge Bases, Bedrock Agents, Guardrails, Prompt Management, and Inference Pipelines. It leverages underlying CloudFormation L1 resources to provision these Bedrock features. ## Table of contents @@ -38,7 +38,7 @@ See the [API documentation](../../../apidocs/namespaces/bedrock/README.md). ## Knowledge Bases -With Knowledge Bases for Amazon Bedrock, you can give FMs and agents contextual information from your company’s private data sources for Retrieval Augmented Generation (RAG) to deliver more relevant, accurate, and customized responses. +Amazon Bedrock Knowledge Bases enable you to provide foundation models and agents with contextual information from your company’s private data sources. This enhances the relevance, accuracy, and customization of their responses. ### Create a Knowledge Base @@ -48,6 +48,25 @@ The resource accepts an `instruction` prop that is provided to any Bedrock Agent Amazon Bedrock Knowledge Bases currently only supports S3 as a data source. The `S3DataSource` resource is used to configure how the Knowledge Base handles the data source. +## Knowledge Base Properties + + +| Name | Type | Required | Description | +|---|---|---|---| +| embeddingsModel | BedrockFoundationModel | Yes | The embeddings model for the knowledge base | +| name | string | No | The name of the knowledge base | +| description | string | No | The description of the knowledge base | +| instruction | string | No | Instructions for agents based on the design and type of information of the Knowledge Base that will impact how Agents interact with the Knowledge Base | +| existingRole | iam.IRole | No | Existing IAM role with a policy statement granting permission to invoke the specific embeddings model | +| indexName | string | No | The name of the vector index (only applicable if vectorStore is of type VectorCollection) | +| vectorField | string | No | The name of the field in the vector index (only applicable if vectorStore is of type VectorCollection) | +| vectorStore | VectorCollection \| PineconeVectorStore \| AmazonAuroraVectorStore \| ExistingAmazonAuroraVectorStore | No | The vector store for the knowledge base | +| vectorIndex | VectorIndex | No | The vector index for the OpenSearch Serverless backed knowledge base | +| knowledgeBaseState | string | No | Specifies whether to use the knowledge base or not when sending an InvokeAgent request | +| tags | Record | No | Tag (KEY-VALUE) bedrock agent resource | + +## Initializer + Example of `OpenSearch Serverless`: TypeScript @@ -595,7 +614,7 @@ class PythonTestStack(Stack): Python ```python - ChunkingStrategy.DEFAULT; + ChunkingStrategy.DEFAULT ``` - **Fixed Size Chunking**: This method divides the data into fixed-size chunks, with each chunk @@ -617,7 +636,7 @@ class PythonTestStack(Stack): ```python # Fixed Size Chunking with sane defaults. - ChunkingStrategy.FIXED_SIZE; + ChunkingStrategy.FIXED_SIZE # Fixed Size Chunking with custom values. ChunkingStrategy.fixed_size( @@ -706,7 +725,7 @@ class PythonTestStack(Stack): Python ```python - ChunkingStrategy.NONE; + ChunkingStrategy.NONE ``` #### Knowledge Base - Parsing Strategy @@ -769,12 +788,35 @@ CustomTransformation.lambda_( ## Agents -Enable generative AI applications to execute multistep tasks across company systems and data sources. +Amazon Bedrock Agents allow generative AI applications to automate complex, multistep tasks by seamlessly integrating with your company’s systems, APIs, and data sources. + + +### Agent 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 | IInvokable | 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 | +| knowledgeBases | IKnowledgeBase[] | No | The KnowledgeBases associated with the agent | +| actionGroups | AgentActionGroup[] | No | The Action Groups associated with the agent | +| guardrail | IGuardrail | No | The guardrail that will be associated with the agent | +| 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 | ### Create an Agent The following example creates an Agent with a simple instruction and default prompts that consults a Knowledge Base. +### Initializer + TypeScript ```ts @@ -795,7 +837,7 @@ agent = bedrock.Agent( foundation_model=bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_HAIKU_V1_0, instruction="You are a helpful and friendly agent that answers questions about insurance claims.", ) - agent.add_knowledge_base(kb); + agent.add_knowledge_base(kb) ``` You can also use system defined inference profiles to enable cross region inference requests for supported models. For instance: @@ -836,6 +878,22 @@ For more information on cross region inference, please refer to [System defined 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 + +| Name | Type | Required | Description | +|---|---|---|---| +| name | string | Yes | The name of the action group | +| description | string | No | A description of the action group | +| apiSchema | ApiSchema | No | The API Schema | +| executor | ActionGroupExecutor | No | The action group executor | +| enabled | boolean | No | Specifies whether the action group is available for the agent to invoke or not when sending an InvokeAgent request. Defaults to true | +| forceDelete | boolean | No | Specifies whether to delete the resource even if it's in use. Defaults to false | +| functionSchema | CfnAgent.FunctionSchemaProperty | 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. When specified, description, apiSchema, and actionGroupExecutor must be blank | + + +### Initializer + ```ts const actionGroupFunction = new lambda_python.PythonFunction(this, 'ActionGroupFunction', { runtime: lambda.Runtime.PYTHON_3_12, @@ -866,11 +924,10 @@ action_group_function = PythonFunction( handler="lambda_handler", ) -actionGroup = bedrock.AgentActionGroup(self, - "MyActionGroup", +actionGroup = bedrock.AgentActionGroup( name="query-library", description="Use these functions to get information about the books in the library.", - action_group_executor= bedrock.ActionGroupExecutor.from_lambda_function(action_group_function), + executor= bedrock.ActionGroupExecutor.fromlambda_function(action_group_function), enabled=True, api_schema=bedrock.ApiSchema.from_local_asset("action-group.yaml")) @@ -1201,10 +1258,38 @@ const prompt1 = new Prompt(this, 'prompt1', { description: 'my first prompt', defaultVariant: variant1, variants: [variant1], - encryptionKey: cmk, + kmsKey: cmk, }); ``` +Python + +```python + cmk = kms.Key(self, "cmk") + claude_model = bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_SONNET_V1_0 + + variant1 = bedrock.PromptVariant.text( + variant_name="variant1", + model=claude_model, + prompt_variables=["topic"], + prompt_text="This is my first text prompt. Please summarize our conversation on: {{topic}}.", + inference_configuration={ + "temperature": 1.0, + "top_p": 0.999, + "max_tokens": 2000, + } + ) + + prompt = bedrock.Prompt( + self, + "myprompt", + prompt_name="prompt1", + description="my first prompt", + default_variant=variant1, + variants=[variant1], + kms_key=cmk + ) +``` Example of a "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. @@ -1258,6 +1343,68 @@ new Prompt(stack, 'prompt1', { }); ``` +Python + +```python + +# Create KMS key + cmk = kms.Key(self, "cmk") + + # Create tool specification + tool_spec = CfnPrompt.ToolSpecificationProperty( + name="top_song", + description="Get the most popular song played on a radio station.", + input_schema=CfnPrompt.ToolInputSchemaProperty( + json={ + "type": "object", + "properties": { + "sign": { + "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": ["sign"] + } + ) + ) + + # Create tool configuration + tool_config = bedrock.ToolConfiguration( + tool_choice=bedrock.ToolChoice.AUTO, + tools=[ + CfnPrompt.ToolProperty( + tool_spec=tool_spec + ) + ] + ) + + # Create chat variant + variant_chat = bedrock.PromptVariant.chat( + variant_name="variant1", + model=bedrock.BedrockFoundationModel.ANTHROPIC_CLAUDE_3_5_SONNET_V1_0, + messages=[ + bedrock.ChatMessage.user("From now on, you speak Japanese!"), + bedrock.ChatMessage.assistant("Konnichiwa!"), + bedrock.ChatMessage.user("From now on, you speak {{language}}!"), + ], + system="You are a helpful assistant that only speaks the language you're told.", + prompt_variables=["language"], + tool_configuration=tool_config + ) + + # Create prompt + prompt = bedrock.Prompt( + self, + "prompt1", + prompt_name="prompt-chat", + description="my first chat prompt", + default_variant=variant_chat, + variants=[variant_chat], + kms_key=cmk + ) + +``` + ### Prompt Variants Prompt variants in the context of Amazon Bedrock refer to alternative configurations of a prompt, @@ -1287,6 +1434,24 @@ const variant2 = PromptVariant.text({ prompt1.addVariant(variant2); ``` +Python + +```python + + variant2 = bedrock.PromptVariant.text( + variant_name="variant2", + model=claude_model, + prompt_variables=["topic"], + prompt_text="This is my second text prompt. Please summarize our conversation on: {{topic}}.", + inference_configuration={ + "temperature": 0.5, + "topP": 0.999, + "maxTokens": 2000, + } + ) + + prompt.add_variant(variant2) +``` ### Prompt routing @@ -1344,12 +1509,21 @@ to update the version whenever a certain configuration property changes. new PromptVersion(prompt1, 'my first version'); ``` +```python +bedrock.PromptVersion(self, "my first version") + +``` + or alternatively: ```ts prompt1.createVersion('my first version'); ``` +```python +prompt.create_version("version1", "my first version") +``` + ## System defined inference profiles You can build a CrossRegionInferenceProfile using a system defined inference profile. The inference profile will route requests to the Regions defined in the cross region (system-defined) inference profile that you choose. You can find the system defined inference profiles by navigating to your console (Amazon Bedrock -> Cross-region inference) or programmatically, for instance using [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/bedrock/client/list_inference_profiles.html).