2026/08/17 - Agents for Amazon Bedrock Runtime - 1 updated api methods
Changes AgenticRetrieveStream API now supports Amazon Bedrock AgentCore Memory. Use the new memoryConfiguration parameter to continue a session from short-term memory and retrieve from long-term memory.
{'memoryConfiguration': {'memoryId': 'string',
'persistenceMode': 'DEFAULT | NONE',
'retrievalConfigs': [{'metadataFilters': [{'left': {'metadataKey': 'string'},
'operator': 'EQUALS_TO '
'| '
'EXISTS '
'| '
'NOT_EXISTS '
'| '
'BEFORE '
'| '
'AFTER '
'| '
'CONTAINS '
'| '
'GREATER_THAN '
'| '
'GREATER_THAN_OR_EQUALS '
'| '
'LESS_THAN '
'| '
'LESS_THAN_OR_EQUALS',
'right': {'metadataValue': {'dateTimeValue': 'timestamp',
'numberValue': 'double',
'stringListValue': ['string'],
'stringValue': 'string'}}}],
'namespace': 'string',
'namespacePath': 'string',
'strategyId': 'string'}],
'sessionBinding': {'actorId': 'string',
'sessionId': 'string'}}}
Response {'stream': {'traceEvent': {'attributes': {'actions': {'memoryRetrieve': {'inputQuery': {'text': 'string'},
'memoryId': 'string',
'namespace': 'string',
'namespacePath': 'string',
'strategyId': 'string'}},
'retrievalMetadata': {'retrievalType': {'BedrockAgentCoreMemory'}},
'step': {'SessionHistoryLoad'}}}}}
Retrieves information from one or more knowledge bases using an agentic approach. Agentic retrieval uses a foundation model to intelligently decompose complex queries into sub-queries and iteratively retrieve relevant information from your knowledge bases. This approach improves retrieval accuracy for complex, multi-step questions that a single retrieval pass might not fully address.
The operation returns results through a stream that includes retrieval results, trace events for visibility into the process, and a generated response synthesized from the results by default, which can be turned off.
See also: AWS API Documentation
Request Syntax
client.agentic_retrieve_stream(
agenticRetrieveConfiguration={
'foundationModelConfiguration': {
'bedrockFoundationModelConfiguration': {
'modelConfiguration': {
'modelArn': 'string'
}
},
'type': 'BEDROCK_FOUNDATION_MODEL'
},
'foundationModelType': 'CUSTOM'|'MANAGED',
'maxAgentIteration': 123,
'rerankingConfiguration': {
'bedrockRerankingConfiguration': {
'modelConfiguration': {
'modelArn': 'string'
}
},
'type': 'BEDROCK_RERANKING_MODEL'
},
'rerankingModelType': 'CUSTOM'|'MANAGED'|'NONE'
},
generateResponse=True|False,
memoryConfiguration={
'memoryId': 'string',
'persistenceMode': 'DEFAULT'|'NONE',
'retrievalConfigs': [
{
'metadataFilters': [
{
'left': {
'metadataKey': 'string'
},
'operator': 'EQUALS_TO'|'EXISTS'|'NOT_EXISTS'|'BEFORE'|'AFTER'|'CONTAINS'|'GREATER_THAN'|'GREATER_THAN_OR_EQUALS'|'LESS_THAN'|'LESS_THAN_OR_EQUALS',
'right': {
'metadataValue': {
'dateTimeValue': datetime(2015, 1, 1),
'numberValue': 123.0,
'stringListValue': [
'string',
],
'stringValue': 'string'
}
}
},
],
'namespace': 'string',
'namespacePath': 'string',
'strategyId': 'string'
},
],
'sessionBinding': {
'actorId': 'string',
'sessionId': 'string'
}
},
messages=[
{
'content': {
'text': 'string'
},
'role': 'user'|'assistant'
},
],
nextToken='string',
policyConfiguration={
'bedrockGuardrailConfiguration': {
'guardrailId': 'string',
'guardrailVersion': 'string'
}
},
retrievers=[
{
'configuration': {
'knowledgeBase': {
'knowledgeBaseId': 'string',
'retrievalOverrides': {
'filter': {
'andAll': [
{'... recursive ...'},
],
'equals': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'greaterThan': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'greaterThanOrEquals': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'in': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'lessThan': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'lessThanOrEquals': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'listContains': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'notEquals': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'notIn': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'orAll': [
{'... recursive ...'},
],
'startsWith': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
},
'stringContains': {
'key': 'string',
'value': {...}|[...]|123|123.4|'string'|True|None
}
},
'maxNumberOfResults': 123
}
}
},
'description': 'string'
},
],
userContext={
'userId': 'string'
}
)
dict
[REQUIRED]
Configuration settings for the agentic retrieval operation.
foundationModelConfiguration (dict) --
The foundation model configuration. Required when foundationModelType is CUSTOM.
bedrockFoundationModelConfiguration (dict) --
The Bedrock foundation model configuration.
modelConfiguration (dict) -- [REQUIRED]
The model configuration containing the model ARN.
modelArn (string) -- [REQUIRED]
The ARN of the Bedrock foundation model.
type (string) -- [REQUIRED]
The type of foundation model configuration.
foundationModelType (string) --
The type of foundation model to use. CUSTOM uses a specified model, MANAGED uses the service default.
maxAgentIteration (integer) --
The maximum number of agent iterations for retrieval.
rerankingConfiguration (dict) --
The reranking model configuration. Required when rerankingModelType is CUSTOM.
bedrockRerankingConfiguration (dict) --
The Bedrock reranking model configuration.
modelConfiguration (dict) -- [REQUIRED]
The model configuration containing the model ARN.
modelArn (string) -- [REQUIRED]
The ARN of the Bedrock reranking model.
type (string) -- [REQUIRED]
The type of reranking configuration.
rerankingModelType (string) --
The type of reranking model to use. CUSTOM uses a specified model, MANAGED uses the service default. If not specified, defaults to MANAGED for managed embedding knowledge bases and NONE for custom embedding knowledge bases.
boolean
Whether to generate a response based on the retrieved results.
dict
The configuration for using an Amazon Bedrock AgentCore Memory resource with this retrieval.
memoryId (string) -- [REQUIRED]
The identifier of the AgentCore Memory resource to use. The resource must exist in your account and be in the ACTIVE state.
persistenceMode (string) --
Specifies whether the agent-generated answer is written back to the given short-term memory session, and applies only when sessionBinding is set. Valid values:
DEFAULT (default) – Specifies that the question and the agent-generated answer are persisted to the session as a single event. This value requires generateResponse to be true.
NONE – Specifies that the session is left unchanged.
retrievalConfigs (list) --
Specifies the long-term memory configuration the agent can retrieve from. The agent decides whether to retrieve and composes its own query. This field currently accepts at most one entry.
(dict) --
A long-term memory namespace that the agent might retrieve memory records from.
metadataFilters (list) --
The metadata filter expressions that restrict retrieval to matching memory records. You can specify a maximum of 5 expressions.
(dict) --
A metadata filter expression.
left (dict) -- [REQUIRED]
The metadata key that the expression evaluates.
metadataKey (string) --
The metadata key to filter on.
operator (string) -- [REQUIRED]
The relationship that the metadata key and value must have for a memory record to match.
right (dict) --
The value that the expression compares the metadata key against. Supply this value for every operator except EXISTS and NOT_EXISTS.
metadataValue (dict) --
The value to compare the metadata key against.
dateTimeValue (datetime) --
A timestamp value in ISO 8601 UTC format.
numberValue (float) --
A numeric value.
stringListValue (list) --
A list of string values.
(string) --
A string value within the list.
stringValue (string) --
A string value.
namespace (string) --
The namespace prefix to filter memory records by. The agent retrieves memory records in namespaces that start with the provided prefix. You must specify either namespace or namespacePath.
namespacePath (string) --
The parent namespace to use for hierarchical retrievals. The agent retrieves all memory records whose namespace falls under the same parent hierarchy. You must specify either namespace or namespacePath.
strategyId (string) --
The extraction strategy ID that restricts retrieval to memory records produced by a single strategy. Omit this parameter to retrieve records from every strategy on the memory resource.
sessionBinding (dict) --
The short-term memory session whose history is restored for this retrieval. To persist the agent-generated answer to the session, omit persistenceMode or set it to DEFAULT. To leave the session unchanged, set persistenceMode to NONE. Supply session history through the existing messages parameter or through short-term memory, but not both.
actorId (string) -- [REQUIRED]
The identifier of the end user or agent that the session belongs to. This identifier scopes session history so that one actor's history is never returned for another. You are responsible for sending the correct actor value.
sessionId (string) -- [REQUIRED]
The identifier of the session to restore and continue. You are responsible for sending the correct session value.
list
[REQUIRED]
The list of messages for the agentic retrieval conversation.
(dict) --
A single message in the conversation.
content (dict) -- [REQUIRED]
The content of the message.
text (string) --
The text content of the message.
role (string) -- [REQUIRED]
The role of the message sender (e.g., user or assistant).
string
Opaque continuation token for paginated results.
dict
Policy configuration for guardrails and content filtering.
bedrockGuardrailConfiguration (dict) --
Configuration for Bedrock guardrails to apply during retrieval.
guardrailId (string) -- [REQUIRED]
The unique identifier of the guardrail.
guardrailVersion (string) -- [REQUIRED]
The version of the guardrail to use.
list
[REQUIRED]
The list of retrievers to use for agentic retrieval.
(dict) --
A retriever configuration.
configuration (dict) -- [REQUIRED]
The configuration for this retriever.
knowledgeBase (dict) --
Configuration for a knowledge base retriever.
knowledgeBaseId (string) -- [REQUIRED]
The unique identifier of the knowledge base.
retrievalOverrides (dict) --
Overrides for retrieval behavior such as filters and result limits.
filter (dict) --
A filter to apply to the retrieval results.
andAll (list) --
Knowledge base data sources are returned if their metadata attributes fulfill all the filter conditions inside this list.
(dict) --
Specifies the filters to use on the metadata attributes in the knowledge base data sources before returning results. For more information, see Query configurations. See the examples below to see how to use these filters.
This data type is used in the following API operations:
Retrieve request – in the filter field
RetrieveAndGenerate request – in the filter field
equals (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value matches the value in this object.
The following example would return data sources with an animal attribute whose value is cat:
"equals": { "key": "animal", "value": "cat" }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
greaterThan (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is greater than the value in this object.
The following example would return data sources with an year attribute whose value is greater than 1989:
"greaterThan": { "key": "year", "value": 1989 }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
greaterThanOrEquals (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is greater than or equal to the value in this object.
The following example would return data sources with an year attribute whose value is greater than or equal to 1989:
"greaterThanOrEquals": { "key": "year", "value": 1989 }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
in (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is in the list specified in the value in this object.
The following example would return data sources with an animal attribute that is either cat or dog:
"in": { "key": "animal", "value": ["cat", "dog"] }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
lessThan (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is less than the value in this object.
The following example would return data sources with an year attribute whose value is less than to 1989.
"lessThan": { "key": "year", "value": 1989 }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
lessThanOrEquals (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is less than or equal to the value in this object.
The following example would return data sources with an year attribute whose value is less than or equal to 1989.
"lessThanOrEquals": { "key": "year", "value": 1989 }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
listContains (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is a list that contains the value as one of its members.
The following example would return data sources with an animals attribute that is a list containing a cat member (for example ["dog", "cat"]).
"listContains": { "key": "animals", "value": "cat" }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
notEquals (dict) --
Knowledge base data sources are returned when:
It contains a metadata attribute whose name matches the key and whose value doesn't match the value in this object.
The key is not present in the document.
The following example would return data sources that don't contain an animal attribute whose value is cat.
"notEquals": { "key": "animal", "value": "cat" }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
notIn (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value isn't in the list specified in the value in this object.
The following example would return data sources whose animal attribute is neither cat nor dog.
"notIn": { "key": "animal", "value": ["cat", "dog"] }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
orAll (list) --
Knowledge base data sources are returned if their metadata attributes fulfill at least one of the filter conditions inside this list.
(dict) --
Specifies the filters to use on the metadata attributes in the knowledge base data sources before returning results. For more information, see Query configurations. See the examples below to see how to use these filters.
This data type is used in the following API operations:
Retrieve request – in the filter field
RetrieveAndGenerate request – in the filter field
startsWith (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value starts with the value in this object. This filter is currently only supported for Amazon OpenSearch Serverless vector stores.
The following example would return data sources with an animal attribute starts with ca (for example, cat or camel).
"startsWith": { "key": "animal", "value": "ca" }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
stringContains (dict) --
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the key and whose value is one of the following:
A string that contains the value as a substring. The following example would return data sources with an animal attribute that contains the substring at (for example cat). "stringContains": { "key": "animal", "value": "at" }
A list with a member that contains the value as a substring. The following example would return data sources with an animals attribute that is a list containing a member that contains the substring at (for example ["dog", "cat"]). "stringContains": { "key": "animals", "value": "at" }
key (string) -- [REQUIRED]
The name that the metadata attribute must match.
value (:ref:`document<document>`) -- [REQUIRED]
The value to which to compare the value of the metadata attribute.
maxNumberOfResults (integer) --
The maximum number of results to return.
description (string) --
A description of the retriever's purpose.
dict
Contains information about the user making the request. This is used for access control filtering to ensure that retrieval results only include documents the user is authorized to access.
userId (string) -- [REQUIRED]
The identifier of the user making the retrieval request.
dict
The response of this operation contains an :class:`.EventStream` member. When iterated the :class:`.EventStream` will yield events based on the structure below, where only one of the top level keys will be present for any given event.
Response Syntax
{
'stream': EventStream({
'accessDeniedException': {
'message': 'string'
},
'badGatewayException': {
'message': 'string',
'resourceName': 'string'
},
'conflictException': {
'message': 'string'
},
'dependencyFailedException': {
'message': 'string',
'resourceName': 'string'
},
'internalServerException': {
'message': 'string',
'reason': 'string'
},
'resourceNotFoundException': {
'message': 'string'
},
'responseEvent': {
'text': 'string'
},
'result': {
'generatedResponse': {
'answer': 'string',
'citations': [
{
'endIndex': 123,
'references': [
{
'resultIndex': 123
},
],
'startIndex': 123
},
]
},
'nextToken': 'string',
'results': [
{
'content': {
'byteContent': b'bytes',
'mimeType': 'string',
'text': 'string'
},
'metadata': {
'string': {...}|[...]|123|123.4|'string'|True|None
},
'sourceRetriever': {
'identifier': 'string'
}
},
]
},
'serviceQuotaExceededException': {
'message': 'string'
},
'throttlingException': {
'message': 'string'
},
'traceEvent': {
'attributes': {
'actions': [
{
'fullDocumentExpansion': {
'documentId': 'string',
'sourceRetriever': {
'identifier': 'string'
}
},
'memoryRetrieve': {
'inputQuery': {
'text': 'string'
},
'memoryId': 'string',
'namespace': 'string',
'namespacePath': 'string',
'strategyId': 'string'
},
'retrieve': {
'inputQuery': {
'text': 'string'
},
'sourceRetrievers': [
{
'identifier': 'string'
},
]
}
},
],
'failures': [
{
'message': 'string'
},
],
'message': 'string',
'retrievalMetadata': [
{
'identifier': 'string',
'retrievalType': 'BedrockKnowledgeBase'|'BedrockAgentCoreMemory'
},
],
'retrievalResponse': [
{
'content': {
'byteContent': b'bytes',
'mimeType': 'string',
'text': 'string'
},
'metadata': {
'string': {...}|[...]|123|123.4|'string'|True|None
},
'sourceRetriever': {
'identifier': 'string'
}
},
],
'status': 'IN_PROGRESS'|'SUCCEEDED'|'FAILED',
'step': 'Planning'|'Retrieval'|'SpeculativeRetrieval'|'FullDocumentExpansion'|'SessionHistoryLoad',
'warnings': [
{
'guardrail': {
'action': 'INTERVENED'|'NONE',
'id': 'string',
'message': 'string',
'version': 'string'
},
'message': {
'message': 'string'
}
},
]
},
'id': 'string',
'timestamp': 123
},
'validationException': {
'message': 'string'
}
})
}
Response Structure
(dict) --
Response structure for the agentic retrieve stream operation.
stream (:class:`.EventStream`) --
The output stream containing retrieval results and trace events.
accessDeniedException (dict) --
Access to the resource was denied.
message (string) --
badGatewayException (dict) --
A bad gateway error occurred.
message (string) --
resourceName (string) --
The name of the dependency that caused the issue, such as Amazon Bedrock, Lambda, or STS.
conflictException (dict) --
A conflict occurred with the current state of the resource.
message (string) --
dependencyFailedException (dict) --
A dependency failed during the operation.
message (string) --
resourceName (string) --
The name of the dependency that caused the issue, such as Amazon Bedrock, Lambda, or STS.
internalServerException (dict) --
An internal server error occurred.
message (string) --
reason (string) --
The reason for the exception. If the reason is BEDROCK_MODEL_INVOCATION_SERVICE_UNAVAILABLE, the model invocation service is unavailable. Retry your request.
resourceNotFoundException (dict) --
The specified resource was not found.
message (string) --
responseEvent (dict) --
A chunk of the generated answer. Emitted only when generateResponse is true.
text (string) --
The generated text chunk.
result (dict) --
A retrieval result event containing the retrieved items.
generatedResponse (dict) --
The generated response. Present only when generateResponse is true.
answer (string) --
The generated answer text.
citations (list) --
Citations mapping spans of the answer to supporting results.
(dict) --
A citation mapping a span of the generated answer to supporting results.
endIndex (integer) --
Character offset end (exclusive) in the answer text.
references (list) --
References to results that support this span.
(dict) --
A reference to a specific result item.
resultIndex (integer) --
Index into the results array on the same event.
startIndex (integer) --
Character offset start in the answer text.
nextToken (string) --
Opaque continuation token for paginated results.
results (list) --
The list of retrieved result items.
(dict) --
A single retrieval result item.
content (dict) --
The retrieved content.
byteContent (bytes) --
The binary content of the retrieved item.
mimeType (string) --
The MIME type of the retrieved content.
text (string) --
The text content of the retrieved item.
metadata (dict) --
Metadata associated with the retrieved item.
(string) --
The metadata key.
(:ref:`document<document>`) --
The metadata value.
sourceRetriever (dict) --
The source retriever that produced this result.
identifier (string) --
The unique identifier of the source retriever.
serviceQuotaExceededException (dict) --
The service quota has been exceeded.
message (string) --
throttlingException (dict) --
The request was throttled.
message (string) --
traceEvent (dict) --
A trace event providing visibility into the retrieval process.
attributes (dict) --
The attributes describing the trace event details.
actions (list) --
The list of actions taken during this step.
(dict) --
A single retrieval action.
fullDocumentExpansion (dict) --
Details of a full document expansion action.
documentId (string) --
The identifier of the document to expand.
sourceRetriever (dict) --
The source retriever associated with the document.
identifier (string) --
The unique identifier of the source retriever.
memoryRetrieve (dict) --
The details of a long-term memory retrieval that the agent chose to perform.
inputQuery (dict) --
The query that the agent composed.
text (string) --
The text content of the message.
memoryId (string) --
The identifier of the AgentCore Memory resource retrieved from.
namespace (string) --
The namespace prefix retrieved from, as supplied in the request. This field is present when the request specified namespace.
namespacePath (string) --
The parent namespace retrieved from hierarchically, as supplied in the request. This field is present when the request specified namespacePath.
strategyId (string) --
The extraction strategy that restricted retrieval, if the request specified one.
retrieve (dict) --
Details of the retrieve action.
inputQuery (dict) --
The input query used for retrieval.
text (string) --
The text content of the message.
sourceRetrievers (list) --
The list of source retrievers targeted by this action.
(dict) --
A source retriever.
identifier (string) --
The unique identifier of the source retriever.
failures (list) --
Failures that occurred during this step.
(dict) --
A single failure.
message (string) --
A message describing the failure.
message (string) --
A human-readable message describing the trace event.
retrievalMetadata (list) --
Metadata about the retrieval sources used.
(dict) --
Metadata for a retrieval source.
identifier (string) --
The identifier of the retrieval source.
retrievalType (string) --
The type of retrieval source.
retrievalResponse (list) --
The retrieval results from this step.
(dict) --
A single trace result item.
content (dict) --
The retrieved content.
byteContent (bytes) --
The binary content of the retrieved item.
mimeType (string) --
The MIME type of the retrieved content.
text (string) --
The text content of the retrieved item.
metadata (dict) --
Metadata associated with the retrieved item.
(string) --
The metadata key.
(:ref:`document<document>`) --
The metadata value.
sourceRetriever (dict) --
The source retriever that produced this result.
identifier (string) --
The unique identifier of the source retriever.
status (string) --
The status of the current step.
step (string) --
The current step in the retrieval process.
warnings (list) --
Warnings generated during this step.
(dict) --
A single warning.
guardrail (dict) --
A warning from a guardrail evaluation.
action (string) --
The action taken by the guardrail.
id (string) --
The unique identifier of the guardrail.
message (string) --
A message describing the guardrail evaluation result.
version (string) --
The version of the guardrail.
message (dict) --
A general warning message.
message (string) --
The warning message text.
id (string) --
The unique identifier of the trace event.
timestamp (integer) --
The timestamp when the trace event occurred.
validationException (dict) --
The request validation failed.
message (string) --