AgentsforBedrockRuntime / Client / agentic_retrieve_stream
agentic_retrieve_stream¶
- AgentsforBedrockRuntime.Client.agentic_retrieve_stream(**kwargs)¶
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
response = 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, 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' } )
- Parameters:
agenticRetrieveConfiguration (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.
generateResponse (boolean) – Whether to generate a response based on the retrieved results.
messages (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).
nextToken (string) – Opaque continuation token for paginated results.
policyConfiguration (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.
retrievers (list) –
[REQUIRED]
The list of retrievers to use for agentic retrieval.
(dict) –
A retriever configuration.
configuration (dict) – [REQUIRED]
The configuration for this retriever.
Note
This is a Tagged Union structure. Only one of the following top level keys can be set:
knowledgeBase.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.
Note
This is a Tagged Union structure. Only one of the following top level keys can be set:
andAll,equals,greaterThan,greaterThanOrEquals,in,lessThan,lessThanOrEquals,listContains,notEquals,notIn,orAll,startsWith,stringContains.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
filterfieldRetrieveAndGenerate request – in the
filterfield
Note
This is a Tagged Union structure. Only one of the following top level keys can be set:
andAll,equals,greaterThan,greaterThanOrEquals,in,lessThan,lessThanOrEquals,listContains,notEquals,notIn,orAll,startsWith,stringContains.
equals (dict) –
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the
keyand whose value matches thevaluein this object.The following example would return data sources with an
animalattribute whose value iscat:"equals": { "key": "animal", "value": "cat" }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
keyand whose value is greater than thevaluein this object.The following example would return data sources with an
yearattribute whose value is greater than1989:"greaterThan": { "key": "year", "value": 1989 }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
keyand whose value is greater than or equal to thevaluein this object.The following example would return data sources with an
yearattribute whose value is greater than or equal to1989:"greaterThanOrEquals": { "key": "year", "value": 1989 }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
keyand whose value is in the list specified in thevaluein this object.The following example would return data sources with an
animalattribute that is eithercatordog:"in": { "key": "animal", "value": ["cat", "dog"] }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
keyand whose value is less than thevaluein this object.The following example would return data sources with an
yearattribute whose value is less than to1989."lessThan": { "key": "year", "value": 1989 }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
keyand whose value is less than or equal to thevaluein this object.The following example would return data sources with an
yearattribute whose value is less than or equal to1989."lessThanOrEquals": { "key": "year", "value": 1989 }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
keyand whose value is a list that contains thevalueas one of its members.The following example would return data sources with an
animalsattribute that is a list containing acatmember (for example["dog", "cat"])."listContains": { "key": "animals", "value": "cat" }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
keyand whose value doesn’t match thevaluein this object.The key is not present in the document.
The following example would return data sources that don’t contain an
animalattribute whose value iscat."notEquals": { "key": "animal", "value": "cat" }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
keyand whose value isn’t in the list specified in thevaluein this object.The following example would return data sources whose
animalattribute is neithercatnordog."notIn": { "key": "animal", "value": ["cat", "dog"] }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
filterfieldRetrieveAndGenerate request – in the
filterfield
Note
This is a Tagged Union structure. Only one of the following top level keys can be set:
andAll,equals,greaterThan,greaterThanOrEquals,in,lessThan,lessThanOrEquals,listContains,notEquals,notIn,orAll,startsWith,stringContains.
startsWith (dict) –
Knowledge base data sources are returned if they contain a metadata attribute whose name matches the
keyand whose value starts with thevaluein this object. This filter is currently only supported for Amazon OpenSearch Serverless vector stores.The following example would return data sources with an
animalattribute starts withca(for example,catorcamel)."startsWith": { "key": "animal", "value": "ca" }key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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
keyand whose value is one of the following:A string that contains the
valueas a substring. The following example would return data sources with ananimalattribute that contains the substringat(for examplecat)."stringContains": { "key": "animal", "value": "at" }A list with a member that contains the
valueas a substring. The following example would return data sources with ananimalsattribute that is a list containing a member that contains the substringat(for example["dog", "cat"])."stringContains": { "key": "animals", "value": "at" }
key (string) – [REQUIRED]
The name that the metadata attribute must match.
value (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.
userContext (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.
- Return type:
dict
- Returns:
The response of this operation contains an
EventStreammember. When iterated theEventStreamwill 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' } }, 'retrieve': { 'inputQuery': { 'text': 'string' }, 'sourceRetrievers': [ { 'identifier': 'string' }, ] } }, ], 'failures': [ { 'message': 'string' }, ], 'message': 'string', 'retrievalMetadata': [ { 'identifier': 'string', 'retrievalType': 'BedrockKnowledgeBase' }, ], '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', '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 (
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.
(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.
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.
(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.
Note
This is a Tagged Union structure. Only one of the following top level keys will be set:
guardrail,message. If a client receives an unknown member it will setSDK_UNKNOWN_MEMBERas the top level key, which maps to the name or tag of the unknown member. The structure ofSDK_UNKNOWN_MEMBERis as follows:'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
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) –
Exceptions
AgentsforBedrockRuntime.Client.exceptions.ResourceNotFoundExceptionAgentsforBedrockRuntime.Client.exceptions.ValidationExceptionAgentsforBedrockRuntime.Client.exceptions.InternalServerExceptionAgentsforBedrockRuntime.Client.exceptions.DependencyFailedExceptionAgentsforBedrockRuntime.Client.exceptions.BadGatewayExceptionAgentsforBedrockRuntime.Client.exceptions.ThrottlingExceptionAgentsforBedrockRuntime.Client.exceptions.AccessDeniedExceptionAgentsforBedrockRuntime.Client.exceptions.ServiceQuotaExceededException