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.

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"
}

Considerations

Keep the following in mind when using agentic retrieval: