Services or capabilities described in AWS documentation might vary by Region. To see the differences applicable to the AWS European Sovereign Cloud Region, see the AWS European Sovereign Cloud User Guide.

Use agentic retrieval to query a knowledge base

Agentic retrieval uses a foundation model to intelligently decompose complex queries into sub-queries, iteratively retrieve relevant information from your knowledge bases, and evaluate whether the retrieved results are sufficient to answer the original query. This approach improves retrieval accuracy for complex, multi-step questions that a single retrieval pass might not fully address.

For example, given the query "Which magazine was started first, Arthur's Magazine or First for Women?", agentic retrieval breaks this into separate sub-queries such as "When was Arthur's Magazine founded?" and "When was First for Women founded?", retrieves results for each, and evaluates whether the combined results are sufficient.

How agentic retrieval works

When you send a request to the AgenticRetrieveStream API, the following process occurs:

Prerequisites

Before you can use agentic retrieval, you must have the following:

Query a knowledge base with agentic retrieval

To use agentic retrieval, send an AgenticRetrieveStream request. The response is a stream that includes retrieval results and trace events.

The following table describes the key request fields:

For the full request and response syntax, see AgenticRetrieveStream in the API reference.

Agentic retrieval response

The AgenticRetrieveStream response is a stream that contains the following event types:

Use AgentCore Memory with agentic retrieval

You can give agentic retrieval access to an Amazon Bedrock AgentCore Memory resource. With memory access, a retrieval can continue an earlier session and draw on what the agent has learned in previous ones. Supply the memoryConfiguration field with the memoryId of a memory resource in your account that is in the ACTIVE state.

Memory is optional. A memoryConfiguration that sets only a memoryId is not valid. When you supply memoryConfiguration, you must use the memory resource in at least one of the following two ways:

Supply namespaces exactly as they are configured on the memory strategy, with placeholders already resolved. For example, if the strategy defines the namespace /strategy/{memoryStrategyId}/actor/{actorId}, supply the resolved value rather than the template. For more information about namespaces, strategies, and memory records, see Memory terminology in the Amazon Bedrock AgentCore Developer Guide.

When sessionBinding is set, use persistenceMode to control whether the current exchange is written back to the session:

The following example restores an earlier session, gives the agent access to that actor's long-term memory, and persists the exchange back to the session:

{
    "messages": [
        {
            "content": {
                "text": "What did we decide about the migration timeline?"
            },
            "role": "user"
        }
    ],
    "retrievers": [
        {
            "configuration": {
                "knowledgeBase": {
                    "knowledgeBaseId": "KB12345678"
                }
            }
        }
    ],
    "agenticRetrieveConfiguration": {
        "foundationModelType": "MANAGED",
        "rerankingModelType": "MANAGED"
    },
    "memoryConfiguration": {
        "memoryId": "projectAssistantMemory-1a2b3c4d5e",
        "sessionBinding": {
            "actorId": "user-123",
            "sessionId": "session-456"
        },
        "retrievalConfigs": [
            {
                "namespace": "/strategy/summarization-1a2b3c4d5e/actor/user-123"
            }
        ],
        "persistenceMode": "DEFAULT"
    }
}

The response stream reports memory activity. The restore appears as a Session history load trace event. The records that long-term memory returns appear on the Retrieval trace event with a source type of BedrockAgentCoreMemory, whichever step retrieved them.

How the retrieval itself appears depends on when it happens. When the foundation model chooses to search memory (typical on a continued session), the retrieval appears as a memoryRetrieve action on the Planning trace event. On a new session, the agent can instead retrieve long-term memory during Speculative retrieval, before the first planning step, in which case it emits no memoryRetrieve action. For more information, see Agentic retrieval response.

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.

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.

Required permissions for agentic retrieval

To use the AgenticRetrieveStream API, the calling IAM identity must have the following permissions:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "bedrock:AgenticRetrieveStream",
            "Resource": "*"
        },
        {
            "Effect": "Allow",
            "Action": [
                "bedrock:Retrieve",
                "bedrock:GetDocumentContent"
            ],
            "Resource": "arn:aws:bedrock:region:account-id:knowledge-base/*"
        },
        {
            "Effect": "Allow",
            "Action": "bedrock:InvokeModelWithResponseStream",
            "Resource": "*"
        }
    ]
}

If you use guardrails with agentic retrieval, add the following permissions:

{
    "Effect": "Allow",
    "Action": [
        "bedrock:GetGuardrail",
        "bedrock:ApplyGuardrail"
    ],
    "Resource": "*"
}

If you use an AgentCore Memory resource with agentic retrieval, add the following permissions:

{
    "Effect": "Allow",
    "Action": [
        "bedrock-agentcore:GetMemory",
        "bedrock-agentcore:ListEvents",
        "bedrock-agentcore:RetrieveMemoryRecords",
        "bedrock-agentcore:CreateEvent"
    ],
    "Resource": "arn:aws:bedrock-agentcore:region:account-id:memory/memory-id"
}

bedrock-agentcore:ListEvents is required only when you set sessionBinding. bedrock-agentcore:RetrieveMemoryRecords is required only when you set retrievalConfigs. bedrock-agentcore:CreateEvent is required only when persistenceMode is DEFAULT.

If the memory resource 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"
}

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. For the permissions to create and manage retrieval instructions, see Required permissions for retrieval instructions.

Considerations

Keep the following in mind when using agentic retrieval: