AWS bedrock documentation change
Summary
Complete restructuring of Automated Reasoning policy documentation with new sections on document preparation, instructions writing, policy creation methods, policy review, and iterative building. Added practical examples, best practices, and API usage details.
Security assessment
The changes focus entirely on improving user guidance for policy creation workflows, document preparation, and API usage. No security vulnerabilities, incidents, or weaknesses are mentioned. The KMS encryption section remains but isn't expanded with new security information.
Diff
diff --git a/bedrock/latest/userguide/create-automated-reasoning-policy.md b/bedrock/latest/userguide/create-automated-reasoning-policy.md index aee234e57..064d044b6 100644 --- a//bedrock/latest/userguide/create-automated-reasoning-policy.md +++ b//bedrock/latest/userguide/create-automated-reasoning-policy.md @@ -5 +5 @@ -Create your Automated Reasoning policy in the consoleCreate your Automated Reasoning policy using the APIStart Automated Reasoning policy build workflow request parametersCreate Automated Reasoning policy response elementsExampleKMS permissions for Automated Reasoning policiesView Automated Reasoning policy detailsPolicy creation best practices +Prepare your source documentWrite effective instructionsCreate a policy in the consoleCreate a policy using the APIReview the extracted policyIterative policy buildingKMS permissions for Automated Reasoning policies @@ -9 +9 @@ Create your Automated Reasoning policy in the consoleCreate your Automated Reaso -When you create an Automated Reasoning policy, your input source document is translated into a set of formal logic rules and a schema of variables and types. +When you create an Automated Reasoning policy, your source document is translated into a set of formal logic rules and a schema of variables and types. This page walks you through preparing your document, creating the policy, and reviewing the results. @@ -13 +13 @@ Amazon Bedrock encrypts your Automated Reasoning policy using AWS Key Management -**Example:** If your source document contains an HR policy stating "Full-time employees who have worked for at least 1 year are eligible for parental leave," Automated Reasoning would extract variables like `IsFullTime` (boolean), `YearsOfService` (integer), and `EligibleForParentalLeave` (boolean), along with a rule that connects them. +To test and use your Automated Reasoning policy, ensure you have [the appropriate permissions](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrail-automated-reasoning-permissions.html). @@ -15 +15 @@ Amazon Bedrock encrypts your Automated Reasoning policy using AWS Key Management -###### Note +## Prepare your source document @@ -17 +17 @@ Amazon Bedrock encrypts your Automated Reasoning policy using AWS Key Management -**Tutorial video:** For a step-by-step walkthrough of creating an Automated Reasoning policy, watch the following tutorial: +Before you open the console or call the API, prepare the document that Automated Reasoning will use to extract rules and variables. The quality of your policy depends directly on the quality of this input. @@ -19 +19 @@ Amazon Bedrock encrypts your Automated Reasoning policy using AWS Key Management -[Tutorial Demo 1 - Policy creation in Automated Reasoning checks](https://youtu.be/8Y4kKv6F0JY) +### Document structure and clarity @@ -21 +21 @@ Amazon Bedrock encrypts your Automated Reasoning policy using AWS Key Management -To test and use your Automated Reasoning policy, ensure you have [the appropriate permissions](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrail-automated-reasoning-permissions.html). +Automated Reasoning checks work best with documents that contain clear, unambiguous rules. Each rule should state a condition and an outcome. Avoid vague language, subjective criteria, or rules that depend on external context not present in the document. @@ -23 +23 @@ To test and use your Automated Reasoning policy, ensure you have [the appropriat -## Create your Automated Reasoning policy in the console +**Example: Clear vs. vague rules** @@ -25 +25,4 @@ To test and use your Automated Reasoning policy, ensure you have [the appropriat - 1. In the left navigation, choose **Automated Reasoning** , and then choose **Create policy**. +Clear (good for extraction) | Vague (poor for extraction) +---|--- +"Full-time employees with at least 12 months of continuous service are eligible for parental leave." | "Eligible employees may apply for parental leave subject to manager approval." +"Refund requests must be submitted within 30 days of purchase. Items must be in original packaging." | "Refunds are handled on a case-by-case basis." @@ -27 +30 @@ To test and use your Automated Reasoning policy, ensure you have [the appropriat - 2. Enter a **Name** for the policy. +### Size limits and splitting large documents @@ -29 +32 @@ To test and use your Automated Reasoning policy, ensure you have [the appropriat - 3. (Optional) Enter a **Description** for the policy. +Source documents are limited to 5 MB in size and 50,000 characters. Images and tables in documents also count toward the character limit. @@ -31 +34 @@ To test and use your Automated Reasoning policy, ensure you have [the appropriat - 4. For **Source** , you need to provide a document that describes the rules and policies of your knowledge domain. This document should contain the business rules, policies, or guidelines that you want Automated Reasoning to validate against. For example, you might upload an HR policy document that defines employee benefits eligibility, a compliance manual that outlines regulatory requirements, or a technical specification that describes system constraints. The document should be comprehensive and clearly written, as Automated Reasoning will extract formal logic rules from this content. +If your document exceeds these limits, or if it covers multiple unrelated domains, split it into focused sections. For example, split an employee handbook into separate documents for leave policies, benefits eligibility, and expense reimbursement. Create your policy with the first section, then use iterative policy building (described later on this page) to merge additional sections into the same policy. @@ -33 +36 @@ To test and use your Automated Reasoning policy, ensure you have [the appropriat -###### Note +### Pre-process complex documents @@ -35 +38 @@ To test and use your Automated Reasoning policy, ensure you have [the appropriat -**Best practice:** For complex policies, it's better to split the content into digestible chunks and progressively import new content into a policy to make it more complex. Start with a focused subset of your rules, create and test the policy thoroughly, then gradually add more content in subsequent iterations. This approach helps you identify and resolve issues early, ensures each addition works correctly with existing rules, and makes troubleshooting easier when problems arise. +Documents that contain a lot of boilerplate, legal disclaimers, or content unrelated to the rules you want to enforce will produce noisy policies with unnecessary variables and rules. Before uploading, consider: @@ -37 +40 @@ To test and use your Automated Reasoning policy, ensure you have [the appropriat -Do the following: + * Removing headers, footers, table of contents, and appendices that don't contain rules. @@ -39 +42 @@ Do the following: - 1. For **Ingest method** , do one of the following: + * Extracting only the sections that contain the rules relevant to your use case. @@ -41 +44 @@ Do the following: - 1. Select **Upload document** , then select **Choose file**. Upload a PDF document of the source content that will serve as the basis for your policy. + * Simplifying complex tables into plain text statements where possible. @@ -43 +45,0 @@ Do the following: - 2. Select **Enter text**. Paste or enter your source content that will serve as the basis for your policy. @@ -45 +46,0 @@ Do the following: - 2. (Recommended) For **Instructions** , specify additional information on how to process your source document. While optional, providing information on how the policy will be used and what parts of the document to focus on or ignore help the logic extraction process. @@ -47 +47,0 @@ Do the following: -###### Note @@ -49 +49 @@ Do the following: -Instructions should explain what type of questions the policy will be validating, describe the structure of the input document, and give an example of the type of questions users will ask. For example: "This policy will validate HR questions about leave eligibility. The document has sections on different leave types. Users will ask questions like 'Am I eligible for parental leave if I've worked here for 9 months?'" +###### Tip @@ -51 +51 @@ Instructions should explain what type of questions the policy will be validating - 5. (Optional) For **Tags** , choose **Add new tag** to tag your policy. Tags can help you manage, filter, and search for your AWS resources. +Start with a focused subset of your rules. Create and test the policy thoroughly, then gradually add more content in subsequent iterations. This approach helps you identify and resolve issues early and makes troubleshooting easier. @@ -53 +53 @@ Instructions should explain what type of questions the policy will be validating - 6. (Optional) For **Encryption** , choose a KMS key to encrypt your policy. You can use the default service-owned key or select a customer managed key from your account. +## Write effective instructions @@ -55 +55 @@ Instructions should explain what type of questions the policy will be validating - 7. Choose **Create policy**. +When creating a policy, you can provide optional instructions that guide how Automated Reasoning processes your source document. While optional, good instructions significantly improve the quality of the extracted rules and variables. @@ -56,0 +57 @@ Instructions should explain what type of questions the policy will be validating +Effective instructions should cover three things: @@ -57,0 +59 @@ Instructions should explain what type of questions the policy will be validating + 1. **Describe the use case.** Explain what your application does and what type of content the policy will validate. For example: "This policy will validate an HR chatbot that answers employee questions about leave of absence eligibility." @@ -58,0 +61 @@ Instructions should explain what type of questions the policy will be validating + 2. **Describe the types of questions users will ask.** Give examples of realistic user questions. For example: "Users will ask questions like 'Am I eligible for parental leave if I've worked here for 9 months?' or 'How many days of bereavement leave can I take?'" @@ -60 +63 @@ Instructions should explain what type of questions the policy will be validating -## Create your Automated Reasoning policy using the API + 3. **Focus the extraction.** If your document covers multiple topics, tell Automated Reasoning checks which parts to focus on and which to ignore. For example: "Focus on sections 3 through 5 which cover leave policies. Ignore the general company overview in section 1 and the organizational chart in section 2." @@ -62 +64,0 @@ Instructions should explain what type of questions the policy will be validating -An Automated Reasoning policy is a resource in your AWS account that can be referenced using an Amazon Resource Name (ARN). Automated Reasoning policies are a container for build workflows that produce policy definitions and policy versions. Policy definitions consist of a schema of variables and a set of rules that operate on the variables. Policy versions are immutable snapshots of the default DRAFT version. Automated Reasoning policies can have up to two build workflows. Each build workflow outputs three assets: a policy definition, a quality report on the policy definition, and a build log. @@ -64 +65,0 @@ An Automated Reasoning policy is a resource in your AWS account that can be refe -Automated Reasoning policies can contain numbered, immutable versions of a definition created by calling the `CreateAutomatedReasoningPolicyVersion` API action. Automated Reasoning policies support a special version called `DRAFT` that is presented in the AWS console as "Working Draft." @@ -66 +66,0 @@ Automated Reasoning policies can contain numbered, immutable versions of a defin -To create a new policy, the first step is to use the the `CreateAutomatedReasoningPolicy` API to create the policy resource. Then, using the new policy Amazon Resource Name (ARN), you can call the `StartAutomatedReasoningPolicyBuildWorkflow` to populate a policy build from a document with a schema of variables and rules. @@ -68 +68 @@ To create a new policy, the first step is to use the the `CreateAutomatedReasoni -### Create Automated Reasoning policy request parameters +**Example instruction:** @@ -70 +69,0 @@ To create a new policy, the first step is to use the the `CreateAutomatedReasoni -The following parameters are required or optional when creating an Automated Reasoning policy: @@ -72 +71,6 @@ The following parameters are required or optional when creating an Automated Rea -`name` (required) + This policy will validate HR questions about leave eligibility. The document + has sections on different leave types (parental, medical, bereavement, personal). + Users will ask questions like "Am I eligible for parental leave if I've worked + here for 9 months?" or "Can part-time employees take bereavement leave?" + Focus on the eligibility criteria for each leave type. Capture variables that + help determine whether an employee is eligible for a specific type of leave. @@ -73,0 +78 @@ The following parameters are required or optional when creating an Automated Rea +## Create a policy in the console @@ -75 +80 @@ The following parameters are required or optional when creating an Automated Rea -The name of the Automated Reasoning policy. The name must be unique within your AWS account and Region. + 1. In the left navigation, choose **Automated Reasoning** , and then choose **Create policy**. @@ -77 +82 @@ The name of the Automated Reasoning policy. The name must be unique within your -`description` (optional) + 2. Enter a **Name** for the policy. @@ -78,0 +84 @@ The name of the Automated Reasoning policy. The name must be unique within your + 3. (Optional) Enter a **Description** for the policy. @@ -80 +86 @@ The name of the Automated Reasoning policy. The name must be unique within your -A description of the Automated Reasoning policy. Use this to provide context about the policy's purpose and the types of validations it performs. + 4. For **Source** , provide the document that describes the rules and policies of your knowledge domain. Do the following: @@ -82 +88 @@ A description of the Automated Reasoning policy. Use this to provide context abo -`clientRequestToken` (optional) + 1. For **Ingest method** , do one of the following: @@ -83,0 +90 @@ A description of the Automated Reasoning policy. Use this to provide context abo + 1. Select **Upload document** , then select **Choose file**. Upload a PDF document of the source content. @@ -85 +92 @@ A description of the Automated Reasoning policy. Use this to provide context abo -A unique, case-sensitive identifier to ensure that the operation completes no more than once. If this token matches a previous request, Amazon Bedrock ignores the request but doesn't return an error. + 2. Select **Enter text**. Paste or enter your source content. @@ -87 +94 @@ A unique, case-sensitive identifier to ensure that the operation completes no mo -`policyDefinition` (optional) + 2. (Recommended) For **Instructions** , provide guidance on how to process your source document. See Write effective instructions for what to include. @@ -88,0 +96 @@ A unique, case-sensitive identifier to ensure that the operation completes no mo + 5. (Optional) For **Tags** , choose **Add new tag** to tag your policy. @@ -90 +98 @@ A unique, case-sensitive identifier to ensure that the operation completes no mo -The policy definition that contains the formal logic rules, variables, and custom variable types used to validate foundation model responses in your application. + 6. (Optional) For **Encryption** , choose a KMS key to encrypt your policy. You can use the default service-owned key or select a customer managed key. @@ -92 +100 @@ The policy definition that contains the formal logic rules, variables, and custo -`tags` (optional) + 7. Choose **Create policy**. @@ -95 +102,0 @@ The policy definition that contains the formal logic rules, variables, and custo -A list of tags to associate with the Automated Reasoning policy. Tags help you organize and manage your policies. @@ -97 +103,0 @@ A list of tags to associate with the Automated Reasoning policy. Tags help you o -`kmsKeyId` (optional) @@ -98,0 +105 @@ A list of tags to associate with the Automated Reasoning policy. Tags help you o +###### Tip @@ -100 +107 @@ A list of tags to associate with the Automated Reasoning policy. Tags help you o -The KMS key identifier for encrypting the Automated Reasoning policy. You can use the key ID, key ARN, alias name, or alias ARN. If you don't specify a KMS key, Amazon Bedrock uses a service-owned key to encrypt your policy. +If your application expects a specific set of variables, you can pre-define the schema before importing content. Use the `CreateAutomatedReasoningPolicy` API or CloudFormation to create a policy with a `policyDefinition` that contains your desired variables and types but no rules. Then use Iterative policy building to import your source document. Automated Reasoning will use your predefined schema as a starting point and add rules that reference your variables. @@ -102 +109 @@ The KMS key identifier for encrypting the Automated Reasoning policy. You can us -### Create Automated Reasoning policy response elements +## Create a policy using the API @@ -104 +111 @@ The KMS key identifier for encrypting the Automated Reasoning policy. You can us -The API returns the following information: +An Automated Reasoning policy is a resource in your AWS account identified by an Amazon Resource Name (ARN). Creating a policy through the API is a two-step process: first create the policy resource, then start a build workflow to extract rules from your document. @@ -106 +113 @@ The API returns the following information: -`policyArn` +### Step 1: Create the policy resource @@ -107,0 +115 @@ The API returns the following information: +Use the `CreateAutomatedReasoningPolicy` API to create the policy resource. @@ -109 +117 @@ The API returns the following information: -The Amazon Resource Name (ARN) of the Automated Reasoning policy that you created. +`name` (required) @@ -111 +118,0 @@ The Amazon Resource Name (ARN) of the Automated Reasoning policy that you create -`version` @@ -112,0 +120 @@ The Amazon Resource Name (ARN) of the Automated Reasoning policy that you create +The name of the policy. Must be unique within your AWS account and Region. @@ -114 +122 @@ The Amazon Resource Name (ARN) of the Automated Reasoning policy that you create -The version of the Automated Reasoning policy. The initial version is `DRAFT`. +`description` (optional) @@ -116 +123,0 @@ The version of the Automated Reasoning policy. The initial version is `DRAFT`. -`name` @@ -117,0 +125 @@ The version of the Automated Reasoning policy. The initial version is `DRAFT`. +A description of the policy's purpose. @@ -119 +127 @@ The version of the Automated Reasoning policy. The initial version is `DRAFT`. -The name of the Automated Reasoning policy. +`policyDefinition` (optional) @@ -121 +128,0 @@ The name of the Automated Reasoning policy. -### Example @@ -123 +130,18 @@ The name of the Automated Reasoning policy. -The following example shows how to create an Automated Reasoning policy using the AWS CLI: +An initial policy definition with rules, variables, and custom types. Use this if you already have a schema you want to start from. + +`kmsKeyId` (optional) + + +The KMS key identifier for encrypting the policy. If not specified, Amazon Bedrock uses a service-owned key. + +`tags` (optional) + + +Tags to associate with the policy. + +`clientRequestToken` (optional) + + +An idempotency token to ensure the operation completes no more than once. + +**Example:** @@ -127 +151,2 @@ The following example shows how to create an Automated Reasoning policy using th - --name "DeleteMe" \ + --name "MyHRPolicy" \ + --description "Validates HR chatbot responses about leave eligibility" \ @@ -135,3 +160,3 @@ Example response: