Skip to content

Commit

Permalink
chore(documentation): updated bedrock readme file (#924)
Browse files Browse the repository at this point in the history 
* chore(documentation): updated bedrock readme file

---------

Co-authored-by: dinsajwa <[email protected]>
  • Loading branch information
@dineshSajwan
dineshSajwan and dinsajwa authored Jan 30, 2025
1 parent 4f1176f commit adb7692
Showing 1 changed file with 186 additions and 12 deletions.
198 changes: 186 additions & 12 deletions src/cdk-lib/bedrock/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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<string, string> | No | Tag (KEY-VALUE) bedrock agent resource |

## Initializer

Example of `OpenSearch Serverless`:

TypeScript
Expand Down Expand Up @@ -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
Expand All @@ -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(
Expand Down Expand Up @@ -706,7 +725,7 @@ class PythonTestStack(Stack):
Python

```python
ChunkingStrategy.NONE;
ChunkingStrategy.NONE
```

#### Knowledge Base - Parsing Strategy
Expand Down Expand Up @@ -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
Expand All @@ -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:
Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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"))

Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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,
Expand Down Expand Up @@ -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

Expand Down Expand Up @@ -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).
Expand Down

0 comments on commit adb7692

Please sign in to comment.