AWS Security ChangesHomeSearch

AWS bedrock: Document retrieval instructions for agentic retrieval, incl. IAM/KMS permissions

Service: bedrock · 2026-10-20 · Documentation medium

File: bedrock/latest/userguide/kb-test-agentic-retrieve.md · Type: iam

Summary

Adds a new section explaining how to apply retrieval instructions to agentic retrieval requests (retrievalInstructionConfiguration with retrievalInstructionId/version, ACTIVE-state and same-account/Region validation, appliedInstruction trace attribute), plus the required IAM permission bedrock:GetRetrievalInstruction and, for customer managed key-encrypted instructions, kms:Decrypt on the key and a key policy allowing Bedrock. Also updates the planning/response-generation steps, parameter table, and navigation links.

Security assessment

The change is feature documentation for retrieval instructions, but it explicitly documents least-privilege IAM (bedrock:GetRetrievalInstruction scoped to a retrieval-instruction ARN) and encryption access (kms:Decrypt on a customer managed key plus key policy requirements), which are security-relevant configuration guidance rather than a fix for a specific vulnerability or incident.

Evidence

+        "Action": "bedrock:GetRetrievalInstruction",

Diff

diff --git a/bedrock/latest/userguide/kb-test-agentic-retrieve.md b/bedrock/latest/userguide/kb-test-agentic-retrieve.md
index 3b04fbe..16bd62f 100644
--- a//bedrock/latest/userguide/kb-test-agentic-retrieve.md
+++ b//bedrock/latest/userguide/kb-test-agentic-retrieve.md
@@ -7 +7 @@
-How agentic retrieval worksPrerequisitesQuery a knowledge base with agentic retrievalAgentic retrieval responseUse AgentCore Memory with agentic retrievalRequired permissions for agentic retrievalConsiderations
+How agentic retrieval worksPrerequisitesQuery a knowledge base with agentic retrievalAgentic retrieval responseUse AgentCore Memory with agentic retrievalUse retrieval instructions with agentic retrievalRequired permissions for agentic retrievalConsiderations
@@ -21 +21 @@ When you send a request to the `AgenticRetrieveStream` API, the following proces
-  2. **Planning** – The foundation model analyzes your query and creates a plan to decompose it into one or more sub-queries. Each sub-query targets a specific source that you configured, either a knowledge base retriever or AgentCore Memory long-term memory. After retrieval results are collected, the foundation model evaluates whether they are sufficient to answer the original query. If not, it plans and executes additional retrieval iterations, up to the configured maximum.
+  2. **Planning** – The foundation model analyzes your query and creates a plan to decompose it into one or more sub-queries. Each sub-query targets a specific source that you configured, either a knowledge base retriever or AgentCore Memory long-term memory. After retrieval results are collected, the foundation model evaluates whether they are sufficient to answer the original query. If not, it plans and executes additional retrieval iterations, up to the configured maximum. When the request applies a retrieval instruction, the plan follows the instruction's `retrievalGuidance`.
@@ -27 +27 @@ When you send a request to the `AgenticRetrieveStream` API, the following proces
-  5. **Response generation** – When `generateResponse` is set to `true` (the default), the foundation model synthesizes a natural-language answer from the retrieved results. Amazon Bedrock streams the answer back to you through `responseEvent` events. When `sessionBinding` is set and `persistenceMode` is `DEFAULT`, Amazon Bedrock persists the question and the generated answer to the session.
+  5. **Response generation** – When `generateResponse` is set to `true` (the default), the foundation model synthesizes a natural-language answer from the retrieved results. Amazon Bedrock streams the answer back to you through `responseEvent` events. When `sessionBinding` is set and `persistenceMode` is `DEFAULT`, Amazon Bedrock persists the question and the generated answer to the session. When the request applies a retrieval instruction, its `persona`, `answerFormat`, and `answerPolicy` fields shape the answer.
@@ -64,0 +65 @@ generateResponse | A boolean field that, when set to `true` (the default), instr
+retrievalInstructionConfiguration | Applies a retrieval instruction that steers how the agent searches and answers. Specify a `retrievalInstructionId` and, optionally, a `version`. For more information, see Use retrieval instructions with agentic retrieval.  
@@ -96 +97 @@ The `AgenticRetrieveStream` response is a stream that contains the following eve
-    * **Planning** – Indicates the foundation model is analyzing the query and creating sub-queries. Includes the planned actions and target sources. Each action is either a `retrieve` action targeting a knowledge base or a `memoryRetrieve` action targeting long-term memory, which includes the composed query and the `memoryId`.
+    * **Planning** – Indicates the foundation model is analyzing the query and creating sub-queries. Includes the planned actions and target sources. Each action is either a `retrieve` action targeting a knowledge base or a `memoryRetrieve` action targeting long-term memory, which includes the composed query and the `memoryId`. When the request applies a retrieval instruction, the first **Planning** event includes an `appliedInstruction` attribute with the ID of the instruction and the version that was applied.
@@ -180,0 +182,52 @@ How the retrieval itself appears depends on when it happens. When the foundation
+## Use retrieval instructions with agentic retrieval
+
+A retrieval instruction steers how agentic retrieval searches your knowledge bases and how it answers. You create the instruction once, Amazon Bedrock reviews it, and then you reference it from your requests. Retrieval instructions are optional. To create, review, version, and delete retrieval instructions, see [Create and manage retrieval instructions](./kb-test-agentic-retrieve-instruction.html).
+
+To apply one, supply the `retrievalInstructionConfiguration` field with the `retrievalInstructionId` of an `ACTIVE` instruction in your account and Region. To pin the behavior, set `version` to a version number. When you omit `version`, Amazon Bedrock applies `DRAFT`, the current reviewed content. If the instruction doesn't exist in your account, isn't `ACTIVE`, or the version you specify doesn't exist, the request fails with a `ValidationException` before any events are streamed.
+
+In the following example, replace `abcde12345` with your retrieval instruction ID and `3` with the version to apply:
+    
+    
+    {
+        "messages": [
+            {
+                "content": {
+                    "text": "How do I reset the Model X200 to factory settings?"
+                },
+                "role": "user"
+            }
+        ],
+        "retrievers": [
+            {
+                "configuration": {
+                    "knowledgeBase": {
+                        "knowledgeBaseId": "KB12345678"
+                    }
+                }
+            }
+        ],
+        "agenticRetrieveConfiguration": {
+            "foundationModelType": "MANAGED",
+            "rerankingModelType": "MANAGED"
+        },
+        "retrievalInstructionConfiguration": {
+            "retrievalInstructionId": "abcde12345",
+            "version": "3"
+        }
+    }
+
+To confirm which instruction and version a request used, read the `appliedInstruction` attribute on the first **Planning** trace event. The following example shows the attributes of that trace event:
+    
+    
+    {
+        "step": "Planning",
+        "status": "IN_PROGRESS",
+        "message": "Agent planning started",
+        "appliedInstruction": {
+            "id": "abcde12345",
+            "version": "3"
+        }
+    }
+
+For more information about trace events, see Agentic retrieval response.
+
@@ -246,0 +300,22 @@ If the memory resource is encrypted with a customer managed key, add the followi
+If you apply a retrieval instruction with agentic retrieval, add the following permission:
+    
+    
+    {
+        "Effect": "Allow",
+        "Action": "bedrock:GetRetrievalInstruction",
+        "Resource": "arn:aws:bedrock:region:account-id:retrieval-instruction/retrieval-instruction-id"
+    }
+
+Versions don't have their own ARN, so this permission also covers the version that you specify in `version`.
+
+If the retrieval instruction is encrypted with a customer managed key, add the following permission on that key:
+    
+    
+    {
+        "Effect": "Allow",
+        "Action": "kms:Decrypt",
+        "Resource": "arn:aws:kms:region:account-id:key/key-id"
+    }
+
+The key policy must also allow the caller to use the key through Amazon Bedrock. For the key policy, see [Encryption of retrieval instructions](./encryption-kb.html#encryption-kb-retrieval-instruction). For the permissions to create and manage retrieval instructions, see [Required permissions for retrieval instructions](./kb-test-agentic-retrieve-instruction.html#kb-retrieval-instruction-permissions).
+
@@ -270,0 +346,2 @@ Keep the following in mind when using agentic retrieval:
+  * A retrieval instruction must be `ACTIVE` and in the same account and Region as the request. For more information, see Use retrieval instructions with agentic retrieval.
+
@@ -282 +359 @@ Retrieve document content
-Configure and customize queries
+Retrieval instructions