AWS bedrock documentation change
Summary
Updated documentation for Converse API guardrail integration with improved examples, terminology consistency, and clarification of content evaluation behavior
Security assessment
The changes enhance documentation about guardrail content evaluation mechanisms (guardContent blocks, contextual grounding checks) and clarify security filtering behavior. While it explains security-related features, there's no evidence of addressing a specific vulnerability.
Diff
diff --git a/bedrock/latest/userguide/guardrails-use-converse-api.md b/bedrock/latest/userguide/guardrails-use-converse-api.md index 8b469b188..a71c05492 100644 --- a//bedrock/latest/userguide/guardrails-use-converse-api.md +++ b//bedrock/latest/userguide/guardrails-use-converse-api.md @@ -5 +5 @@ -Calling the Converse API with guardrailsProcessing the response when using the Converse APIExample code for using Converse API with guardrails +Call the Converse API with guardrailsProcessing the response when using the Converse APICode example for using Converse API with guardrails @@ -7 +7 @@ Calling the Converse API with guardrailsProcessing the response when using the C -# Include a guardrail with Converse API +# Include a guardrail with the Converse API @@ -13 +13 @@ You can use a guardrail to guard conversational apps that you create with the Co - * Calling the Converse API with guardrails + * Call the Converse API with guardrails @@ -17 +17 @@ You can use a guardrail to guard conversational apps that you create with the Co - * Example code for using Converse API with guardrails + * Code example for using Converse API with guardrails @@ -22 +22 @@ You can use a guardrail to guard conversational apps that you create with the Co -## Calling the Converse API with guardrails +## Call the Converse API with guardrails @@ -28 +28 @@ To use a guardrail, you include configuration information for the guardrail in c - * Configuring the guardrail to work with Converse API + * Configure a guardrail to work with the Converse API @@ -30 +30 @@ To use a guardrail, you include configuration information for the guardrail in c - * Guarding a message to assess harmful content using APIs + * Evaluate only specific content in a message @@ -39 +39 @@ To use a guardrail, you include configuration information for the guardrail in c -### Configuring the guardrail to work with Converse API +### Configure a guardrail to work with the Converse API @@ -41 +41 @@ To use a guardrail, you include configuration information for the guardrail in c -You specify configuration information for the guardrail in the `guardrailConfig` input parameter. The configuration includes the ID and the version of the guardrail that you want to use. You can also enable tracing for the guardrail, which provides information about the content that the guardrail blocked. +You specify guardrai configuration information in the `guardrailConfig` input parameter. The configuration includes the ID and the version of the guardrail that you want to use. You can also enable tracing for the guardrail, which provides information about the content that the guardrail blocked. @@ -54 +54 @@ If you use `ConverseStream`, you pass a [GuardrailStreamConfiguration](https://d -### Guarding a message to assess harmful content using APIs +### Evaluate only specific content in a message @@ -56 +56,7 @@ If you use `ConverseStream`, you pass a [GuardrailStreamConfiguration](https://d -When you pass a message ([Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html)) to a model, the guardrail assesses the content in the message. Optionally, you can guard selected content in the message by specifying the `guardContent` ([GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)) field. The guardrail evaluates only the content in the `guardContent` field and not the rest of the message. This is useful for having the guardrail assess only the most recent message in a conversation, as shown in the following example. +When you pass a [Message](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_Message.html) to a model, your guardrail assesses the content in the message. You also can asses specific parts of a message by using the `guardContent` ([GuardrailConverseContentBlock](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_GuardrailConverseContentBlock.html)) field. + +###### Tip + +Using the `guardContent` field is similar to using input tags with [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) and [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html). For more information, see [Apply tags to user input to filter content](./guardrails-tagging.html). + +For example, the following guardrail evaluates only the content in the `guardContent` field and not the rest of the message. This is useful for having the guardrail assess only the most recent message in a conversation, as shown in the following example. @@ -90 +96 @@ When you pass a message ([Message](https://docs.aws.amazon.com/bedrock/latest/AP -Another use is providing additional context for a message, without having the guardrail assess that additional context. In the following example, the guardrail only assesses `"Create a playlist of heavy metal songs"` and ignores the `"Only answer with a list of songs"`. +Another use case of `guardContent` is providing additional context for a message without your guardrail assessing that context. In the following example, the guardrail only assesses `"Create a playlist of heavy metal songs"` and ignores the `"Only answer with a list of songs"`. @@ -93 +99 @@ Another use is providing additional context for a message, without having the gu - [ + messages = [ @@ -111 +117,4 @@ Another use is providing additional context for a message, without having the gu -###### Note +If content isn't in a `guardContent` block, that doesn't necessarily mean it won't be evaluated. This behavior depends on what filtering polices the guardrail uses. + +The following example shows two `guardContent` blocks with [contextual grounding checks](./guardrails-contextual-grounding-check.html) (based on the `qualifiers` fields). The contextual grounding checks in the guardrail will only evaluate the content in these blocks. However, if the guardrail also has a [word filter](./guardrails-content-filters.html) that blocks the word "background", the text "Some additional background information." will still be evaluated, even though it's not in a `guardContent` block. + @@ -113 +122,23 @@ Another use is providing additional context for a message, without having the gu -Using the `guardContent` field is analogous to using input tags with [InvokeModel](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModel.html) and [InvokeModelWithResponseStream](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_runtime_InvokeModelWithResponseStream.html). For more information, see [Apply tags to user input to filter content](./guardrails-tagging.html). + [{ + "role": "user", + "content": [{ + "guardContent": { + "text": { + "text": "London is the capital of UK. Tokyo is the capital of Japan.", + "qualifiers": ["grounding_source"] + } + } + }, + { + "text": "Some additional background information." + }, + { + "guardContent": { + "text": { + "text": "What is the capital of Japan?", + "qualifiers": ["query"] + } + } + } + ] + }] @@ -137 +168 @@ How the guardrail assesses `guardContent` field behaves differently between syst -| System prompt has Guardrail block | System prompt does not have Guardrail block +| System prompt has guardrail block | System prompt doesn't have guardrail block @@ -139,2 +170,2 @@ How the guardrail assesses `guardContent` field behaves differently between syst -**Messages have Guardrail block** | System: Guardrail investigates content in Guardrail block Messages: Guardrail investigates content in Guardrail block | System: Guardrail investigates nothing Messages: Guardrail investigates content in Guardrail block -**Messages does not have Guardrail block** | System: Guardrail investigates content in Guardrail block Messages: Guardrail investigates everything | System: Guardrail investigates nothing Messages: Guardrail investigates everything +**Messages have guardrail block** | System: Guardrail investigates content in guardrail block Messages: Guardrail investigates content in guardrail block | System: Guardrail investigates nothing Messages: Guardrail investigates content in guardrail block +**Messages don't have guardrail block** | System: Guardrail investigates content in guardrail block Messages: Guardrail investigates everything | System: Guardrail investigates nothing Messages: Guardrail investigates everything @@ -214 +245 @@ The following partial response shows the blocked content text and the trace from -## Example code for using Converse API with guardrails +## Code example for using Converse API with guardrails